Writing a Good AGENTS.md

Help users write, audit, and improve AGENTS.md — and the harness-specific files that sit alongside or import it.

Core Model

AGENTS.md is an onboarding document, not a configuration dump. It answers three questions:

• WHY — purpose of the project and its components
• WHAT — stack and structure the implementer needs to act, not an explorer's tour (see Sub-Agent Context Loading)
• HOW — build, test, verify commands the agent runs

Everything else lives elsewhere: linter config, sub-documents, one-off instructions, and orientation material (README/ADR), which search agents find on their own.

Audit Checklist