The Irony of Writing Documentation That AI Agents Actually Read
More Documentation Than Ever
Here is the irony of the AI era: developers are writing more documentation than ever before. Not READMEs that nobody reads. Not Confluence pages that go stale after a week. CLAUDE.md specs - precise, detailed instructions for AI agents.
And the agents actually read every word. Every constraint, every edge case, every "do not do this" caveat. They follow the documentation exactly as written, which is more than most human teammates have ever done.
Why This Documentation Is Different
Traditional documentation fails because humans skim. They read the first paragraph, maybe scan the headers, and then figure it out by trial and error. Writing detailed docs feels like wasted effort when the audience is going to ignore most of it.
CLAUDE.md specs flip this dynamic. The audience - an AI agent - processes every token. If you write "never use em dashes," the agent will never use em dashes. If you write "always run tests before committing," the agent will always run tests before committing. The documentation is the product specification, and compliance is near-perfect.
What Good Agent Documentation Looks Like
The best CLAUDE.md files are structured for machine consumption:
- Explicit constraints over implicit conventions. Do not assume the agent knows your team's coding style. Spell it out.
- Negative instructions are as important as positive ones. "Do not create new files unless necessary" prevents the agent from adding unnecessary complexity.
- Examples with context. Show the agent what a correct implementation looks like, and explain why alternatives are wrong.
- Priority ordering. When constraints conflict, the agent needs to know which one wins.
The Cultural Shift
Writing for AI agents forces a kind of precision that is rare in human communication. You cannot rely on shared context, body language, or the assumption that the reader will "figure out what I mean." Every instruction has to be unambiguous.
This is making developers better communicators. The skills you build writing specs for AI agents - clarity, precision, explicit constraint definition - transfer directly to writing specs for humans. The difference is that humans still will not read the full document. But at least now you know how to write one that could be followed perfectly if they did.
Fazm is an open source macOS AI agent. Open source on GitHub.