Include only what genuinely helps, ruthlessly cut everything else. These principles apply regardless of language or framework — C#, Python, TypeScript all follow the same rules.

Core Principles

• Minimum viable requirements. Ask of each line: "Does this earn its cost on nearly every session?" If not, cut it. Every line loads on every session — brevity has direct cost benefits.

• Two failure modes. (1) Length — as instruction count grows, compliance degrades uniformly, not just for new instructions. (2) Task-irrelevant requirements — correct instructions not needed for the current task still get followed, increasing cost and reducing success.

• Don't send an LLM to do a linter's job. Style guidelines add instructions and irrelevant context. Use actual linters, wired to hooks if the harness supports it.

• Never auto-generate. Auto-generated files are stuffed with documentation the agent can read directly. Write by hand.

• Architecture and overview sections have weak evidence in root files. Exception: scoped sub-files can carry richer context — they only load when the agent is already working in that area.

Single File vs. Hierarchical System

Single root file for simple projects: one app, one language, one team. Keep it under 100 lines.

Hierarchical system for monorepos, large codebases, or multiple apps/packages/services. The harness auto-loads AGENTS.md files as the agent navigates — apps/web/AGENTS.md only loads when the agent works there.

Hierarchical Rules

Place files at semantic boundaries — where responsibilities shift or contracts matter. Not in every directory.

Least Common Ancestor for shared knowledge — shared facts belong in the shallowest file covering all relevant paths. Never duplicate across siblings.

Downlink from parent to children — reference child files so the agent can follow the hierarchy:

Sub-areas

• packages/ui/AGENTS.md — component library conventions
• apps/api/AGENTS.md — API server, auth, database access

Build leaf-first — write deepest files first. Parents summarize children's AGENTS.md files, not raw code.

Scoped files can be richer — entry points, invariants, and pitfalls are appropriate in a file that only loads for one service.

Writing a New AGENTS.md

Project or Area Name

One sentence: what it does and why it exists.

Stack

Tech stack. Package manager or build tool (be explicit — agents assume defaults). Path aliases if non-standard. Infrastructure if non-obvious (DB, cache, queue). Directory tree only if ownership boundaries aren't obvious. 1-2 levels max.

Development

Verification commands only: typecheck, lint, test. What to run before finishing. Skip inferrable commands. Include non-obvious ones whose names don't reveal purpose (e.g. cf-typegen, db:migrate, dotnet ef database update).

Conventions

Only things the agent can't infer from reading the code. No style rules — use a linter.

A Reference Docs section is fine — only add a pointer if the agent genuinely needs to read it before working in that area.

Auditing an Existing AGENTS.md

Measure first: total lines, distinct instructions, style rules, overview sections. Classify each: essential and universal (keep), task-specific or architectural (cut or demote to pointer), style/lint rule (remove), redundant or stale (remove).

For hierarchical systems: check whether root content belongs in a scoped sub-file, and whether sub-files duplicate knowledge that belongs at their LCA.

Present before/after line counts, what was cut and why, and the complete rewritten file.

Maintenance

On significant changes, update affected AGENTS.md files leaf-first. A CI agent that detects changed files and proposes updates is worth building.

Anti-Patterns to Flag

Command dump — inferrable commands like dev , build , start listed in full.

Deep tree — directory structures more than 2 levels deep. Replace with a sentence.

Architecture tour — system overviews in a root file. One sentence of purpose, or push into a scoped sub-file.

Style guide — formatting rules. Use a linter.

Code museum — large inline snippets. Use file:line references.

Hotfix graveyard — accumulated one-off corrections. Delete them.

Auto-generated blob — output from auto-init commands. Rewrite from scratch.

Stale reference — outdated paths or commands. Update or remove.

Duplicated siblings — the same fact in two sub-files. Hoist to their LCA.