AGENTS.md Creation & Refactoring

Create minimal, focused AGENTS.md files that use progressive disclosure.

Core Principles

1. Instruction budget: LLMs can follow ~150-200 instructions consistently. Every token loads on every request.
2. Progressive disclosure: Give agents only what they need now, point elsewhere for specifics.
3. Avoid staleness: Don't document file paths—they change. Document capabilities and domain concepts.

What Belongs in Root AGENTS.md

Only these essentials:

• One-sentence project description (anchors agent decisions)
• Package manager (if not npm)
• Non-standard build/typecheck commands

Everything else goes elsewhere.

Refactoring Workflow

When refactoring an existing AGENTS.md:

1. Find contradictions: Identify conflicting instructions, ask user which to keep
2. Extract essentials: Pull out only what belongs at root level
3. Group the rest: Organize into logical categories (TypeScript, testing, API design, etc.)
4. Create file structure: Output minimal root + separate files with markdown links
5. Flag for deletion: Remove instructions that are:
   • Redundant (agent already knows)
   • Too vague to be actionable
   • Overly obvious ("write clean code")

Progressive Disclosure Patterns

Separate Files

# Root AGENTS.md
For TypeScript conventions, see docs/TYPESCRIPT.md

Nested Documentation

docs/
├── TYPESCRIPT.md → references TESTING.md
├── TESTING.md → references test runners
└── BUILD.md → references build config

Monorepo Structure

Example Minimal AGENTS.md

React component library for accessible data visualization.

Uses pnpm workspaces.

## Conventions
- TypeScript: see docs/TYPESCRIPT.md
- Testing: see docs/TESTING.md
- API patterns: see docs/API.md

Anti-Patterns to Fix

• Auto-generated files: Bloated with "useful for most scenarios" content
• File path documentation: Goes stale quickly, poisons context
• Accumulated rules: "Ball of mud" from months of one-off additions
• Forcing language: Excessive "ALWAYS", "NEVER", all-caps directives
• Obvious instructions: Things the model already knows

Creation Workflow

When creating a new AGENTS.md:

1. Ask user for one-sentence project description
2. Identify package manager (default npm needs no mention)
3. Check for non-standard build/typecheck commands
4. Keep it under 10 lines if possible
5. Create separate docs/ files for domain-specific guidance