Why Documentation Must Change
From documents that are read to documents that agents can operate from.
Key takeaways
- The old model (a human writes, a document stores, another human reads) no longer holds because coding agents, RAG systems, MCP clients, and AI assistants now read docs directly to plan, call tools, and verify work.
- Modern documentation has four jobs: instructions, procedures, context, and verification, each mapped to common surfaces.
- The new bar is not "a human understands" but "humans and agents work from the same operational context"; the higher goal is agent-operable, not just AI-readable.
- Keep local, current, contractual, or risky facts in docs and omit generic knowledge the model already has.
- The documentation surface has expanded across README,
AGENTS.md,CLAUDE.md, path rules, Skills, Plugins, MCP Resources, OpenAPI, andllms.txt, each with a typical failure mode.
The Old Formula
For decades, technical documentation followed a simple formula:
A human writes -> a document stores -> another human reads.
Tools changed from wikis to Notion, Confluence, GitBook, and MDX sites, but the operating model stayed the same. The reader was a person, and the value of documentation was measured by how quickly that person could understand the system.
That is no longer enough. Coding agents, RAG systems, MCP clients, and AI support assistants now read project documents directly and use them to plan work, call tools, write code, and verify results.
The New Equation
Modern documentation has four jobs.
| Job | Meaning | Common surfaces |
|---|---|---|
| Instructions | Tell agents how to work in a project | AGENTS.md, CLAUDE.md, .claude/rules/ |
| Procedures | Capture repeatable workflows | Skills, commands, runbooks |
| Context | Provide reference facts and contracts | OpenAPI, ADRs, KBs, MCP Resources |
| Verification | Define how work is checked | CI, smoke tests, eval sets |
Core Shift
The goal is no longer only "a human understands." The goal is "humans and agents work from the same operational context." Good documentation is AI-readable, but the higher bar is agent-operable.
What to Keep and What to Omit
Do not use documents to restate generic knowledge the model already knows. Use documents for facts that are local, current, contractual, or risky.
| Keep in docs | Usually omit |
|---|---|
| Project-specific architecture decisions | Generic framework explanations |
| Internal conventions and exceptions | Language basics |
| Business rules and why they exist | General design pattern tutorials |
| Deployment, runtime, and approval boundaries | Generic troubleshooting |
| Validation commands and completion criteria | Broad conceptual background |
How Agents Consume Documentation
Agents do not skim documents like people. They load text into context, parse headings, follow paths, use code blocks as commands, and treat rules as planning constraints.
AGENTS.md / CLAUDE.md -> project entry instructions
path-scoped rules -> local constraints
Skills / runbooks -> repeatable procedures
OpenAPI / ADR / KB / MCP -> reference context
CI / smoke tests / evals -> verificationThis means long prose, duplicated facts, ambiguous instructions, screenshots without text, and stale links hurt both quality and cost.
The Documentation Surface Has Expanded
| Surface | Purpose | Common failure |
|---|---|---|
README.md | Human entry point | Becomes a dumping ground |
AGENTS.md | Shared agent instructions | Too long or stale |
CLAUDE.md | Claude Code memory/instructions | Duplicates AGENTS.md |
.claude/rules/ | Path-scoped rules | Conflicts with global rules |
| Skills | Repeatable procedures | Hide static project facts |
| Plugins | Distribute skills, MCP, and apps | Ship unreviewed workflows |
| MCP Resources | Expose external context | Treat untrusted data as instructions |
| OpenAPI | API contract | Drifts from implementation |
llms.txt | Markdown index proposal | Misrepresented as SEO guarantee |
New Principles
- Information density - project-specific value per token.
- Structure - headings, tables, code blocks, frontmatter, and stable paths.
- Operability - commands, completion criteria, validation, and ownership.
- Trust boundaries - separate instructions from data and tools from references.
What This Handbook Answers
- How should documents be structured so agents can parse them reliably?
- How should teams write with AI without accepting hallucinated facts?
- When should content live in
AGENTS.md,CLAUDE.md, a Skill, a Plugin, MCP, OpenAPI, orllms.txt? - How do teams maintain freshness, security, and ownership over time?