Docs Written for AI: Your README Is Being Read as a Manual by Agents

A quiet shift has happened: the first reader of your repo's documentation is no longer human — it's AI. Agents read your README, CONTRIBUTING, and comments not to "learn" but to use directly as action instructions. Docs written for humans aim for narrative flow; docs written for AI demand precision, zero ambiguity, and executability — two completely different genres.

Three layers, each with a job

In practice, AI-facing docs work best in three layers.

Layer 1: the project constitution (CLAUDE.md / AGENTS.md). Lives at the repo root; the agent reads it on entry. What goes in? Stack and versions ("use pnpm, not npm"), absolute no-go zones ("don't touch migrations/", "ask me before adding dependencies"), common commands (dev/build/test, one per line). One principle: only include what would go wrong if unwritten — overlong instructions get diminishing compliance.

Layer 2: task skills (SKILL.md). Reusable workflows: "release process," "standard steps for adding an API endpoint," "checklist for writing migration scripts." Unlike the constitution, skills load on demand — the agent reads the release skill only when releasing. The test: if you've dictated a process to an agent more than twice, it should be a skill.

Layer 3: decision records (ADRs). Architecture Decision Records answer "why was it designed this way." The layer vibe coders skip most and long-term value most. Agents have no project memory; seeing context like "why Postgres over SQLite" completely changes the quality of their subsequent decisions. Each ADR can be short: context, decision, consequences — three paragraphs suffice.

Style notes for AI readers

First, use imperatives, not descriptions. "All new files must use TypeScript strict mode; any is forbidden" beats "this project uses TypeScript strict mode." AI obeys "must/forbidden" far better than "we usually."

Second, give counter-examples. Saying what's right isn't enough; show what's wrong. E.g., "Wrong: fetching directly in components; Right: all data requests go through lib/api.ts." Agents are pattern matchers; counter-examples precisely cut off their favorite wrong path.

Third, keep docs in sync with code, or don't write them at all. Stale docs are poison to AI — humans doubt outdated docs, AI follows them literally. Updating docs alongside architecture changes should be a fixed step in your workflow; you can even make the agent do it ("after changing code, update related docs" goes in the constitution).

A lesser-known fact: docs are distribution

When someone else's agent researches "is there an existing library for X," it reads your README and docs. AI-readable docs mean your project gets picked more often in agent-driven evaluations. Clear install steps, explicit scope boundaries, one line saying what it is — these serve humans and agents alike. In that sense, documentation is now your project's API.