Maintaining Documentation with AI

Have docs written – and review them

AI is good at producing documentation: README sections, function comments, API descriptions. The Claude Code docs describe a simple flow for this: have undocumented spots found, have docs generated, then review and refine. The last step is mandatory: generated docs always sound convincing – even when they are wrong. Read them before you commit them.

Docs for agents: CLAUDE.md and AGENTS.md

Documentation now has two audiences: humans and agents. CLAUDE.md is a file Claude Code reads at the start of every session – with build commands, style rules, and project quirks. AGENTS.md is an open, cross-tool format with the same idea: a "README for agents", read by more than 20 coding tools (as of July 2026).

Avoiding documentation drift

Docs go stale when the code changes and nobody touches the docs. Wrong docs are worse than none – especially for agents, which trust them. Practical rule: update docs in the same change set as the code, and regularly ask the AI: "Does the README still match the current state?"

llms.txt for AI readers

If your docs are a website, an /llms.txt file helps: a Markdown overview with links so AI systems can find the content without fighting through HTML full of navigation and ads.