Writing Effective AGENTS.md Files

AGENTS.md is a README for coding agents. It lives at the repo root and tells agents how to build, test, lint, navigate, and contribute to the project. Based on the agents.md open format (https://agents.md) and lessons from OpenAI's harness engineering approach.

Core Principle: Map, Not Manual

Keep AGENTS.md short (~100-150 lines). It's a table of contents, not an encyclopedia.

The "one big instruction file" approach fails because:

• Context is scarce. A giant file crowds out the actual task and code.
• Everything-is-important becomes nothing-is-important. Agents pattern-match locally instead of navigating intentionally.
• It rots instantly. A monolithic manual becomes a graveyard of stale rules.
• It's hard to verify. A single blob doesn't lend itself to freshness checks.

Point to deeper docs elsewhere. The agent starts with AGENTS.md and drills into references as needed.