AGENTS.md Guide

AGENTS.md is the source of truth for agent instructions in a harnessed repo. CLAUDE.md is a symlink to it (harness-check invariant #1) so both tools read the same file.

Keep it lean: a map, not an encyclopedia. Apply the pruning test to every line — *"would removing this cause the agent to make a mistake?"* If not, cut it.

Required sections

harness-check invariant #2 requires these headings to exist (they may be short, but they must be present):

• ## Project Structure — an annotated tree, ~20 lines, plus the "where new things go" rule.
• ## Commands — make check is the gate; the target table.
• ## Workflow — OpenSpec, Conventional Commits, when to run the reviewer.
• ## Deploy & Rollback — the deploy path and how to roll back.
• ## Baselines — checks currently relaxed for legacy code (empty is fine).

Most repos also add a short ## Golden Principles block.

Golden Principles

Golden Principles are short (≤10 lines), opinionated, mechanical code-quality rules the gardener skill scans against. Starter set:

• Prefer shared utilities over hand-rolled helpers; extract on the second copy.
• Validate data shapes at boundaries — never build on a guessed shape.
• Keep functions single-purpose; push side effects to the edges.
• Errors are remediation instructions: every failure message ends with what to do next.

docs/references/ — the llms.txt convention

Load-bearing dependencies get an llms.txt-style reference under docs/references/. The agent reads these instead of relying on training data for things like the Workers runtime, wrangler config, or a framework's API. When a dependency's behavior is subtle, vendor its reference here and point to it from ## Project Structure.

Monorepo convention

In a monorepo, each deployable package has its own AGENTS.md at its root, harnessed independently (its own Makefile including Makefile.core, its own /health). A root AGENTS.md describes the workspace and points to each package. make check runs per package. Do not try to make one giant AGENTS.md cover everything — locality beats completeness.

What does NOT belong here

Session-hygiene habits — /clear between tasks, one phase per session — live on this site under Working with the Harness, not in AGENTS.md. Those are operator habits, not repo facts.