Appendix A — AGENTS.md Reference Patterns

Most context files are full of the wrong content. Not badly written — wrong category.

Use this appendix to: audit an existing context file, decide what belongs in it, and layer multiple files without creating contradictions nobody can detect.

Established in: Chapter 6 (the budget), Chapter 7 (the quadrant), Chapter 9 §9.5 (the division of labour), Chapter 8 §8.9 (contradictions), Chapter 21 (Guide Sprawl).

A.1 What belongs here, and what does not

Chapter 9 §9.5 established the division of labour that governs everything else in this appendix.

A study of 328 CLAUDE.md files found that architectural concerns dominate their content, followed by development guidelines, project overviews, and testing [B] 🔴. And architecture is a structural property of the code — derivable, mechanically, and kept fresh by a pipeline rather than by hand.

So the test for every line in a context file:

Could a machine derive this from the code? If yes, it does not belong here — it belongs in the graph, or it is already checkable by a sensor. If no, it is exactly what this file is for.

Chapter 6 gives the second test, from the context budget: the marginal token can be negative, so add a line only if it is more relevant than the average of what is already there. That bar rises as the file improves, which is why the first few lines help enormously and later ones often do not.

A.2 The audit

Run this on an existing file before adding anything. Most teams delete 40–60% on a first pass.

   FOR EACH LINE OR SECTION, ASK:

   1  Could a machine derive this?              → DELETE, build the sensor
      "the auth module lives in src/auth"          or the graph entry
      "handlers implement the Handler
       interface"

   2  Is it already enforced by a check?        → DELETE
      "always run the formatter"                   the check is the control;
      "use tabs, not spaces"                       the sentence is decoration

   3  Is it a claim about a model's             → DELETE if the deficit
      behaviour rather than about your             has closed. Ch 2: guides
      project?                                     age, sensors persist.
      "be concise", "don't hallucinate",           Drill it (Ch 8 §8.9)
      "always use the edit tool"

   4  Can nobody say why it is here?            → DELETE
      no date, no named failure mode                Ch 21's early warning
                                                    for Harness Theatre

   5  Does it record WHY?                       → KEEP. This is the file's
      a deliberate trade-off, a constraint          entire purpose
      that is not obvious, a decision
      someone would otherwise reverse

Category 3 is the one people resist deleting, and Chapter 2 is the reason to: a rule compensating for a model deficit that three generations have since closed is not neutral. It consumes the scarce budget, and worse, it teaches every reader that the file's contents are decorative.

A.3 Patterns worth keeping

Annotated. Each of these records something underivable.

The deliberate trade-off.

## Known trade-offs

- `orders/legacy_pricing.py` duplicates logic in `pricing/`. This is
  deliberate until the Q3 migration — the two diverge in rounding and
  merging them broke invoices in 2024. Do not "clean this up".
  Added 2026-02-11 · reason: recurring unwanted refactor · review Q4

Records a decision an agent would otherwise reverse, with the incident that motivated it. Chapter 4's cost gradient predicts an agent will keep trying to fix this; the note is what stops it.

The load-bearing convention.

## Conventions that are NOT style

- Every handler returns `Result`, never raises. This is load-bearing:
  the retry middleware distinguishes them and raising bypasses retry.
- Field order in `wire.py` structs is protocol-significant.

(Everything else about style is enforced by the formatter. If it is not
in this list and not enforced, it is habit and you may ignore it.)

The parenthetical is the valuable half. Chapter 5 established that agents cannot distinguish deliberate convention from habit; this states the distinction explicitly and bounds it.

The non-goal.

## Out of scope for agents in this repo

- Do not modify `migrations/`. Ask. Blast radius: irreversible (Ch 13 B2).
- Do not add dependencies. Open an issue instead.

⚠️ These are guides, so they are belief-based (Chapter 11). They inform; they do not enforce. If the consequence is severe, revoke the capability instead — no write access to migrations/, no network egress for package installs. A sentence here is a reminder, not a control.

The escalation instruction.

## When to stop and ask

- The change requires touching more than one bounded context.
- You cannot enumerate the callers of a symbol you are changing.
- A test that was passing now fails and you did not intend to change it.

Chapter 14's escalation quality metric depends on the agent knowing when to stop. This is one of the few things a context file does that nothing else can.

The pointer, not the payload.

## Architecture

See the generated dependency map: `make graph` or `docs/graph.json`.
Layering is enforced by `tests/structural/test_layers.py` — if you are
unsure whether an import is allowed, run it.

Chapter 6's progressive disclosure. Three lines replacing three pages, and unlike the three pages it cannot go stale.

A.4 Layering without contradiction

Chapter 7 found 4,768 context files across 2,586 repositories, with CLAUDE.md pointing to AGENTS.md in 301 cases [A]. Layering is normal. Layering plus no removal plus no detector is Chapter 21's Guide Sprawl.

Galster's authors draw the practical implication, and it is the right one:

Two rules that prevent the failure:

Substantive content lives in exactly one file. If a statement appears in two files it will eventually appear differently in two files, and nothing will tell you.

Never let the agent resolve a contradiction. Chapter 8 §8.9: delegating that means accepting a silent, unlogged, per-invocation decision about which of your stated intentions wins. A contradiction is a defect in the harness and belongs to whoever owns it.

And the honest gap, from Chapter 21 and Chapter 27: there is no contradiction detector. Both Galster's authors and Böckeler name this independently as a missing tool. Until one exists, the single-source discipline above is the only defence, and it is a convention rather than a control.

A.5 Maintenance rules

Five, each traceable to a chapter.

1. Every guide carries a date and the failure it was added for. Chapter 12's fourth prohibition. Undated guides cannot be pruned, so they accumulate. A one-line HTML comment is enough:

<!-- added 2026-03-04 · failure: agent reverted the pricing duplication
     three times · retire when the Q3 migration lands -->

2. Edit, never regenerate. Chapter 6 §6.7: contexts collapse. Repeated wholesale rewriting degrades toward genericity, dropping exactly the specific, hard-won detail that looks like noise to a summariser. A regenerated AGENTS.md will read better and will have quietly deleted the three lines doing all the work.

3. Prune on a schedule. If nothing is ever removed, dilution is where you end up by default.

4. Do not use this file to enforce anything that matters. Chapter 11: guides are belief-based and defeated by injection. Chapter 10 §10.7's ordering — make it impossible, then detect it deterministically, then judge it, then assert it. This file is tier four.

5. Measure whether it is working. Chapter 14's context efficiency — tokens per accepted change — moves in the right direction when a context file is well curated. It is the only feedback available on a file whose failures are otherwise silent.

A.6 A minimum viable file

Everything above, applied. This is what a good context file looks like: short, underivable, dated.

# AGENTS.md

## What this service does
One paragraph. Why it exists, who depends on it, what it must never do.

## Architecture
Generated: `make graph`. Layering enforced by `tests/structural/`.
<!-- deliberately NOT described here — Ch 9 §9.5 -->

## Conventions that are NOT style
- Handlers return `Result`, never raise. Load-bearing: retry middleware.
- Field order in `wire.py` is protocol-significant.
Everything else is enforced by the formatter and may be ignored.

## Known trade-offs
- `orders/legacy_pricing.py` duplicates `pricing/` deliberately until
  the Q3 migration. Merging them broke invoices in 2024.
  <!-- added 2026-02-11 · failure: recurring unwanted refactor · review Q4 -->

## When to stop and ask
- The change spans more than one bounded context.
- You cannot enumerate the callers of a symbol you are changing.

## Out of scope
- `migrations/` — ask first.
  <!-- NOTE: also enforced by revoked write access. This line is a
       reminder, not the control. -->

Roughly forty lines. Chapter 7's evidence says the median repository has one or two context files and little else; the goal is not to make this file bigger but to make every line in it underivable.