Technical documentation has traditionally had a fairly narrow job: help the next developer understand a system fast enough to be useful. That job hasn't disappeared, but it's no longer the only one. AI coding tools, from inline assistants to full agentic build platforms, now read the same repository files, and unlike a person, they don't skim past a gap in the documentation and figure it out through experience. They fill it with a guess.
Why does documentation matter more in an AI-assisted codebase?
AI coding tools work from more than the prompt. They pull in surrounding code, project conventions, and whatever context files exist in the repository. A README that stops at installation instructions doesn't give a tool much to reason from when it's deciding how a new feature should be structured or which existing pattern it should follow instead of reinventing.
The cost of that gap isn't abstract. It shows up as rework, as inconsistent patterns scattered through a codebase, and in the worse cases, as changes that look correct but quietly violate a rule nobody wrote down. A team that asks an AI tool to add a refund flow to a billing service, with no documentation to work from, may get a new payment abstraction instead of the approved one, a missing idempotency check, or an error-handling pattern that doesn't match the rest of the service. None of that is the tool malfunctioning. It's the tool doing a reasonable job with insufficient information.
This has driven fast, visible adoption of files written specifically for AI tools rather than people: CLAUDE.md for Claude Code, .github/copilot-instructions.md for GitHub Copilot, and AGENTS.md as a cross-tool standard. AGENTS.md alone has been adopted by more than 60,000 repositories, according to arXiv research on context engineering for AI coding agents, a pace that suggests this has moved past early-adopter territory.
Does a context file actually improve what the AI produces?
The honest answer is more specific than "yes." A study of 124 real code changes across 10 repositories found that having an AGENTS.md file present reduced median agent runtime by about 28.6% and output tokens by roughly 16.6%, a meaningful efficiency and cost improvement. But a separate, more controlled study covering 288 attempts across 17 tasks found no measurable difference in whether the agent got the change correct, according to Generative Labs' analysis of both studies.
That distinction matters for how teams should think about this. Documentation appears to make AI tools cheaper and faster to work with, it stops them from re-deriving context they could have simply been given. It doesn't seem to make them meaningfully smarter on its own. The quality of judgment in the output still depends on what the documentation actually captures: decisions and constraints, not a restatement of what the code already shows.
What should documentation record, if not just descriptions?
The distinction that seems to matter most is why, not what. A comment noting that a request is retried three times describes behavior. A comment noting that only idempotent requests should be retried, because the endpoint can create a duplicate payment otherwise, records a constraint, the kind of detail that keeps a safety rule from being quietly deleted by someone (or something) that didn't know it existed.
In practice, this means documenting why a database or framework was chosen, why a service boundary exists where it does, which rejected alternatives were considered and why, and which parts of a system shouldn't be changed casually. None of this is naturally visible from reading code, which is exactly why it tends to get lost first.
What does a documentation layer built for AI tools look like structurally?
A workable structure tends to separate concerns by scope: a concise repository-level file at the root, module-level notes for services carrying real risk, and file-level context for code that changes often or breaks easily. Coding conventions and anti-patterns get stated explicitly. Canonical examples get linked rather than re-explained.
Some AI build platforms generate a version of this automatically, as part of how they build software rather than as separate work. 8080.ai, for one, produces a System Requirements Document and a set of architecture diagrams before any code is generated, and ships projects with a README and architecture overview included. That's a structurally different starting point than platforms that generate code first and leave documentation as an afterthought, though it doesn't remove the ongoing work of keeping that documentation accurate as a system evolves, any more than a hand-written AGENTS.md file maintains itself.
How does this change day-to-day engineering practice?
The practical shift is less about tooling and more about habit. Documentation updates land in the same pull request as the code change they describe, not a follow-up task that quietly never happens. Context files get reviewed the way code does. Stale rules get removed rather than left to accumulate next to current ones, which matters more here than it used to, because a tool following instructions literally won't notice that a rule stopped applying two months ago the way a person eventually would.
The underlying shift
AI coding doesn't make documentation less important, it makes documentation that's vague, outdated, or scattered noticeably more expensive, because it now has a reader that acts on it immediately and without judgment to fall back on. Whether that reader is Claude Code checking a CLAUDE.md file, Codex reading AGENTS.md, or a build platform like 8080.ai working from a requirements document it generated itself, the underlying discipline is the same: record decisions, not just descriptions, keep the explanation close to the code, and update both together.
Top comments (0)