Kick off your book project in 3 hours! Live workshop on Zoom. You’ll leave with a real book project, progress on your first chapter, and a clear plan to keep going. Saturday, May 16, 2026. Learn more…

Leanpub Header

Skip to main content

Clarity Engineer : Code Is the Side Effect

Building AI-Driven Systems Where Engineering Judgment Is the Real Work

Code Is the Side Effect

"Software engineers are not primarily code writers. We are clarity traders — and that hasn't changed."

You've seen the demos. The AI builds a whole feature from a sentence. The agent writes tests, fixes the failing ones, opens the PR. It's remarkable.

Then you come back three months later. The codebase is a tangle. Nobody knows why anything is the way it is. The agent that built it has no memory of what it decided or why. And every time you ask it to add something new, it breaks two things you didn't know were connected.

This is the pattern that nobody talks about. AI coding tools make the easy parts of engineering dramatically easier. They leave the hard parts untouched — and they create new hard parts that didn't exist before.

Ways of Working is the book for engineers who want to work with AI agents rather than be gradually replaced by them — who understand that the tools are genuinely powerful and genuinely limited, and want to build practices that get the most from each.

What you will actually learn

The world model framework. Before an agent can build anything well, it needs to understand what it's building and why. This book teaches you to give agents what they need: a structured, queryable representation of your architecture, your component contracts, your behavior specifications, and your code patterns. No world model = no sustained agentic development.

Intent documentation. The most expensive bug in agentic codebases is not a hallucination — it's a decision made without context. Why is this rule here? Why is this boundary where it is? Agents can't infer rationale from code. You have to write it down.

Spec-Kit and formal specifications. GitHub's Spec-Kit brings machine-readable, traceable, CI-verified specifications to engineering teams. This book shows how to use it to turn requirements into agent inputs that are precise enough to generate correct implementations.

Graph explainers. Tools like Graphify and Understand-Anything transform codebases and documents into queryable knowledge graphs — giving agents navigable context instead of flat text. This is the memory substrate that makes multi-agent systems reliable at scale.

Agent architecture that holds. What makes an agent coherently itself? When do file-based agent systems break down and what replaces them? How does constraint-based coordination (borrowed from holocracy) solve the autonomy-coherence problem that has stumped AI researchers for decades?

Claude Code, for real. A complete treatment of Claude Code's CLAUDE.md convention, permission model, hooks, and slash commands. Plus the oh-my-claudecode ecosystem: 15+ specialized agents, workflow orchestration patterns (autopilot, ralph, ultrawork), and the skills framework for team-specific automation.

The AI-native organization. What genuine AI-native teams look like beneath the marketing. How to hire, structure, and lead them. What language-oriented programming and constrained natural language mean for the future of the human-code relationship.

Who it's for

Engineers who are past the "should I use AI?" question and into the "how do I use it without losing my engineering integrity?" question.

Senior engineers. Engineering managers. Technical leaders. People who have noticed that the more they delegate to AI, the less certain they feel — and who want to understand why.

From the Author

I've been building production systems with AI agents for years. Not demos — systems that had to work reliably across months, maintain themselves as requirements changed, and produce outputs that engineers could understand and defend.

That experience has made me skeptical in both directions.

Skeptical of the "AI will do everything" vision — because I've watched too many AI-generated codebases collapse under the weight of accumulated misunderstanding.

Equally skeptical of the "nothing fundamentally changed" position — because the engineers who treat AI coding tools as just faster autocomplete are making a category error they'll pay for in months of maintenance debt.

Something genuinely new is happening. This book is my attempt to think about it clearly.

Minimum price

$27.00

$43.00

You pay

Author earns

$
PDF
EPUB
WEB
About

About

About the Book

Something strange happened in the years between 2023 and 2026.

Every week, a new headline announced that software engineers were obsolete. Every week, the same software engineers downloaded the latest AI coding tool, integrated it into their workflows, and went back to doing the hard work of understanding complex systems, managing ambiguous requirements, and making thousands of tiny judgment calls that no model had yet learned to make reliably.

This book is about that gap — and how to close it.

Ways of Working is a field guide for engineers who are serious about their craft and want to navigate the AI transition without losing themselves in it. It does not give you prompt templates or tool tutorials. Those become obsolete in months. Instead, it offers frameworks and practices that remain relevant regardless of which specific models and tools dominate the next cycle.

What You Will Learn

Why clarity — not code — is your core product. Software engineers are not primarily code writers. We are clarity traders: we translate the ambiguity of business requirements into the precision that machines demand. AI handles the translation step faster than ever — but only if you first achieve the clarity that makes translation possible.

How to build world models that agents can actually use. The single most common failure mode in agentic development is not hallucination — it is missing context. This book teaches a four-layer framework for giving agents what they need: architecture constraints, component contracts, behavior specifications, and code patterns. Including deep dives into GitHub's Spec-Kit for machine-readable specifications, and graph-based knowledge systems (Graphify, Understand-Anything) that make complex domains navigable.

What agent architecture actually requires. Agent identity, the scaling wall that breaks file-based memory in production, constraint-based coordination borrowed from holocracy, and the emerging Networked Agentic Organization model for human-AI teams.

How to use Claude Code and the plugin ecosystem effectively. A complete guide to Claude Code's CLAUDE.md convention, permission model, slash commands, and hooks — plus the oh-my-claudecode ecosystem with its 15+ specialized agents, workflow orchestration patterns, and skills framework. Focused on patterns that work in production, not demos.

What AI-native organizations actually look like. Beneath the marketing, genuine AI-native organizations have specific characteristics: data quality obsession, research as daily practice, hiring profiles that differ from traditional software engineering, and cultural patterns that compound in capability over time.

Who This Book Is For
  • Senior engineers trying to understand what "agentic development" actually means in practice
  • Engineering managers building teams that will work alongside AI coding agents every day
  • Technical leaders trying to distinguish genuine AI-native practices from expensive hype
  • Individual practitioners who have noticed that the more they rely on AI, the less certain they feel about what they actually know — and want to understand why

This book assumes you are already a competent engineer. It does not explain what a function is. It does explain what changes when an AI agent writes the functions for you.

What Makes This Book Different

The ideas in this book come from building real systems with AI agents — not demos, but production systems that had to work reliably, maintain themselves over time, and evolve as requirements changed.

This experience produces a specific kind of skepticism: skeptical of the "AI will do everything" narrative (because AI-generated codebases regularly collapse under accumulated misunderstanding), and equally skeptical of the "nothing fundamentally changed" narrative (because the engineers who treat AI tools as just faster autocomplete are making a costly category error).

Something genuinely new is happening. The question is whether you can think about it clearly enough to benefit from it.

That is what this book is for.

About the Author

Volodymyr Pavlyshyn is a software architect and researcher with deep expertise in agentic AI systems, graph databases, self-sovereign identity, and knowledge representation.

He is the author of LadybugDB (Leanpub), a practical guide to graph database and vector search architectures for agent memory systems. He writes regularly about agent identity, world models, networked agentic organizations, and the organizational implications of AI-driven engineering.

His background in hardware engineering gives him an unusual perspective: the principle that the problem defines the algorithm, not vice versa — and the habit of building new tools when existing ones don't fit the problem.

Table of Contents

Part I: The Great Mindset Shift

  1. Beyond Vibe Coding — You Are a Clarity Trader
  2. The Paradox of Intensification
  3. Cognitive Sovereignty — Renting vs. Owning Your Intelligence

Part II: World Models and the Architecture of Intent 4. World Models for Agentic Coding — The Four-Layer Framework 5. Intent Documentation — Why Agents Need Your Why 6. Spec-Kit — Formal Specifications for the Agent Era 7. Graph Explainers — Making Knowledge Machine-Readable

Part III: Agent Architecture 8. Agent Identity — Beyond Names and Roles 9. The Scaling Wall — From Files to Databases in Multi-Agent Systems 10. Holocracy as Constraint Architecture for AI Agents 11. Networked Agentic Organizations

Part IV: The Coding Agent Toolkit 12. Claude Code — The New Command Line for AI Engineers 13. Oh-My-Claude Code and the Plugin Ecosystem 14. Claude Code Best Practices — Patterns That Actually Work

Part V: The AI-Native Organization 15. Building AI-Native Teams 16. Language-Oriented Programming and Constrained Natural Language 17. The Future of Human-Agent Collaboration

Epilogue: The Right to Build Before Your Time

Author

About the Author

Volodymyr Pavlyshyn

Hey I am Volodymyr 

Seasoned Developer's Journey from COBOL to Web 3.0, SSI, Privacy First Edge AI, and Beyond

 As a seasoned developer with over 20 years of experience, I have worked with various programming languages, including some that are considered "dead," such as COBOL and Smalltalk. However, my passion for innovation and embracing cutting-edge technology has led me to focus on the emerging fields of Web 5.0, Self-Sovereign Identity (SSI),AI Agents, Knowledge Graphs, Agentiic memory systems, and the architecture of a decentralized world that empowers data democratization.

A firm believer in the potential of agent systems and the concept of a "soft" internet, I am dedicated to exploring and promoting these transformative ideas. In addition to writing, I also enjoy sharing my knowledge and insights through videoblogging. Most of my Medium posts serve as supplementary content to the videos on my YouTube channel, which you can explore here: https://www.youtube.com/c/VolodymyrPavlyshyn. 

Join me on this exciting journey as we delve into the future of technology and the possibilities it holds.

Contents

Table of Contents

The Clarity Engineer

  1. Code Is the Side Effect

Introduction: The Engineer Who Survived the Hype

  1. Who This Book Is For
  2. What You Will Find Here
  3. A Note on Perspective

Part I: The Great Mindset Shift

Chapter 1: Beyond Vibe Coding — You Are a Clarity Trader

  1. What Engineers Actually Do
  2. The Two Sides of the Translation
  3. What AI Actually Changes
  4. The New Role: Clarity Trader in the AI Era
  5. The Clarity Forcing Functions
  6. A Brief Taxonomy of Clarity
  7. Practical Recommendations

Chapter 2: The Paradox of Intensification

  1. The Intensification Trap
  2. The False Feeling
  3. The Burnout Curve
  4. The Critical Thinking Vaccine
  5. Protecting Cognitive Surplus
  6. Practical Recommendations
  7. A Final Note on Magic

Chapter 3: Cognitive Sovereignty — Renting vs. Owning Your Intelligence

  1. When Intelligence Becomes a Rental
  2. Ownership Is About Sovereignty, Not Possession
  3. The Hidden Cost: Cognitive Dependency
  4. A Practical Sovereignty Stack
  5. On Convenience and Fragility
  6. Practical Recommendations

Part II: World Models and the Architecture of Intent

Chapter 4: World Models for Agentic Coding — The Four-Layer Framework

  1. What We Actually Need
  2. Layer 1: Architecture and Non-Functional Decisions
  3. Layer 2: Components and Contracts
  4. Layer 3: Logic and Behavior Specifications
  5. Layer 4: Code Patterns and Generation Rules
  6. Assembling the Stack

Chapter 5: Intent Documentation — Why Agents Need Your Why

  1. What Intent Documentation Is Not
  2. The Three Levels of Intent
  3. Making Intent Agent-Readable
  4. The Intent Gap Problem
  5. Intent Documentation as Living Practice

Chapter 6: Spec-Kit — Formal Specifications for the Agent Era

  1. The Structured Specification Approach
  2. The Specification Format
  3. Using Spec-Kit with AI Agents
  4. Specifications in the CI Pipeline
  5. Writing Good Specifications
  6. The Agent Engineering Advantage

Chapter 7: Graph Explainers — Making Knowledge Machine-Readable

  1. The Knowledge Graph Advantage for Agents
  2. Graphify: Codebase Intelligence Through Knowledge Graphs
  3. Document Intelligence Tools: Graph-Based Document Comprehension
  4. Building Your Graph Layer
  5. The Bigger Picture: From Text to Structured Knowledge

Chapter 8: Think Before You Prompt — Why Pen and Paper Still Matter

  1. What Paper Does That Screens Cannot
  2. The Sequence Problem
  3. AI Sycophancy and the Validation Trap
  4. The Illusion of Understanding
  5. Cognitive Sovereignty in Practice
  6. The Practical Pattern: Paper-First Engineering
  7. What You Are Protecting

Chapter 9: The Thinking Machine — Zettelkasten, Obsidian, and the Shared Knowledge Layer

  1. What Zettelkasten Is, Precisely
  2. Obsidian: The Engineering Implementation
  3. The Convergence Point: Plain Markdown
  4. Human Zettelkasten vs. Agent Knowledge Graph
  5. The Extended Mind
  6. Building the Vault as Engineering Infrastructure
  7. Cognitive Sovereignty and the Local-First Principle
  8. The Thinking Machine as Infrastructure

Chapter 10: The Feynman Agent and Deep Research Tools

  1. What the Feynman Agent Actually Does
  2. Why Vibe Coding Is the Opposite
  3. Deep Research: From Retrieval to Synthesis
  4. Claude Deep Research
  5. NotebookLM
  6. The Research-to-Understanding Pipeline
  7. The Sovereignty Dimension
  8. Understanding as Engineering Infrastructure

Part III: Agent Architecture

Chapter 11: Agent Identity — Beyond Names and Roles

  1. The Philosophical Foundation
  2. Identity Layers for AI Agents
  3. The System Prompt as Identity Contract
  4. Identity in Multi-Agent Coordination
  5. Verification and Trust
  6. Practical Recommendations

Chapter 12: The Scaling Wall — From Files to Databases in Multi-Agent Systems

  1. Where Files Work
  2. The Five Hard Walls
  3. You’re Building a Database Anyway
  4. Practical Architecture
  5. The Codebase as Database
  6. Practical Recommendations

Chapter 13: Holocracy as Constraint Architecture for AI Agents

  1. The Core Problem: Autonomy Without Chaos
  2. Three Types of Constraints
  3. Roles as Enabling Constraints
  4. Governance as Rate-Independent Regulation
  5. Circles as Holons: Nested Coordination
  6. The Constitution: Defining Inviolable Constraints
  7. Practical Implementation

Chapter 14: Networked Agentic Organizations

  1. Why DAOs Failed and What They Taught Us
  2. The Identity Foundation
  3. Human-Agent Mixed Networks
  4. The Social Graph Layer
  5. Resource Allocation Beyond Tokens
  6. Implementing NAO Principles Today
  7. The Post-AI Labor Context

Part IV: The Coding Agent Toolkit

Chapter 15: Claude Code — The New Command Line for AI Engineers

  1. What Claude Code Actually Is
  2. The CLAUDE.md Convention
  3. Context Management: The Art of the Compact
  4. The Permission Model
  5. Slash Commands: Extending the Interface
  6. Hooks: Automating Workflow Integration
  7. Multi-Agent Coordination
  8. What Claude Code Is Not
  9. Getting Started

Chapter 16: Oh-My-Claude Code and the Plugin Ecosystem

  1. What oh-my-claudecode Provides
  2. The Agent Catalog
  3. Key Slash Commands
  4. The Plugin Architecture
  5. MCP Server Integration
  6. The oh-my-claudecode Philosophy
  7. Getting Set Up
  8. Building Your Own Extensions

Chapter 17: Claude Code Best Practices — Patterns That Actually Work

  1. The Context-First Principle
  2. The Specification Gateway
  3. The Verification Loop
  4. The Incremental Build Pattern
  5. The Two-Pass Pattern for Large Changes
  6. Managing Long-Running Tasks
  7. The Principle of Minimal Scope
  8. Handling Agent Errors
  9. Code Review for AI-Generated Code
  10. The Long Game

Part V: The AI-Native Organization

Chapter 18: Building AI-Native Teams

  1. What AI-Native Actually Means
  2. The Data Quality Obsession
  3. Research as Daily Practice
  4. Hiring for AI-Native Work
  5. Avoiding the Cargo Cult
  6. The Organizational Infrastructure
  7. What Engineers Do in AI-Native Organizations

Chapter 19: Language-Oriented Programming and Constrained Natural Language

  1. The Precision-Ambiguity Spectrum
  2. Domain-Specific Languages: The Proven Foundation
  3. Constrained Natural Language: The Other Direction
  4. The AI Translation Layer
  5. Why This Matters for Engineering Teams
  6. The Right to Natural Language

Chapter 20: The Future of Human-Agent Collaboration

  1. The Collaboration Spectrum
  2. Designing the Boundary
  3. The Human Roles That Remain
  4. The New Engineering Roles
  5. The Gig Economy Dimension
  6. On Not Surrendering Agency

Epilogue: The Right to Build Before Your Time

  1. The Mainstream Is Not There Yet
  2. The Permission to Proceed
  3. What Stays True
  4. To the Reader

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

Now, this is technically risky for us, since you'll have the book or course files either way. But we're so confident in our products and services, and in our authors and readers, that we're happy to offer a full money back guarantee for everything we sell.

You can only find out how good something is by trying it, and because of our 100% money back guarantee there's literally no risk to do so!

So, there's no reason not to click the Add to Cart button, is there?

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub