managing-agents-md

Managing AGENTS.md

Overview

AGENTS.md is a README for AI agents. It tells any AI coding tool — Claude Code, Copilot, Cursor, Codex — how to navigate and work with your codebase. Keep it updated as the project evolves.

When to Create or Update

Create AGENTS.md when:

• Setting up a new project or monorepo
• Adding a significant new feature directory (5+ related files)
• Introducing an extensible or polymorphic system
• A codebase has no AGENTS.md and you're doing substantial work in it

Update AGENTS.md when:

• Changing architectural patterns or project structure
• Adding new build/test/deploy commands
• Modifying base classes, registries, or extension points
• Adding significant new directories

Do NOT create for:

• Simple utility directories
• Single-purpose modules
• Non-extensible features
• Directories with fewer than 5 related files

Tier Structure

For monorepos or large projects, use a hierarchical approach:

Root AGENTS.md         → Project overview, tech stack, global conventions
├── app/AGENTS.md      → App-specific architecture, commands, patterns
│   └── feature/AGENTS.md → Feature-specific extension points

Each tier adds specificity. Agents read from root down to the most relevant file.

Template

# AGENTS.md — [Project or Directory Name]

Brief one-line description of this part of the codebase.

## Commands

\`\`\`bash
npm run dev      # Start development server
npm test         # Run tests
npm run build    # Production build
\`\`\`

## Project Structure

\`\`\`
src/
├── api/          # REST endpoints (~12 files)
├── services/     # Business logic (~8 files)
├── models/       # Data models (~6 files)
└── utils/        # Shared utilities (~4 files)
\`\`\`

## Key Patterns

[Describe the main architectural patterns, data flow, or conventions]

## Boundaries

### Always
- [Pattern to always follow]
- [Convention to always use]

### Never
- [Anti-pattern to avoid]
- [Dangerous operation]

### Ask First
- [Risky change that needs confirmation]

CLAUDE.md Companion

If the project also uses Claude Code, create a CLAUDE.md that imports the AGENTS.md:

@AGENTS.md

## Claude-Specific
- [Any Claude Code-specific instructions, hooks, or skill references]

This avoids duplicating content while adding Claude-specific configuration.

Anti-Patterns

Stale documentation: An outdated AGENTS.md is worse than none. Update it when the code changes.

Too granular: Don't create AGENTS.md for every directory. Only for significant architectural boundaries.

Duplicating README: AGENTS.md is for AI agents, not humans. Focus on what an agent needs to navigate and modify code correctly — commands, patterns, boundaries.