Originally published at kunalganglani.com — read it there for inline code, hero image, and live links.

AI-Readable Documentation: 8 Templates That Agents Actually Use [2026]

Documentation is still the set of written artifacts that explain what your software does, how to use it, and why it was built the way it was. In 2026, the twist is that “the reader” is often an AI coding assistant or agent. If you want to move fast with copilots, you need to know how to write documentation that AI tools can use reliably, not just write “nice” prose that humans politely ignore.

Key takeaways

• AI tools don’t “understand docs.” They retrieve chunks, weigh them like instructions, then act. Your job is to make instructions unambiguous.
• Stable anchors, predictable structure, and verification steps matter more than eloquence.
• Agent-friendly docs are routing logic plus evidence, not a wiki-shaped memoir.
• You can measure doc completeness for agent safety using a simple 100-point scorecard.
• Automation helps. Unchecked doc generation creates a feedback loop of convincing nonsense.

Write docs like you’re programming a cautious intern with amnesia. Every step needs inputs, outputs, and a check.

The Intent Gap: Why Code Isn’t Enough

The “post-documentation era” take is seductive. Agents can read source. They can parse your OpenAPI spec. They can grep the repo. So why write docs at all?

Because code and specs are great at how, and terrible at why.

As Ben Halpern, Founder at DEV Community (Dev.to), puts it: there’s an intent gap between what the system does and what humans intended. A spec can list an endpoint and payload fields. It can’t explain:

• why a breaking change was intentionally avoided in March
• why a “weird” retry policy exists only for one payment processor
• why a service is allowed to be eventually consistent in one workflow but not another

That “why” is what stops agents from confidently doing the wrong thing.

Here’s a painfully common example. Most of us have shipped “temporary” compatibility layers that lasted 18+ months. The code tells you what it does today. The docs are the only place that can say: this is here because customer X can’t upgrade until condition Y is met, and you’re allowed to delete it when Z happens. Without that sentence, an agent will happily “clean up” the layer. Congrats. You just manufactured a regression.

If you’ve been following the Dev.to discourse from July 2026, the vibe has shifted. It’s no longer “docs are dead.” It’s “docs are changing shape.” They’re becoming agent routing + evidence.

This connects directly to how I think about AI agents in real engineering orgs. Reliability comes from explicit constraints, not vibes.

(Inline illustration break: “Intent gap: code vs docs vs decisions”)

The Danger of Slop Describing Slop

Automation in docs is good. Lazy automation is poison.

Halpern nails the failure mode: unchecked LLM-generated docs become “slop describing slop.” One model invents a plausible explanation. The next model treats it as ground truth. A month later you’ve got a repo that reads like a confident rumor mill.

Here’s the problem in agent terms. Agents weight text like instruction. They don’t naturally discount “stale but confident” prose. Humans do a vibe-check when something looks off. Agents do not. They’ll execute.

Enjoy Kumawat learned this the hard way. In Enjoy Kumawat’s repo, one stale line in key_facts.md (“Token scopes needed: repo, user”) caused an actual bug on 2026-06-23 when the workflow scope was required. A human would skim that and think “ok, scopes stuff.” An agent will take it literally and proceed.

That’s why “generate docs from code” is not a strategy. It’s a starting point.

My opinionated rule: if an agent can execute the instruction, the instruction must have an owner. That’s not a tooling problem. That’s accountability.

If you care about AI in production, treat documentation like production config. It needs review, provenance, and drift detection. “Someone should update the wiki” is how you end up with outages and weird security holes.

The setup: how AI tools read and use documentation

AI coding tools don’t ingest your docs the way humans do. They do some combination of:

1. Retrieve: search/grep, vector search, IDE index, or a docs portal search.
2. Chunk: read a section or a few sections that fit in the context window.
3. Follow: treat bullet points and imperative language as “do this now.”
4. Act: run commands, edit files, open PRs, call tools.
5. Loop: when they hit an error, they retrieve again.

So doc quality isn’t about “did we write a lot.” It’s about determinism.

A small but important detail: most agent loops will only keep a handful of doc chunks in context at once. If your runbook step references “see above” or “as mentioned earlier,” you’re rolling dice. Sometimes the “above” chunk is present. Sometimes it’s not. Either way, the agent will do something.

What format of documentation is best for AI (Markdown vs HTML vs structured data)?

My practical answer: Markdown + predictable structure wins for most teams.

• Markdown is diffable, reviewable, and lives next to code.
• HTML is fine, but it tempts teams into long narrative pages with fragile navigation.
• Structured data (YAML/JSON/OpenAPI/JSON Schema) is the best way to reduce ambiguity.

The sweet spot is what Sualeh Fatehi is arguing for with SchemaCrawler Scribe. In Sualeh Fatehi’s view, Google’s Open Knowledge Format (OKF) output works because it’s consistent, diffable, and automatable.

If you publish public API docs, it’s still hard to beat the combination of an OpenAPI spec plus narrative guides. The canonical reference is the spec itself: OpenAPI Specification.

And when you’re documenting structured inputs/outputs beyond HTTP, JSON Schema is still the most portable way to make “what does this field mean?” unambiguous.

The trust crisis and the search for reputation

Once agents become your “junior teammate,” your docs become your reputation system.

Halpern frames this as a trust crisis: if everything is generated, nothing is trustworthy. In real teams, that turns into informal folklore:

• “this runbook is always right”
• “that wiki page lies”
• “that ADR folder is the only source of truth”

The move is to make those signals explicit, not tribal knowledge.

At minimum, add provenance to any doc that drives actions:

• last verified date
• version / commit SHA
• owner team
• verification checklist (what was actually run)

That’s how you stop agents from treating your docs as fan fiction.

(Inline illustration break: “Docs trust signals: provenance, verification, ownership”)

Prose docs fail differently than code docs (and how to prevent it)

Humans forgive doc drift. Agents punish you for it.

Enjoy Kumawat’s one-liner is the best summary I’ve seen: prose docs fail differently than code docs. Code fails loudly. Stale prose fails quietly, by nudging the agent into confident wrongness.

Common failure modes in agent-assisted teams:

• Soft language (“usually”, “sometimes”, “as needed”) where a procedure needs a branch.
• Hidden prerequisites (missing env vars, credentials, network access, feature flags).
• Unverifiable steps (“ensure it works”) without a test command or UI check.
• Context leaks (“as in the previous section”) that break when only one chunk is retrieved.
• Overloaded README that becomes a context dump.

If you’re using Claude Code or doing a lot of vibe coding, these issues get amplified. Agents move fast. They will happily execute the fastest path you accidentally described.

The fix is boring. Write procedures like procedures.

How do you structure documentation so an AI agent can follow steps reliably?

My template for any “do X” doc:

• Goal: one sentence.
• Prerequisites: explicit list.
• Inputs: variables, flags, filenames.
• Steps: numbered, no branching hidden in prose.
• Outputs: what artifacts change.
• Verification: exact checks.
• Rollback: if it’s operational.
• Failure modes: common error signatures and what to do.

If that feels like overkill, consider the alternative. Agents invent missing steps. Humans do too, but at least they pause when they’re unsure.

What changed in how I write these files (the AI-readable template pack)

Most competing posts wave their hands at “write better docs.” That’s not useful. You need copy/paste-able patterns that you can enforce across doc types.

You don’t need 40 doc types. You need 8 that cover 95% of what an agent actually does.

Below is a template pack you can adopt in a day. It’s optimized for humans and agents, and it lines up with what Kumawat (routing logic files), Moukhataev (index and tags), and bestbee (coverage measurement) are all pointing at.

The minimum repo files for agent onboarding

If you’re starting from scratch, add these 7 files/folders:

1. AGENTS.md (or CLAUDE.md) at repo root
2. docs/index.md (docs home)
3. docs/decisions/ (ADRs)
4. docs/runbooks/ (operational procedures)
5. docs/troubleshooting.md (error signature map)
6. docs/key_facts.md (commands, endpoints, environments)
7. docs/tags.md (tag registry)

That’s it. Everything else is optional.

Template 1: AGENTS.md / CLAUDE.md (routing logic)

Kumawat’s “protocols” idea is the right mental model. This file is routing logic.

Include:

• what the agent must read at session start
• which file to consult on specific events
• what the agent is not allowed to do (guardrails)
• how to log work

Example structure (no code block, but you can copy this outline):

• Start here: read docs/index.md and the nearest index.md in the directory you’re touching.
• If you see an error: consult docs/troubleshooting.md then docs/runbooks/.
• If you propose architecture changes: check docs/decisions/ for conflicts.
• If you change behavior: update the relevant task doc and verification steps.
• After a task: append a short entry to docs/issues.md (date, goal, diff summary, verification).

Template 2: docs/index.md (information architecture)

This should fit in ~60–120 lines. If it becomes longer, you’re writing a wiki again. And nobody. Not humans, not agents. Wants that.

Include:

• links to “how-to” docs (tasks)
• links to “reference” docs (APIs/config)
• links to ADRs
• link to runbooks
• link to troubleshooting

Template 3: per-directory index.md (the directory tree layer)

This comes from Pavel Moukhataev: every meaningful directory gets an index.md that explains local structure.

Rules:

• Keep it short: 10–30 lines per directory.
• Describe purpose, key files, how to test, and what not to break.
• Link to cross-cutting concepts via tags.

Template 4: tag registry + cross-cutting layer

Moukhataev’s cross-cutting layer is the single best “low tech” agent trick I’ve seen: use shared @tag: tokens in docs and code comments so plain search works.

• Put the registry in docs/tags.md
• Use @tag:billing-retries, @tag:tenant-isolation, etc.
• Require tags on ADRs, runbooks, and any tricky subsystem

This also answers “Why not just rely on the IDE index?” IDE indexes are vendor-specific and can be opaque. grep is forever.

Template 5: ADR (Architecture Decision Record)

ADRs are how you close the intent gap.

Required fields:

• ID: ADR-00XX (stable)
• Status: proposed / accepted / superseded
• Context: what problem forced the decision
• Decision: the choice
• Consequences: tradeoffs, risks, migration cost
• Alternatives considered: 2–3 bullets
• Tags: @tag: list
• Supersedes/Superseded by: stable links

If you write nothing else, write ADRs. Agents can read code. They can’t read the argument you had in a meeting.

Template 6: Runbook (operational)

Runbooks are where agents can do real damage if you’re sloppy.

Required fields:

• Goal
• Blast radius (explicit)
• Prereqs (permissions, access, environment)
• Steps (numbered)
• Verification (exact)
• Rollback (exact)
• Owner (team)
• Last verified (date)

If your runbook has “restart service” without an explicit verification check, you didn’t write a runbook. You wrote a suggestion.

Template 7: Troubleshooting (error signature table)

Agents need “if error X, do Y.”

Structure:

• A table of error signatures (exact strings or regex-ish patterns)
• The likely cause
• The fix
• The verification
• The link to the runbook section

This is also an LLM security issue. Error logs are a classic place for prompt injection payloads to sneak in via “helpful” text. See my prompt injection coverage if you’re letting agents read logs and act.

Template 8: API endpoint example block (humans + agents)

If you maintain an SDK or public API, every endpoint should have at least:

• “what this does” in 1 sentence
• request/response schema snippet (OpenAPI/JSON Schema)
• 1 working example request
• 1 example error response
• pagination/rate limit notes
• verification (how to test it)

This is where structured data pays off. Don’t force the model to infer field semantics from narrative.

(Inline illustration break: “Template pack overview: 8 doc types”)

The problem: navigation at scale (directory indexes + tags)

Moukhataev’s post is short, but it solves the scaling problem people keep stepping on. Once your agent instruction file turns into a context dump, it stops working.

He proposes two layers:

• The directory tree layer: index.md per directory.
• The cross-cutting layer: shared @tag: tokens across docs and code.

Let’s put numbers on it.

In a mid-size monorepo, you can easily have 50–200 directories that are “meaningful.” If even 25% of them get touched frequently, the agent needs a fast way to answer: “what is this folder and what should I not break?” A per-directory index.md is the cheapest answer.

Then you need cross-cutting tags because the nastiest bugs live across boundaries. Auth bootstrap. Tenant isolation. Idempotency. Retries.

Keep a tag registry

Don’t let tags become folk taxonomy.

docs/tags.md should define:

• tag name
• owning team
• 1-line definition
• links to canonical ADRs/runbooks

Treat it like an API. If tags drift, search results rot.

Tradeoffs (because there are always tradeoffs)

Moukhataev is honest about tradeoffs. Here are mine:

• More files means more maintenance.
• Tags get spammy if you don’t enforce a registry.
• Directory indexes go stale if you don’t tie them to PR expectations.

And I still think the boring approach wins because it’s resilient:

• Markdown survives tool churn.
• grep works on every machine.
• You can review doc changes in PRs like code.

What I’m still unsure about

The open question I haven’t seen answered cleanly: how do we make this portable across private repos + public docs portals without duplicating content?

My current stance: keep canonical “agent routing” and “operational evidence” in the repo, then publish a curated subset externally. Do it the other way around and your repo becomes the stale mirror. Every time.

The actual test: keeping docs fresh with automation and gates

Docs rot because the system changes and the incentives don’t.

The fix is to stop treating docs as a side quest. Put them on rails.

Automation that’s worth doing

You don’t need fancy AI workflows. Do these boring checks first:

• Link checking in CI (catch broken anchors)
• Command freshness checks (run the documented commands in a minimal container)
• Schema validation for structured snippets (OpenAPI / JSON Schema)
• Doc linting for heading conventions and frontmatter
• Changelog enforcement for behavior-changing PRs

For API docs, generated references are fine, but they need narrative guardrails and examples. For database docs, Fatehi’s approach is attractive because the generated output is still reviewable Markdown.

Stable anchors + canonical citations (so agents can cite deterministically)

Agents need stable section addresses. Humans tolerate “scroll until you see it.” Agents don’t.

Rules I recommend:

• Add explicit IDs in headings when your renderer supports it.
• Avoid renaming headings casually. A renamed heading is a broken API.
• Use permalinks (most doc sites support this).
• Version your docs if behavior differs across major versions.

If you’ve ever debugged a production incident with a stale runbook, you already know how ugly this gets.

Use the scorecard as a workflow gate (measuring doc completeness)

bestbee proposes a clean, measurable rubric: a 100-point documentation coverage score across five equally weighted dimensions:

• Problem (20)
• Reproduction (20)
• Expected behavior (20)
• Verification (20)
• Limitations (20)

That’s from bestbee. I like it because it’s not a vague “quality score.” It’s an evidence checklist.

How to apply it without turning it into bureaucracy:

• Score only high-risk work: auth, payments, infra, data migrations.
• Store the score as a small JSON/YAML file in the PR.
• Require at least 80/100 to merge for those categories.

That “80” is opinionated, but it matches bestbee’s example: their case study landed at 80/100, with reproduction and limitations partial.

Make scoring auditable

This is the part teams skip. Don’t.

If the score is a checkbox, it becomes theater. Make it auditable by requiring:

• evidence links (issue, logs, screenshots, test run IDs)
• revision pinned to a commit SHA
• ownership field

You can do this with a tiny validation script, like bestbee shows. No dependencies required.

Measure whether the scorecard helps

If it doesn’t change outcomes, delete it.

Track one metric for 30 days:

• number of “agent got stuck” loops per week
• number of PRs requiring a human to correct misunderstood requirements

If those don’t move, you’re measuring the wrong thing.

How to write documentation that AI tools can use (the checklist)

This is the AI-readable documentation checklist I wish every repo had. Print it. Put it in AGENTS.md.

• Write task docs with explicit prerequisites, inputs, outputs, and verification steps.
• Use numbered steps. Avoid “then” chains hidden in paragraphs.
• Put “why” into ADRs, not random prose.
• Add stable anchors. Treat heading changes like breaking API changes.
• Add provenance: owner, last verified date, version/commit.
• Prefer Markdown for workflow docs, plus structured snippets (OpenAPI/JSON Schema) for ambiguity.
• Create per-directory index.md files for navigation.
• Add cross-cutting @tag: tokens and keep a tag registry.
• Maintain troubleshooting as an error signature table.
• Add a doc coverage scorecard for high-risk changes and gate merges.
• Automate link checks and command freshness in CI.
• Never ship unchecked LLM-generated docs. Human oversight is not optional.

If you do nothing else, do the first 3. That gets you most of the win.

FAQ

How do AI tools read and use documentation?

They usually retrieve relevant sections via search (keyword or vector), pull a few chunks into context, and treat imperative text as instructions. They then act immediately, often in a loop where failures trigger more retrieval. That’s why stable structure and verifiable steps matter.

What should a README include for AI coding assistants?

Keep the README as an entry point, not a dump. Include the project goal, how to run tests, the primary commands, and a link to AGENTS.md/CLAUDE.md plus docs/index.md. Put “why” into ADRs and procedures into runbooks.

How do you keep documentation up to date as code changes?

Make docs part of the same workflow as code: require doc updates in behavior-changing PRs, run link checks in CI, and periodically re-verify runbooks. Add provenance fields like “last verified” and “owner” so staleness has a person attached to it.

How can you make API documentation easier for LLMs to use?

Pair narrative guides with structured specs. Use OpenAPI for endpoint contracts and JSON Schema for payload semantics, then add examples and explicit error cases. Give verification steps so an agent can confirm it’s using the API correctly.

What are common mistakes when writing documentation for AI tools?

The big ones are hidden prerequisites, vague language, missing verification, and stale commands. Another common failure is long pages that rely on “see above” references that break when agents only retrieve one section. Unchecked AI-generated docs are the fastest way to create confident misinformation.

How do you document a codebase for onboarding with AI agents?

Start with a routing file (AGENTS.md/CLAUDE.md) that tells the agent what to read and when. Add docs/index.md, ADRs, per-directory index.md, and a troubleshooting error table. Use cross-cutting tags so the agent can gather complete context with simple search.

What this means next

The “post-documentation era” is a marketing phrase. The reality is more interesting. Docs are becoming executable constraints for humans and machines.

My prediction: by the end of 2027, the teams that ship fastest won’t be the ones burning the most agent tokens. They’ll be the ones that treat documentation like an interface. Stable. Testable. Versioned. Owned.

If you’re building with agents today, here’s the challenge: pick one repo and ship the template pack this week. Then watch what happens. Your agents won’t become “smart.” They’ll become predictable, which is the only kind of smart that matters in production.

---

Originally published on kunalganglani.com