Agent Harness · Reference sheet
AGENTS.md structure
The rules file is an index of about 40 lines: commands, definition of done, invariants, 1-3-1, links. Commit it before any feature code. This is one working shape: keep the sections, word them for your project.
Claude Code only: the quick viewClaude Code reads
AGENTS.md natively (v2.1.277+) when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the folder or above. The root file is re-read from disk after /compact. A nested tests/AGENTS.md loads when Claude reads a file there. .claude/rules/*.md with paths: loads only for matching files. Aim for under 200 lines per file, and about 40 for the index. Legend: verified 2026-09-30 = checked against the docs on that date; unverified = test it yourself before relying on it. Skip the Codex and Antigravity columns unless you use them.The index skeleton (~40 lines)
The rules file is an index: it gives the rules that must always hold, and links to depth.
# <Project>: agent instructions
<One line: what it is.> <Stack, with versions.> Brief: `BRIEF.md`.
## Commands
- Build: `<command>`
- Test: `<command>`
- Format check: `<command>`
- Run: `<command>`
## Definition of done (every slice)
1. <The gate that must pass (skill `quality-gate`).>
2. <Which reviewer agent reads the diff, and when.>
3. <Who approves the commit. Never commit or push otherwise.>
## Invariants (never break; details in docs/ai/invariants.md)
- <Rule that stays true however the code changes.>
- <Forbidden pattern, named as a pattern.>
- <Out of scope: what to decline.>
- <Secrets and environment rules.>
## When you are stuck: 1-3-1
<Paste the section from the 1-3-1 sheet.>
## Workflow
<One line, one link: docs/ai/workflow.md>
## More context (read when relevant)
- <Topic>: docs/ai/<file>.mdWhat each section is for
| Section | Holds | Why it is here |
|---|---|---|
| One line + stack | What the thing is, .NET version, test framework, where the brief is | Orientation in 2 lines. The agent cannot ask "what is this?" cheaply. |
| Commands | Exact build, test, format, run commands | Wrong guesses cost a turn each. Copy-paste beats description. |
| Definition of done | 3 to 5 numbered, checkable conditions | "Done" becomes evidence, not opinion. Names the skill and reviewer to run. |
| Invariants | Rules that must survive any refactor; forbidden patterns; out of scope; secrets | The part the agent must never trade for a green test. One line each; depth lives in docs/ai/invariants.md. |
| When stuck: 1-3-1 | The hand-over format and what triggers it | Turns a silent decision into a question (sheet). |
| Workflow | One link | Plan, slice, gate, review, commit. Kept out of the index so the index stays short. |
| More context | Links, one per topic, with "read when relevant" | Progressive disclosure: depth is loaded only when the task needs it. |
The pruning testFor each line ask: "Would removing this cause the agent to make mistakes?" If not, cut it. (Claude Code best practices; target under 200 lines per file.)
Appendix: the reference solution's AGENTS.md, verbatim
# StockApi: agent instructions
A small inventory API: products with a unique SKU and a stock count; orders reserve stock.
.NET 8, ASP.NET Core controllers, EF Core + SQLite, xUnit. Brief: `BRIEF.md`.
## Commands
- Build: `dotnet build -warnaserror`
- Test: `dotnet test`
- Format check: `dotnet format --verify-no-changes`
- Run: `dotnet run --project src/StockApi` (API on the port printed at startup)
## Definition of done (every slice)
1. The quality gate passes: format check, then build, then test (skill `quality-gate`).
2. A reviewer agent has read the diff: `test-reviewer` always; `stock-invariant-reviewer` when stock or orders change.
3. The human has approved the commit message drafted by the `commit` skill. Never commit or push otherwise.
## Invariants (never break; details in docs/ai/invariants.md)
- Stock never goes below zero, including under concurrent orders.
- Every stock change is ONE guarded UPDATE (`ExecuteUpdateAsync` with `Stock >= n` in the WHERE); never read-then-write.
- Target framework is `net8.0`. Do not change it.
- Out of scope: auth, UI, payments. Decline and say so if asked to add them.
- No secrets in git: config values come from environment variables; `.env` is git-ignored.
## When you are stuck: 1-3-1
If a tool, SDK, test provider or environment blocks you, or a fix would change an invariant,
a requirement or the machine: STOP. Do not work around it. Reply with exactly
- **1 problem**: what is blocked and why it matters,
- **3 options**, with the trade-off of each,
- **1 recommendation**,
then wait for the human's decision. Never install, launch, downgrade or delete to get unstuck.
## Workflow
Plan first, then one slice at a time: docs/ai/workflow.md
## More context (read when relevant)
- Invariants and why: docs/ai/invariants.md
- Code layout and naming: docs/ai/conventions.md
- How to test (no EF InMemory): docs/ai/testing.md
- Deliberate decisions: docs/decisions/What not to put in
| Do not put in | Why | Put it instead |
|---|---|---|
| Narrative ("we decided to use SQLite because...") | The agent reads every line every session; story costs context and adds no rule | An ADR (architecture decision record: a short "this is deliberate, here is why" file) in docs/decisions/, linked from the index |
| How-to for humans (clone, install, run the UI) | Humans need steps; agents need constraints | README.md |
| Long code blocks | They go stale and the agent copies them literally | A pointer to the reference shape: "copy ProductsController" |
| Text duplicated from other docs | Two copies drift; the agent obeys whichever it saw last | One home, plain link from the index |
| Rules for one folder only | Loads everywhere for no benefit | Nested tests/AGENTS.md or a path-scoped rule |
| Things the tool already enforces | Prose is weaker than a guard | A permission rule, hook or test (sheet) |
Commit-it-first checklist
- Written before any feature code, committed as
chore(harness): add agent rules(in one real session the rules file was written at the very end, so it steered nothing). - No
CLAUDE.mdorCLAUDE.local.mdnext to it (or one that only says@AGENTS.md). - Under ~40 lines; every line passes the pruning test.
- Commands run as written (paste them into a terminal once).
- Every invariant names its forbidden pattern and, where possible, the guard test.
- The 1-3-1 section is in, and "never install, launch, downgrade or delete" is in it.
- Every link resolves to a file that exists.
-
.gitignorehasbin/ obj/ tmp/ *.db .env. - Checked in a NEW session: "What are this repo's invariants, and where did you read them?"
The docs/ai/ files
| File | Holds | Loaded |
|---|---|---|
docs/ai/invariants.md | Numbered invariants with the forbidden pattern and its failure mode (oversell), the guard test, environment and secrets rules | Read when relevant (linked) |
docs/ai/workflow.md | The loop: explore, plan, one slice, gate, review, commit; mid-task changes; git rules; when stuck | Linked from Workflow |
docs/ai/conventions.md | Layout, reference shape to copy, error codes, async, pinned versions, SQLite DateTimeOffset note, comment style | Read when relevant |
docs/ai/testing.md | Real SQLite through the factory; never EF InMemory; concurrency test per stock change; test naming | Read when relevant |
tests/AGENTS.md | Test-only rules, loaded in addition to the root file when working in tests/ | Nested, on read |
.claude/rules/efcore.md | Claude-only rules with paths: for Data/ and Services/ | When a matching file is read |
docs/decisions/NNNN-*.md | ADRs: the oddity is intentional, here is why | Linked from the index and from code comments |
Load rules per tool
| Claude Code | Codex | Antigravity | |
|---|---|---|---|
| Reads AGENTS.md? | Natively, when the project has no CLAUDE.md v2.1.277+ · verified 2026-09-30. Some sessions still read CLAUDE.md only: versions before v2.1.277, sometimes the first session after upgrading, and before v2.1.281 some Amazon Bedrock or telemetry-off sessions v2.1.281+. Use the fallback below there | Yes: the main rules file. Global ~/.codex/AGENTS.md (or AGENTS.override.md), then every directory from the git root to the cwd | Yes: AGENTS.md or GEMINI.md are read as always_on. Global: ~/.gemini/AGENTS.md or GEMINI.md |
| What suppresses it | A CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the cwd or above. ~/.claude/CLAUDE.md and .claude/rules do not count verified 2026-09-30 | Per directory the override file is checked first, then AGENTS.md, then fallbacks | Not documented unverified |
| Fallback | A CLAUDE.md containing @AGENTS.md; it is never read twice. /config > Project instructions can read both | None needed | None needed |
| Nested files | A subdirectory AGENTS.md loads when Claude reads a file there. All parents of the cwd load at start | Concatenated root-down; closer files come later so they win | Not documented unverified |
| Path-scoped | .claude/rules/*.md with YAML paths: globs; triggers when Claude reads a matching file. No paths = always loaded | Use a nested AGENTS.md per directory | .agents/rules/*.md with frontmatter trigger: glob and globs: (also always_on, model_decision, manual). Legacy .agent/rules/ is still read |
| Size limit | Under 200 lines per file (adherence drops). Imports @path (max 4 hops) do not save context: imported files load at launch | project_doc_max_bytes: 32 KiB by default, across the concatenation | 24 KB per rule file; always-on and global rules share a 20,000-token budget (docs) verified 2026-09-30 |
| Survives compaction | Project-root file is re-read from disk after /compact | Not documented | Not documented |
Sources: Claude Code memory · Context window · Codex AGENTS.md · Antigravity rules · agents.md. Last verified 2026-09-30.
Taught in: Lesson 2: Rules files · Lesson 3: 1-3-1 · Lesson 9: Writing for the agent · Lesson 11: Capstone
Other sheets: The four guards · Commit skill · 1-3-1 · Glossary · Tool equivalents