Writing AGENTS.md
Most AGENTS.md files are lists of things any repo could say: "write tests,"
"don't commit secrets," "use meaningful commit messages." An agent reads
that once and it changes nothing, because it names no specific failure this
repo actually had and no mechanism that would catch a violation. This skill
is built from five AGENTS.md files that do change behavior — velo,
zaynor, locoporcolt, annaconda, nexo — read side by side to extract
what they have in common structurally, despite covering unrelated domains
(a ZK engine, a DFIR postmortem tool, a firearms marketplace, a live
forensic backend, a Rust decision-graph system).
Composes with the library:
- decision-record-discipline — an AGENTS.md invariant is a standing decision record; it needs the same Forces/Assumption/Revisit-trigger thinking, just written as a rule instead of a narrative
- claim-provenance-discipline — a rule with no traceable origin decays into doctrine the same way a finding does; ground every invariant in something checkable (a file, a test, an incident), not assertion
- git-discipline — the git-hygiene rules that appear in most of the five examples (forward-only history, restore-point tags, verify before claiming) are that skill's content; cite it instead of restating it
- irreversible-action-gate — a
git commit/git pushauthorization is per-action, not per-session, the same way that skill treats any other hard-to-reverse action; see §11 below
What AGENTS.md is, and what it is not
MUST state, at the top of the file if a generic discipline guide
(CLAUDE.md) also exists in the repo, which file wins when they conflict,
and what each one is actually for. zaynor's framing: CLAUDE.md is the
portable development-discipline guide (git hygiene, editing discipline, the
reasoning loop) — generic, could apply to any repo. AGENTS.md is this
product's operating manual: its architecture, its authority boundaries, its
own invariants. nexo goes further and makes AGENTS.md itself explicitly
subordinate to docs/: "If anything below conflicts with those files, the
files in docs/ win — this file is a summary and a checklist, not a new
source of truth." Either hierarchy is fine; an unstated one is not — an
agent facing a conflict between two files needs a decision procedure, not
two equally authoritative documents.
MUST NOT duplicate what a human-facing README.md or CONTRIBUTING.md
already says in full — velo's AGENTS.md opens by naming
CONTRIBUTING.md as "the human-readable source of truth for the same
conventions" and positions itself as the agent-specific complement, not a
second copy.
The anatomy: what makes an invariant actually load-bearing
A line that says "verify ownership before returning an object" is an opinion. The same line becomes an invariant an agent will actually respect when it carries these attributes — drawn directly from the strongest examples in the five files:
1. A named enforcement mechanism, not just an instruction
SHOULD name, for each invariant that can be, the mechanism that would
catch a violation: a Semgrep rule (locoporcolt: "Enforced by a Semgrep
rule (contact-disclosure-missing-clu-gate)"), a database CHECK constraint
(locoporcolt: "the CHECK clu_verif_photo_erased_on_resolve makes a
resolved row that still holds it a state Postgres rejects"), a test that
must stay green (annaconda: "tests/test_determinism.py guards this; it
must stay green"), or a CI gate (zaynor's docs_check.py / DOCS_MAP
mechanism that blocks a PR whose code diff has no matching doc update). An
invariant with no named mechanism is a request for the agent's good
behavior; an invariant with one is a fact about what will happen if the
agent ignores it. State honestly which kind each one is — don't imply
mechanical enforcement that doesn't exist.
2. The "why," specific enough to be falsifiable
MUST give a reason concrete enough that a reader could check whether it
still holds — not "for security" or "for maintainability." locoporcolt's
Mercado Pago webhook invariant is the sharpest example: it doesn't just say
"verify the signature," it explains why the obvious pattern (verify over
the raw body, the Stripe convention) is actively wrong for this specific
provider, quotes the exact signed manifest format, and names the SDK
version it was checked against. A reason that specific can be re-verified
later; "for security" cannot.
3. Grounded in an actual incident, not a hypothetical
SHOULD cite the real event that taught the lesson, when one exists.
velo: "it is why PR #6 had to be closed rather than merged, and it nearly
happened again to PR #9 on a base that was three commits behind." A rule
grounded this way survives the question "is this really necessary?" — the
answer is "it already went wrong once, here's the PR." A rule presented as
pure hypothetical caution invites exactly that skepticism, and loses it.
4. Asymmetric failure modes named explicitly
SHOULD, when a rule mediates between two failure directions, say which
one is worse and why the rule is biased toward it. locoporcolt's
requires_clu inheritance rule: "the two failure modes are not symmetric —
over-gating is visible and gets reported, under-gating publishes firearms
with no CLU and is silent — so the flag is forced up, never rejected." This
tells an agent which way to err under genuine uncertainty, which a bare
"the flag propagates down" does not.
5. Numeric values flagged as decisions, not defaults
MUST mark any magic number an agent might be tempted to "clean up" as a
deliberate decision with its current value stated, per locoporcolt's
"Numeric thresholds are decisions, not defaults to normalize" section — a
list of every rate limit, TTL, and threshold in the system with a one-line
reason where non-obvious. Without this, a well-intentioned agent doing an
unrelated refactor "normalizes" a rate limit that was actually sized against
a specific abuse pattern.
6. One dominant invariant is allowed when that's the truth
MAY structure the whole file around a single invariant if the
architecture genuinely has one center of gravity — annaconda's "The one
invariant (do not break this)": the LLM never touches the verdict,
everything else in the file is either a consequence of that rule or
unrelated setup/ops content. Padding a file with invented secondary
invariants to look thorough is worse than naming the one real one clearly.
7. A repo map with one-line purpose per module
SHOULD include a directory tree annotated with what each part is for,
not just its name — annaconda's repo map states, per directory, the
specific invariant that module carries (e.g. "stdlib-only, no floats" next
to core/). This orients a fresh agent in seconds instead of requiring it
to infer architecture from file contents.
8. Operational gotchas that already cost real time
SHOULD document the invisible failure a deploy/setup step produces, not
the obvious one — annaconda: "GOOGLE_CLOUD_PROJECT is not injected by
Cloud Run... without it the store degrades to memory and the fleet's
continuity claim stops being true," with the exact confirmation check
(/health says "case_store":"firestore"). A gotcha worth documenting is
one that fails silently and plausibly, not one that throws an obvious error.
9. Definition of Done as a checklist mirroring the invariants
MUST close with a checklist a reviewer (human or agent) can literally tick against a diff, and MUST have every checklist item trace back to a stated invariant or mechanism earlier in the file — a checklist item that introduces a new rule nobody explained is a sign the file's body is incomplete, not that the checklist is thorough.
10. Verified commands, not remembered ones
MUST give the actual, current command to build/test/lint — copy-pasted
from a real run, not recalled — and SHOULD state what a green result
actually proves ("the tool-layer allowlist tests pass," per zaynor) rather
than let a passing suite imply more than it checked.
11. Who may commit where, and the owner/agent asymmetry
MUST state explicitly, per repo, two separate things — collapsing them into one vague "use branches" line is how an agent ends up guessing:
- Where direct commits to the trunk are allowed at all, and for whom.
Some repos forbid it for everyone, owner included —
zaynor: "Nobody pushes straight tomain— not the owner, not the team, not an agent," enforced mechanically by branch protection, because with several people (human or agent) committing in parallel, an unreviewed direct push is exactly what the others don't find out about until it costs the most. Other repos give the maintainer direct-to-main latitude that a collaborator or an agent does not have — that asymmetry is legitimate, but MUST be written down as a rule, not left to be inferred from who happens to have push access. A collaborator or an agent working here MUST branch:git checkout -b <type>/<short-description> origin/main, never commit to the trunk directly, regardless of what the maintainer's own workflow looks like. - Whether an agent's write access to files also means standing
permission to
git commit/git push. It does not, by default, and the file should say so.zaynor's exact framing is the one to reuse: "An agent may stage changes and propose a commit message, butgit commitandgit pushonly run after the maintainer explicitly authorizes that specific action in the session. A general instruction to work on the repo is not commit permission." MUST treat this as per-action, not per-session — an authorization to commit once is not a standing authorization for the rest of the session, the same way a user approving one destructive action elsewhere doesn't imply approval for the next one (irreversible-action-gate's territory, applied to git specifically).
A repo that skips this either gets an agent that asks permission for everything (friction on work that was already authorized) or one that commits and pushes on its own judgment (the actual incident this section exists to prevent) — an unstated policy defaults to the second, more dangerous reading, because "I have write access" is the easier inference for an agent to make from silence.
Distinguish authored content from tool-generated boilerplate
Next.js's next dev (and similar tooling) writes its own agent-guidance
block directly into AGENTS.md (<!-- BEGIN:nextjs-agent-rules --> ...
<!-- END:nextjs-agent-rules -->), regenerated automatically and meant to
be committed. Two observed instances (zaynor/frontend, locoporcolt) show
the correct handling: commit the block when the tool writes it (removing it
from a diff only recreates the uncommitted change), but do not count it
toward "this repo already has agent documentation" — it teaches an agent
about the framework, not about this codebase's own invariants, and a
9-line tool-generated file with no project-specific content is not a
substitute for the rest of this skill. MUST keep tool-generated blocks
clearly delimited (as the auto-inserted markers already do) and never hand-edit
inside them — the tool will silently overwrite hand edits on its next run.
The throwaway-instance rule
Anna's specific addition, stated because it's not the obvious "don't
commit secrets" advice: MUST, when an agent session creates any test
instance, fixture, or example data for local verification (a sample .env,
a seeded local DB dump, a scratch config with placeholder credentials, a
demo recording), add it to .gitignore immediately, in the same action
that creates it — not as a cleanup step remembered before commit. The
failure this prevents isn't "a secret got committed" (that's
secret-lifecycle-discipline's territory and already obvious); it's
example/synthetic artifacts silently accumulating in git history because
nobody flagged them as throwaway at creation time, which is invisible right
up until someone greps the repo for why it's full of stale fixture files
from six months ago.
Failure modes / anti-patterns
- Generic-checklist AGENTS.md: "write tests," "use meaningful commits," "don't hardcode secrets" — true of every repo, changes nothing about this one, and trains agents to skim past the whole file because none of it is specific enough to act on.
- README duplication: restating the product pitch or setup instructions a human-facing doc already covers, instead of linking to it and adding only the agent-specific delta.
- Invariant with no mechanism and no reason: "always check ownership" — true, but doesn't say what breaks if skipped or what would catch it.
- Unstated hierarchy: an AGENTS.md and a CLAUDE.md (or a
docs/set) that both claim authority with no stated tie-breaker, leaving an agent to guess which one to follow on the first conflict. - Silent magic numbers: a rate limit or TTL that reads as an arbitrary default an agent "cleans up" during an unrelated change, because nothing flagged it as sized against a real constraint.
- Confusing tool-generated boilerplate for project documentation: citing a framework's auto-inserted block as evidence the repo already has agent guidance, when it says nothing about this codebase's actual invariants.
- Checklist items with no upstream explanation: a Definition of Done entry that introduces a brand-new rule the body of the file never stated or justified.
- Copy-pasted template with no incident grounding: an AGENTS.md that reads like it was cloned from another repo and never adapted — no reference to an actual PR, bug, near-miss, or specific numeric value this codebase depends on.
- Unstated commit/push authorization: "agents may work in this repo" with no explicit statement of whether that includes committing and pushing, and no statement of who (if anyone) may work directly on the trunk — an agent then defaults to inferring the broadest reading of its own access.
Verifiable checks
- If both AGENTS.md and a generic discipline file exist, the file states explicitly which one wins on conflict.
- The file does not restate content a human-facing README/CONTRIBUTING already fully covers — it links instead.
- Every stated invariant has either a named enforcement mechanism, an explicit note that none exists yet, or is honestly framed as convention rather than a guarantee.
- Every stated invariant's "why" is specific enough that a reader could check whether it still holds (not "for security"/"for maintainability" alone).
- At least one invariant, where the repo's history supports it, cites the actual incident (PR, bug, near-miss) that motivated it.
- Any rule mediating between two failure directions states which direction is worse and why the rule favors it.
- Magic numbers (rate limits, TTLs, thresholds) are listed with their current value and flagged as deliberate, not left implicit.
- Build/test/lint commands are the actual current commands, and a "tests pass" claim states what the suite covers.
- Tool-generated blocks (framework auto-inserted content) are kept distinct from authored invariants and not counted as "documentation already exists."
- Any throwaway test instance, fixture, or example-data artifact
created during a session is added to
.gitignoreat creation time, not as an afterthought before commit. - The Definition of Done checklist has no item that isn't traceable to an invariant stated earlier in the file.
- The file states who (if anyone) may commit directly to the trunk, and that a collaborator or an agent branches instead — not left to be inferred from access.
- The file states explicitly whether an agent's write access includes
standing permission to
git commit/git push, or whether each such action needs explicit per-action authorization.