AGENTS.md Guidelines

Core Principles

• •Keep root AGENTS.md as small as possible; it loads on every request.
• •Use progressive disclosure: link to deeper docs for details.
• •Prefer stable concepts over volatile paths or time-sensitive notes.
• •Avoid “ball of mud” growth; don’t add rules for every mishap.
• •Keep instructions concise; assume the agent already knows basics.

Essentials Only

Root AGENTS.md should usually include:

• •One-sentence project description
• •Package manager if non-default
• •Non-standard build/typecheck commands
• •Pointers to deeper docs

Progressive Disclosure

• •Move language, testing, and workflow rules into separate docs.
• •Link to those docs from AGENTS.md.
• •Keep guidance domain-based, not file-path based.
• •Avoid deep reference chains; link one level deep when possible.

Staleness Rules

• •Avoid exact file paths unless they are stable interfaces.
• •Avoid dates or time-based instructions.
• •Prefer capability descriptions over structure hints.

Monorepo Guidance

• •Use root AGENTS.md for shared rules.
• •Use package-level AGENTS.md for package-specific conventions.
• •Keep each level focused and minimal.

Instruction Design

• •Start with a TL;DR checklist for fast scanning.
• •Include clear triggers and skip cases to prevent overuse.
• •Provide ordered steps with explicit outputs.
• •Use strict format rules with correct/incorrect examples.
• •Add a decision tree for edge cases when needed.
• •Include validation and debugging tips to reduce failure loops.
• •Make naming conventions explicit.
• •Define archive or completion criteria.
• •Keep terminology consistent.

Quality Checklist

• •Description includes what + when, third-person.
• •Root AGENTS.md is short and link-heavy.
• •TL;DR + triggers + steps are present when needed.
• •No duplicated guidance across files.
• •Terminology is consistent.
• •Examples are concrete and brief.
• •Instructions fit an "instruction budget".