Agent Ready Docs - 5 Lessons Learned
I've been deep diving into what makes documentation 'agent ready'. Here are 5 patterns I keep seeing, and what they mean for how you should write.
1. Vague Documentation vs. Missing Documentation
If an agent has no information, it admits uncertainty.
If documentation is vague, the agent fills the gaps with training data and produces confident but wrong answers.
Example: Commit Messages
One CONTRIBUTING file that I came across had a link to Erlangs write a good commit message
This gives an agent just enough signal to invent Conventional Commits. If this is your standard then great, if it is not then agents will make it up. In this case, not having a CONTRIBUTING file is safer as the agent will respond with honestly and tell you that it doesn’t know.
Try it yourself
Open a repository with a vague CONTRIBUTING in Copilot Chat and ask:
What commit message format should I use in this repository?
If the answer is specific and confident — Conventional Commits but none of that is written in your docs, you just watched a hallucination happen in real time.
2. Good Structure ≠ Usability
A repo can score high on AI readiness (e.g. good structure) and fail an agent ready integration test.
Well-formed Markdown with missing information is still unusable.
Example: Project Setup
If your project depends on files existing and passing tests but your CONTRIBUTING never explains how to run tests or start the service, the agent passes the “good structure” health check but cannot actually contribute.
Try it yourself
Open a repository and type into Copilot Chat:
Give me the exact commands to set up this project locally and run the tests.
Do not infer anything from the tech stack.
Only use what is written in the documentation.
Watch where it stops. Every gap it cannot fill without guessing is a documentation debt that your AI Readiness score never caught.
3. Placement Matters as Much as Content
Information in the wrong file might as well be absent. Documentation must be connected, not just present.
Example: Linting Rules
A CONTRIBUTING said ensure code is linted to appropriate standards
The AGENTS.md contained:
Run vale and markdownlint --disable MD013 before committing
Vale configuration is in .vale.ini
markdownlint configuration is in .markdownlint.json
The agent reads CONTRIBUTING. It finds "ensure code is linted to appropriate standards." There is no link to AGENTS.md. The agent has no reason to look there.
It needs to answer: what linting tools should I run?
It knows it is in a documentation repository. It knows common documentation linting tools. It answers from training data: run markdownlint, perhaps vale. It may get the tools right by luck. It will not know about --disable MD013. It will not know where the config files are. It will not flag the .vale.ini location.
The rules exist. The agent cannot see them. Not because they are hidden because nothing connected them.
Try it yourself
Find a repository where AGENTS.md exists but CONTRIBUTING never references it.
I want to raise a pull request. Walk me through every convention and check I need to follow before I open it.
Count how many rules from AGENTS.md appear in the answer. The ones that don't are invisible — not because they don't exist, but because nothing connected them.
4. A single unclosed code fence can break document parsing
Markdown parsers treat everything after an unclosed fenced code block as part of the code block.
Example:
```yaml
task: summarize
agent: summary_writer
If the closing fence is missing, the rest of the document is interpreted as code rather than prose. Agents may lose the document structure entirely, causing headings, sections, and instructions to become invisible.
Try it yourself
Deliberately introduce an unclosed code fence somewhere in a document, then ask the agent a question that requires it to read content after the unclosed fence.
What are the contribution guidelines for this project?
If the agent can't answer questions about sections that appear after the unclosed fence — or treats prose as code — the test fails. The agent has lost the document structure.
5. The Standard Covers Structure. It Doesn't Cover Content
Our Docs as Code standard tells teams which files to create - a README and a CONTRIBUTING. It does not tell them what those files need to contain for an AI agent to use them safely.
A README exists but has no problem statement. A CONTRIBUTING file exists but defines no scope boundaries. An agent reads both, finds no constraints, and starts proposing changes - confidently, and incorrectly.
The files are present. The standard is satisfied. The agent is still guessing.
Presence is not the same as usability. What each file should contain - a problem statement, a named audience, scope boundaries, safe-change rules - is a different requirement from whether it exists at all. And nobody has written that requirement down yet but I am working on it.
Final Takeaways
I now see documentation as AI infrastructure.
Without clear, structured, and maintained documentation, AI systems cannot operate reliably, safely, or at scale.
Documentation debt doesn't disappear when you adopt AI. It compounds.
The documentation your agents read is an engineering asset. Start treating it like one.
|
