Documentation

Keep the repo legible to humans and agents. Docs rot silently — every code change is a potential doc change. Documentation is part of the interface; optimize for scanability, rhythm, and visual clarity, not just correctness.

Sources

• OpenAI Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md
• Claude Code memory guide: https://code.claude.com/docs/en/memory
• OpenAI AGENTS.md findings: https://openai.com/index/harness-engineering/
• Stripe scoped rules: https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents
• ETH Zurich AGENTS.md study (auto-generated content hurts): https://arxiv.org/abs/2503.01298
• Agent Skills progressive disclosure: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Agent Skills architecture: https://www.newsletter.swirlai.com/p/agent-skills-progressive-disclosure

Contents

• AGENTS.md
• Scoped Rules
• Top-Level Doc Split
• README.md
• CONTRIBUTING.md
• SECURITY.md
• Docs Section
• Architecture Docs
• Repo Docs vs Agent Work Artifacts
• Source Boundaries
• Hygiene
• Keep Docs Alive

AGENTS.md

OpenAI's finding: "We tried the big AGENTS.md. It failed." Context is scarce — too much guidance = non-guidance, rots instantly, hard to verify.

Structure

• ~100 lines — table of contents, not encyclopedia
• Points to docs/ directory for depth
• Include: boot command, test command, key conventions, pointers to detailed docs
• Exclude: architecture tours, full API docs, every lint rule
• Keep headings and bullets scannable. Prefer task-shaped labels like Start here, Commands, Validation, or Repo rules over headings that mirror internal filenames or implementation structure
• Codex layers global, project, then nested AGENTS.md or AGENTS.override.md; closer files override broader guidance, so keep root guidance broad and put specialized rules near the code
• Claude Code targets under 200 lines per CLAUDE.md; when a repo already uses AGENTS.md, use a symlink or @AGENTS.md import instead of duplicating content

What belongs in AGENTS.md

• How to boot the app (exact command)
• How to run tests (exact command)
• Key conventions that deviate from defaults
• Links to docs/architecture.md, docs/api.md, etc.
• Scoped rules pointer (e.g., "see per-directory AGENTS.md files")
• Section order that follows agent workflow: orient, run, verify, then special rules or hotspots

What doesn't belong

• Codebase overviews and directory listings (agents discover structure fine on their own — ETH Zurich)
• Auto-generated content (actively hurts performance — +20% cost, ETH Zurich)
• Conditional rules that apply only sometimes
• Implementation details that change frequently
• Labels or section names that read like raw filesystem output when a clearer human-facing title would do

Enforcement

OpenAI enforces AGENTS.md health mechanically:

• Linters + CI validate freshness, cross-linking, structure
• "Doc-gardening" agent scans for stale docs and opens fix-up PRs

Scoped Rules

Stripe's pattern: global rules used "very judiciously." Almost all rules scoped to subdirectories or file patterns, auto-attached as the agent navigates.

How to implement

• Per-directory AGENTS.md or .cursor/rules/*.mdc files
• Rules attached to file globs (e.g., *.test.ts → testing conventions)
• Same rules work for Minions, Cursor, Claude Code — no duplication

Benefits

• Agent picks up only relevant rules for the files it's touching
• No context waste from rules that don't apply
• Easier to maintain — each team/module owns its rules
• Rules stay close to the code they govern

Example structure

src/
├── AGENTS.md           # global conventions (~100 lines)
├── api/
│   ├── AGENTS.md       # API-specific conventions
│   └── routes/
├── ui/
│   ├── AGENTS.md       # UI component conventions
│   └── components/
└── lib/
    └── AGENTS.md       # shared library conventions

Top-Level Doc Split

Use a small default top-level set with one responsibility per file:

• README.md — what the project is, how to install it, how to use it
• CONTRIBUTING.md — contributor setup, validation commands, branch/PR workflow
• SECURITY.md — private-first vulnerability reporting path and boundaries
• LICENSE — legal terms, not contributor instructions

Split the four responsibilities across focused docs unless the repo is tiny enough that one file is clearer.

Use this split to clean up current docs, redistribute content from an overloaded README, or keep existing files accurate. Creating baseline contributor, security, issue, and pull request templates from scratch is repository governance setup, because those files encode collaboration policy.

General doc-surface rules:

• Visible labels should describe purpose, not filenames. Prefer Contributing, Release workflow, or Architecture over CONTRIBUTING.md or docs/RELEASE.md
• Use consistent casing for visible prose and navigation. Reserve all-caps names or extension-bearing filenames for literal file references only
• Order sections and link lists by reader task flow or importance, not by directory layout or implementation order
• Apply the same rule to agent-facing docs and internal guides, not just user-facing README copy

README.md

Use this default order unless the repo gives you a strong reason not to:

1. Hero — name + one-sentence purpose
2. Install — fastest path to getting it running or consuming it
3. Quick usage — one first successful flow
4. Optional examples / variants / integration notes
5. Docs — compact navigation to deeper material
6. Contributing — short pointer to CONTRIBUTING.md
7. License — short pointer to LICENSE

Guidance:

• Lead with one sentence: what the project is and why it exists
• Put the fastest path to value near the top: install, quickstart, docs, or demo
• Link out to deeper docs instead of duplicating them
• Keep contributing and license sections short
• For package repos, show install plus one short usage example
• For app repos, keep end-user usage in README.md and move contributor setup to CONTRIBUTING.md
• Use human-facing labels in README navigation. Prefer Contributing, Architecture, Distribution, or Security over raw filenames or paths like CONTRIBUTING.md or docs/RELEASE.md
• Order navigation for readers, not for the filesystem. Put the most useful docs first instead of mirroring path order
• Apply the same rule to section titles and callouts around the README, not just the bullet links

Workspace or coordination repos

For workspace, meta, or coordination repos, keep the README even more routing-oriented:

1. Hero — what the workspace owns
2. Quick start — shortest path into an already prepared machine or environment
3. Workspace model — layout, naming, source-of-truth registry
4. Key docs — compact links to setup, strategy, and agent guidance
5. Skills — short pointer to the canonical setup doc if shared skill installation exists
6. Contributing — short pointer to AGENTS.md or CONTRIBUTING.md

Guidance:

• Keep one canonical setup doc for machine bootstrap or shared install commands
• Let README.md point to that setup doc instead of duplicating full bootstrap flows
• Keep peer-repo or multi-repo layout explanations short and source-of-truth oriented
• Put cross-repo reference lists in deeper docs or in the peer repos when they are not part of the top-level user path

Shape selection

• Minimal product: short value prop, one docs link
• CLI/package: install first, then quickstart, then docs links
• Product + contributor: short intro, install, usage, docs, contributing
• With navigation/examples: TOC, visual demo, usage examples

CONTRIBUTING.md

Use this section when updating an existing contributor guide or moving current contributor instructions out of an overloaded README. If the repo has no contributor policy yet, flag the gap instead of inventing one from scratch.

Use this default order unless the repo gives you a strong reason not to:

1. Setup
2. Run locally
3. Validation
4. Development notes
5. Pull request expectations
6. Release notes only if contributors genuinely need them

Guidance:

• Put environment bootstrap first
• Keep commands copy-pastable and verified against the repo
• Include only contributor-facing commands here: install toolchain, install dependencies, run locally, run checks
• Keep repo-specific development notes only when they materially help contributors
• Link deeper docs instead of letting CONTRIBUTING.md turn into a handbook
• Keep visible labels and headings contributor-facing rather than file-oriented here too. For example, prefer Pull request expectations over a heading or bullet that just echoes a filename

SECURITY.md

Use this section when updating an existing security policy or moving current vulnerability-reporting instructions out of an overloaded README. If the repo has no private reporting route, flag the gap instead of guessing one.

Keep it short and private-first.

Default shape:

1. Contact
2. Scope
3. Guidelines
4. Supported versions
5. Disclosure

Guidance:

• Tell reporters not to open public issues for vulnerabilities
• Use the repo's real security contact; do not guess
• Link from README.md only when it helps navigation instead of crowding the user flow

Docs Section

When README.md has a Docs section, keep it compact and canonical.

• Link to deeper docs without dumping their contents into the README
• Common links: About, Guides, Architecture, Deployment, Security
• Treat it as reader navigation. Use human labels, not raw filenames or paths
• Keep Contributing and License in their own sections when the README already has those sections
• Put agent-only or generated docs last, or move them into a small Repo Internals section when that reads better
• Keep the same navigation list in one canonical place
• Keep it skimmable
• Carry the same ordering rule into other visible lists and sections across the doc surface. If a sequence reads like filesystem order instead of reader priority, rewrite it

Architecture Docs

• docs/ARCHITECTURE.md — diagram-first system view and important boundaries
• task-specific current-state references such as API, deployment, operations, and guides
• decision docs when the architectural boundary depends on why a choice was made

Repo Docs vs Agent Work Artifacts

Do not treat every markdown file as the same kind of documentation.

Repo docs describe the current project for readers, users, and contributors:

• README.md, CONTRIBUTING.md, SECURITY.md
• architecture, API, deployment, operations, and runbook docs
• setup and validation commands that are true for this repo now

Agent work artifacts coordinate how agents change the repo:

• AGENTS.md and scoped agent guidance for repeated behavior
• docs/specs/ for durable behavioral contracts
• docs/decisions/ for durable choices and trade-offs
• docs/plans/ for tactical execution that should disappear when done
• handoff prompts only when they help future agents resume work

Keep the layers connected with short links. Do not pour implementation plans, prompt text, or unfinished reasoning into reader-facing docs. Promote an artifact into general docs only after it becomes a stable contract the repo owns.

Source Boundaries

Documentation should capture contracts the target repo owns.

Use this quick table before writing:

Good durable homes:

• docs/decisions/ for why a choice was made
• docs/specs/ for long-lived behavioral contracts
• docs/plans/ for tactical execution that can be deleted when done
• AGENTS.md or scoped agent guidance for behavior future agents must repeat

Hygiene

Run periodically or after a burst of changes:

1. Dedup: same fact in multiple files → pick one canonical location, replace others with pointers
2. Consistency: names, commands, paths in one doc match what referenced docs say
3. Labeling: visible labels read like a file tree or internal implementation detail → rewrite them in reader-facing language
4. Ordering: sections or bullet lists mirror path order instead of reader priority → reorder them
5. Conciseness: section restates what a referenced doc covers → replace with one-line pointer
6. Scannability: agent-facing docs are technically correct but visually awkward, over-cased, or hard to skim → rewrite for fast orientation
7. Structure: file growing past ~80 lines of prose → split detail into references/, keep parent as routing layer
8. Staleness: delete or archive docs for removed features, finished plans, superseded decisions
9. Symlinks over copies: two files need identical content → symlink them
10. Ownership: fact belongs to another repo, private workspace, or local machine → keep it out, link the owner, or make the wording generic

Keep Docs Alive

• After implementing a feature → check if AGENTS.md, README, or architecture docs need updating
• After renaming/moving/deleting code → grep docs for stale references
• After a design decision → record it in a decision doc before moving on
• Treat doc drift the same as test failure — it degrades every future agent's performance