There are already dozens of books about coding agents. How to configure Claude Code, how to write the perfect skills, which plugins promise to do all the work for you. I’ve decided to write one more — but slightly different.

Mine is not about yet another collection of Markdown files dressed up as a product. It’s about mindset.

What does it actually mean to work with an agent? What skills do you still need to bring — not the agent, you? What are the new challenges nobody warned us about? Things like fatigue from working with AI, the change in your dopamine loops, and how to prevent burnout when agents are doing the mechanical heavy lifting but you’re still the one responsible for the outcome. These are real challenges, and engineers need to be aware of them.

I also explore what an AI-first organization actually means — and it’s not about token consumption.

The Intent Problem

The deeper part of the book goes into AI-assisted architecture: how to structure knowledge and product design, how to keep intent on the human side, and critically — how to document that intent.

Here’s what I’m observing: we’re shifting from heavily writing code to writing specifications that drive agents. The spec is becoming the primary artifact, with code as its output. But quite often we lose the spec. We have some history of chats, and the information starts living inside that chat history. That’s horribly wrong.

The memory of your coding project is not your codebase. It never was. We’ve always had this impedance mismatch between architecture diagrams and code. Whole teams of people existed just to hold the context in their heads and map between these two artifacts. Some projects never had architecture diagrams at all, so they never felt the gap — because they never had the architecture. That’s also possible.

But with agents, you cannot ignore this anymore. It simply doesn’t work. If you come back to a project three weeks later and want to add a small feature, your agent will start rewriting large chunks of the codebase. If you ask it why it made certain decisions or chose a particular pattern three weeks ago — just forget about it. The context is gone.

Context Graphs and Documentation That Agents Can Actually Use

We need to change how we set context and how we use context graphs in our codebases. Documentation and context management matter more now than ever before. It was always important, but agents make it practically impossible to ignore — or you could still ignore it, but the cost of that ignorance will be extreme.

In the book, I explain how to build architecture documentation in an agent-friendly way: how to construct a cascade of specifications that preserve intent, how to set up coding rules, patterns, and conventions that make code generation more effective. And yes — code generation, because the agent is, at the end of the day, a very smart code generator. Your job is to drive the generation. To own the intent. To document everything. To manage context deliberately.

One particularly interesting topic here is semantic markup. We can hint at importance by using Heading 1 — that’s a decent trick. But with HTML or XML tags, you can be precise. You can say exactly what something is, not just how it looks in a hierarchy. This kind of structured, meaningful markup is something agents can parse with real understanding, and it’s worth exploring as a documentation strategy.

The Scale Problem

There’s also a scaling problem I cover in depth. You can start with Markdown files — and that’s a reasonable starting point. But especially in a multi-agent setup, you will quickly discover that flat files don’t scale and don’t work. Large-scale knowledge bases and graph databases are what make agents genuinely capable, not just within a single session but across a swarm of collaborating agents.

Where the Book Stands

The book is philosophical, but if you follow me on Substack, you’ll recognize many of the threads I’ve been pulling on — they’re now composed and in one place. It’s still a work in progress, and if you pick it up on Leanpub, you get all future updates included.

The next big section I need to write is about how to talk to your agent: voice-to-text workflows, how to make your interaction blazingly fast, and how to transform the way we work not just with Claude Code but with an entire swarm of tools — getting the best from them without wasting time or money.

The one thing I want you to take away: we cannot ignore documentation anymore, and we cannot use the old documentation patterns either. The 1970s approach to specs is not what agents need. The shift is real, and understanding it is what separates engineers who will thrive with AI from those who will fight it.

Book https://leanpub.com/clarityengineer

Get full access to Sovereign Agentic AI (Volodymyrs View) at volodymyrpavlyshyn.substack.com/subscribe