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

Level	Content
Root	Monorepo purpose, navigation, shared tools
Package	Package purpose, tech stack, conventions

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