AGENTS.md

README.md is for humans. AGENTS.md is for the agent — the one file your coding assistant reads to learn how to work in this repo: the commands, where things live, the conventions, the guardrails. Every serious agent reads it now.

Which is exactly why a stale one is dangerous. A human skims a stale README skeptically. An agent acts on a stale AGENTS.md — at full confidence, no second-guessing. The renamed build command, the guardrail you dropped, the convention you abandoned: followed to the letter. So the real question isn't whether to have one. It's how to keep it true. This guide is the shape of a file that stays true.

The one rule: every line earns its place

A line stays only if it passes one test:

• It resolves ambiguity — picks the canonical choice where the code has several valid ones, or
• It caches cost — saves the agent an expensive hunt (multi-file reads, git archaeology).

If it does neither, cut it. Short. Current. Specific. Actionable. Everything below serves that filter.

The sections

Ordered by what an agent can't infer on its own — most important first.

1. Orientation — one line. What it is, the primary language, the key stack with versions, the project type (app / library / service). Then stop.
2. Setup & build — the real, copy-pasteable commands. Run them first; paste what actually works.
3. Run the tests — the single-test command and the full-suite command. Ranked above build: tests are the agent's only way to check its work against reality instead of trusting a stale belief.
4. Where things live — entry points and key directories only. Never an ls dump — the agent can list files itself. Just the non-obvious "start here."
5. Conventions — only rules that resolve real ambiguity, written as examples ("use SerializerV2 for new features; V1 is back-compat only"), not "write clean code." Anything the linter already enforces → point at the config, don't restate it.
6. Guardrails — Always / Ask-first / Never. (Detail below.)
7. Definition of Done — mechanically checkable, so the agent can know it's finished instead of guessing: "Done when lint exits 0, tests pass, changes committed."
8. When stuck — the escalation default: ask a clarifying question, propose a short plan, or open a draft PR with notes — don't push large speculative changes.
9. Security & secrets — where secrets live (.env, see .env.example) and which files never to read or commit. Never the values.
10. Commit & PR — message format and branch rules.

Footer — a freshness marker (a last-updated date). In a monorepo, use nested AGENTS.md files: nearest wins, and the root points outward.

Situational (add only if the project warrants it, and only if it passes the filter): an Architecture section for deployment or structure shape; non-standard tooling named explicitly (uv, bun, specific MCP servers — a tool named in AGENTS.md gets reached for far more often); and good/bad example pointers that link the canonical file rather than pasting it.

Guardrails, in three tiers

The single highest-value section — a flat "don't" list, upgraded into a safety map the agent can actually navigate:

## Guardrails
- Always: read files, run the tests, build.
- Ask first: dependency installs, deletions, migrations, schema changes.
- Never: force-push, push to main, write to prod, commit secrets.

Now the agent knows what's free, what needs a human, and what's a landmine — before it acts, not after.

How long?

• Start 20–50 lines. Grow a section only when an agent repeatedly gets it wrong; cut it when the convention changes.
• ~150 lines is the practical ceiling. Past that, inference cost climbs with no measurable gain.
• 32 KiB is the hard ceiling — some agents truncate beyond it. Over budget → split into nested files, don't cram.

Anti-patterns

1. Letting an AI write the whole thing. The strongest finding in the field: auto-generated instruction files measurably reduce task success — the model pads them with plausible-sounding rules the agent then over-obeys. Author from truth, not from a guess.
2. Duplicating the README. README is what and why; AGENTS.md is how-to-work-here.
3. Vague prose ("be careful", "clean code"). No verification hook — ignored.
4. Directory dumps. The agent can run ls.
5. Restating linter-enforced style. Point at the config; don't hand-copy the rules.
6. Staleness. Update it in the same PR as the change — a stale file is obeyed with full precision.
7. Secrets in the file. Ever.

A complete example

Around 35 lines. Every line traces to a real command, a real file, or a real constraint — nothing invented:

# AGENTS.md — faf-cli

CLI for the .faf context format. TypeScript (Bun runtime). Type: CLI tool.

## Setup & build
bun install
bun run build

## Run the tests
bun run test              # full suite
bun test tests/interop    # a single area

## Where things live
- src/cli.ts — entry point (command dispatch)
- src/interop/ — the exporters (AGENTS.md, CLAUDE.md, ...)
- src/detect/ — repo detection (stack, commands, key files)
- tests/ — bun test suites

## Conventions
- Stage files by name — never git add -A.
- Match the surrounding file's idiom; keep tsc clean.

## Guardrails
- Always: read files, run bun run test, build.
- Ask first: dependency installs, deleting files, changing .github/workflows.
- Never: git push --force, push straight to main, commit secrets.

## Definition of Done
Done when: bun run lint exits 0, bun run test passes, changes committed with a conventional message.

## When stuck
Ask a clarifying question, propose a short plan, or open a draft PR — don't push large speculative changes.

## Security & secrets
Secrets live in .env (see .env.example). Never read or commit .env.

## Commit & PR
Conventional commits (feat: / fix: / test:). Branch off main; never commit to main directly.

Keeping it true

Getting the file right is an afternoon. Keeping it true — across every repo, on every change, forever — is the part that breaks. There are two failure modes, and they're opposite: hand-write it and leave it, and it rots; ask an AI to write the whole thing, and it bloats. Both drift without care. The fix is the same either way: every line traces to a fact — a real command, a real file, a real constraint — and the file changes in the same PR as the code.

AGENTS.md quality sits on a short ladder. We work the top two rungs: BETTER and BEST.

NONE → GOOD → BETTER → BEST

BETTER — author from repo facts

A dedicated human maintainer can keep a hand-written file honest. When that gets old, author the managed lines from what the tree already declares — real build and test commands, entry points, toolchain conventions. Nothing invented. Nothing padded. Hand-written judgment stays outside the managed markers; re-runs refresh only the facts block.

npx agents-md-facts            # author / refresh AGENTS.md
npx agents-md-facts --check    # fail if missing or stale

Open-source, stack-agnostic — no FAF required. agents-md-facts on GitHub.

BEST — durable DNA, then export

When you want persistent project context, put durable DNA at the root as project.faf — the package.json for context. FAF scores and records that DNA, then authors and syncs instruction surfaces from verified facts (including AGENTS.md). Change the code, re-run export; the managed block stays current. Content you add outside the managed block is preserved.

npx faf-cli export --agents

Follow-on, not a religion. Write a great AGENTS.md by hand, or author BETTER from facts today. When you want root DNA underneath the file — scored, re-exportable, persistent — hand it to FAF.

Further reading

• The series — AGENTS.md on DEV (field guide → hands-on → staleness → discipline → from facts).
• The standard — agents.md (the spec itself).
• BETTER tooling — agents-md-facts (npx agents-md-facts).
• The research — Beyond the Bloat and Recovered in Translation: why context built from a repo's own signals — real commands, real paths, no prose — is exactly the "minimal requirements" ETH Zürich's SRI Lab pointed to.
• The format underneath — the .faf format and faf.one (BEST rung).
• BEST tooling — faf-cli on npm (npx faf-cli export --agents).