AGENTS.md
The checked-in prompt contract agents read before touching a scope
Each AGENTS.md answers the same question at a different point in the tree: what should the agent know here?
At the root, the answer is repo identity, ownership boundaries, commands, and source-of-truth rules. Near an app or package, the answer is local ownership, skill activation, examples, and invariants. The file is the checked-in prompt contract agents read before touching that scope.
In Harness repos, AGENTS.md files are generated through the setup flow. They are repo-tailored, but they are not personal scratchpads. Durable changes go back to the harness baseline, pack source, scaffold logic, or owning repo source that generated the surface.
Contract
Each file should answer only the local questions:
- what this scope owns
- what this scope must not own
- which skills activate here
- which examples or sources guide the work
It should avoid long tutorials. If a rule needs full explanation, link to a wiki page, runbook, spec, or skill contract.
Root Prompt
Root AGENTS.md is repo orientation. It gives the agent the repository identity, app/package boundaries, root command conventions, and source-of-truth rules that apply everywhere.
It should route the agent into the right part of the tree. It should not absorb app-specific implementation detail that belongs under a scoped file.
Scoped Prompts
Scoped AGENTS.md files are activation points. They name the local skills, examples, source inspection targets, and invariants that matter near the files being changed.
For example, a CLI scope can point the agent toward scaffold behavior and relevant upstream command implementations. A wiki scope can point toward routed MDX ownership and docs workflow skills. The guidance lives near the code because that is where it becomes true.
Mirrors
Harness setup may create compatibility mirrors:
CLAUDE.mdcan symlink to the nearest neutralAGENTS.md.- Runtime-specific harness surfaces can reference
.agents/AGENTS.mdand scoped prompts. .claude/skillscan symlink to.agents/skillsfor compatibility.
The neutral file remains the source. Runtime mirrors should not drift into separate instruction sets.
Change Path
Do not patch generated AGENTS.md files as a local preference.
If the repository changed and the prompt surface is stale, rerun the setup or update flow. If the baseline generated the wrong rule, change the harness baseline, pack source, or scaffold logic. If the prompt needs different product truth, change the owning repo source, spec, doc, or runbook that the setup flow should read.
The file can be reviewed like code, but the durable fix belongs at the source that produces it.