Agents Md

28 chapters · 88 min

File Setup

• Create AGENTS.md at the repository root.
• If a Claude-compatible entrypoint is required, symlink CLAUDE.md to AGENTS.md.
• Do not maintain divergent AGENTS.md and CLAUDE.md copies.

Default Sections

Use only sections that add non-obvious value.

Writing Rules

• Use headings, bullets, and tables; avoid paragraphs.
• Use repo-relative paths; avoid vague references like “see docs”.
• Reference existing docs/specs/policies instead of copying them.
• List exact external files for setup, architecture, API specs, security, release, and policy docs when they exist.
• Prefer file-scoped test/lint/typecheck commands; include full builds only when no narrower command exists.
• Put commands in tables when there is more than one.
• Keep one rule per bullet.
• Keep rationale out unless it prevents a likely mistake.
• Do not restate linter, formatter, or typechecker config.
• Do not list installed skills or plugins.
• Do not include generic quality slogans.

External Reference Rules

Good:

Anti-Patterns

• welcome text, intros, conclusions, or pleasantries
• long prose explaining why instructions matter
• duplicated content from README.md, CONTRIBUTING.md, or policy docs
• project-wide commands when file-scoped commands are available
• nested AGENTS.md files that repeat root instructions