agents-md

Original source / Raw SKILL.md

---
name: agents-md
description: Expert AGENTS.md file assistant. Use when users want to create, verify, or improve AGENTS.md files. Helps with creating minimal, focused AGENTS.md files following progressive disclosure principles, verifying existing files for issues (bloat, contradictions, stale info), and refactoring bloated files.
---

This skill provides expert guidance for creating, verifying, and improving AGENTS.md files - the open standard format for guiding AI coding agents.

## What is AGENTS.md?

AGENTS.md is a simple, open format for guiding coding agents, used by over 60k open-source projects. Think of it as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project.

**Key principle:** Unlike README.md (which is for humans), AGENTS.md contains the extra, detailed context coding agents need: build steps, tests, conventions, and instructions that might clutter a README.

**Learn more:** https://agents.md/ | https://www.aihero.dev/a-complete-guide-to-agents-md

## Quick Start

### When users want to create an AGENTS.md file

Start by asking these clarifying questions:

1. **Project type:** Monorepo or single package?
2. **Tech stack:** What languages/frameworks?
3. **Package manager:** npm, pnpm, yarn, bun, or something else?
4. **Build/test commands:** Any non-standard commands?
5. **Specific concerns:** Any patterns you want to encourage or avoid?

Then create a minimal AGENTS.md following the template below.

### When users want to verify an existing AGENTS.md

Run through the verification checklist (see [Verification](#verification) below).

### When users want to improve an existing AGENTS.md

Assess the file and suggest progressive disclosure refactoring (see [Improvement](#improvement) below).

## Core Principles

### 1. Minimal Root AGENTS.md

The root AGENTS.md should be as small as possible. Every token gets loaded on every request, so keep only what's relevant to **every single task**.

**Essential elements only:**
- One-sentence project description (acts as a role-based prompt)
- Package manager (if not npm; or use corepack for warnings)
- Non-standard build/typecheck commands
- Links to progressive disclosure files

### 2. Progressive Disclosure

Instead of cramming everything into AGENTS.md, give the agent only what it needs right now, and point to other resources when needed.

**Example - Don't do this:**
```markdown
## Code style

- Always use const instead of let
- Use interface instead of type when possible
- Prefer functional patterns
- No semicolons
- Single quotes only
- ... (50 more lines)
```

**Do this instead:**
```markdown
For TypeScript conventions, see docs/TYPESCRIPT.md
```

**Benefits:**
- TypeScript rules only load when the agent writes TypeScript
- Other tasks don't waste tokens
- File stays focused and portable across model changes

### 3. Describe Capabilities, Not File Structure

File paths change constantly. Documenting structure leads to stale information that actively poisons context.

**Don't:**
```markdown
Authentication logic lives in src/auth/handlers.ts
```

**Do:**
```markdown
Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.
```

### 4. Nested AGENTS.md for Monorepos

Place AGENTS.md files in subdirectories - they merge with the root level.

| Level | Content |
|-------|---------|
| **Root** | Monorepo purpose, navigation, shared tools |
| **Package** | Package purpose, tech stack, specific conventions |

**Root AGENTS.md:**
```markdown
This is a monorepo containing web services and CLI tools.

Use pnpm workspaces to manage dependencies.

See each package's AGENTS.md for specific guidelines.
```

**Package AGENTS.md (packages/api/AGENTS.md):**
```markdown
This package is a Node.js GraphQL API using Prisma.

Follow docs/API_CONVENTIONS.md for API design patterns.
```

## Templates

### Minimal Single-Package AGENTS.md

```markdown
# AGENTS.md

[One-sentence description of what this project is]

## Package Manager

This project uses [pnpm/yarn/bun]. [Optional: brief note if workspaces/monorepo]

## Build & Test

- Build: `command here`
- Test: `command here`
- Typecheck: `command here` (if non-standard)

## Progressive Disclosure

- [Domain-specific]: [path/to/file.md]
```

### Minimal Monorepo Root AGENTS.md

```markdown
# AGENTS.md

This is a monorepo containing [brief description of packages].

## Package Manager

Use [pnpm workspaces/yarn workspaces] to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines

## Packages

- [`package-name`](packages/package-name): [brief purpose]
- [`package-name`](packages/package-name): [brief purpose]
```

### Package-Level AGENTS.md (Monorepo)

```markdown
# AGENTS.md

[One-sentence description of this package]

## Tech Stack

- [Framework]
- [Language]
- [Key libraries]

## Commands

- Build: `command here`
- Test: `command here`
- Dev: `command here`

## Progressive Disclosure

- [Domain]: [path/to/file.md]
```

## Verification

When verifying an existing AGENTS.md, check for these issues:

### Bloat Indicators

- [ ] File is longer than 50-75 lines
- [ ] Contains detailed coding style rules that belong in separate files
- [ ] Documents file paths extensively
- [ ] Has extensive examples that should be in documentation
- [ ] Contains git workflow instructions that belong in CONTRIBUTING.md

### Contradiction Detection

Look for conflicting instructions:
- [ ] "Use functional patterns" vs "Use classes for X"
- [ ] "Prefer composition" vs "Use inheritance for Y"
- [ ] "Always use X" vs "In cases of Y, use Z"

### Stale Information Risks

- [ ] Specific file paths (especially src/ directories)
- [ ] Lists of files or modules
- [ ] Version-specific toolchain commands
- [ ] Outdated architecture descriptions

### Best Practices Compliance

- [ ] Has one-sentence project description
- [ ] Specifies package manager (if not npm)
- [ ] Links to progressive disclosure files
- [ ] Uses conversational tone (not "ALWAYS", "MUST", "NEVER")
- [ ] Describes capabilities, not structure

## Improvement

### Refactoring Bloated AGENTS.md

Use this process to refactor a bloated AGENTS.md:

1. **Find contradictions**: Identify conflicting instructions and ask which to keep
2. **Extract essentials**: Keep only what belongs in root AGENTS.md
3. **Group the rest**: Organize remaining instructions into logical categories
4. **Create file structure**: Set up progressive disclosure hierarchy
5. **Flag for deletion**: Remove redundant, vague, or obvious instructions

**Prompt template to use:**
```text
I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")
```

### Creating Progressive Disclosure Files

**Suggested structure:**
```
docs/
├── TYPESCRIPT.md       # TypeScript patterns and conventions
├── TESTING.md          # Testing strategies and frameworks
├── API_CONVENTIONS.md  # API design patterns (if applicable)
├── ARCHITECTURE.md     # High-level architecture (capabilities, not file paths)
└── Git worklow items → CONTRIBUTING.md
```

**Each file should:**
- Be focused on one domain
- Link to related files for navigation
- Describe principles, not prescriptions
- Include examples where helpful

## Common Issues & Solutions

| Issue | Solution |
|-------|----------|
| Agent uses wrong package manager | Explicitly specify: "This project uses pnpm" |
| Agent generates wrong commands | List non-standard build/test commands |
| File gets too large | Apply progressive disclosure - move domain rules to separate files |
| Instructions conflict | Review for contradictions and resolve |
| Agent looks in wrong places | Describe capabilities, not file paths |
| Mixed conventions over time | Treat AGENTS.md as living documentation, review periodically |

## AGENTS.md vs CLAUDE.md

**Claude Code** uses `CLAUDE.md` instead of `AGENTS.md`. To maintain compatibility:

```bash
# Create a symlink from AGENTS.md to CLAUDE.md
ln -s AGENTS.md CLAUDE.md
```

Both files serve the same purpose - customize how AI coding agents behave in your repository.

## Tools Supporting AGENTS.md

AGENTS.md is an open standard supported by many tools:
- OpenAI Codex, Jules (Google), Factory, Aider, goose, opencode
- VS Code, Devin (Cognition), Cursor, RooCode, Gemini CLI
- GitHub Copilot coding agent, Windsurf (Cognition), and more

See https://agents.md/ for the full list.

## Your Approach

1. **Start minimal**: Begin with essential information only
2. **Apply progressive disclosure**: Move domain-specific rules to separate files
3. **Avoid file paths**: Describe capabilities, not structure
4. **Keep it conversational**: Use natural language, not rigid commands
5. **Review periodically**: Treat as living documentation
6. **Use nested files**: For monorepos, place AGENTS.md in subdirectories
7. **Link, don't duplicate**: Point to other resources instead of repeating

## Progressive Disclosure

**Deep dive on specific topics:**
- **Verification checklist**: [VERIFICATION.md](references/VERIFICATION.md)
- **Refactoring guide**: [REFACTORING.md](references/REFACTORING.md)
- **Template gallery**: [TEMPLATES.md](references/TEMPLATES.md)
- **Monorepo patterns**: [MONOREPO.md](references/MONOREPO.md)
- **Common anti-patterns**: [ANTI_PATTERNS.md](references/ANTI_PATTERNS.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/VERIFICATION.md

```markdown
# AGENTS.md Verification Guide

This guide helps you systematically verify an existing AGENTS.md file for common issues.

## Verification Checklist

Use this checklist to audit an AGENTS.md file:

### Size & Scope

- [ ] **File length**: Is the file under 75 lines? (Longer files indicate potential bloat)
- [ ] **Token efficiency**: Does every line add value to every single task?
- [ ] **Root-level appropriateness**: Would each instruction be relevant to ANY task in this repo?

### Essential Elements

- [ ] **Project description**: Is there a clear one-sentence description of what the project is?
- [ ] **Package manager**: Is the package manager explicitly specified (if not npm)?
- [ ] **Build commands**: Are non-standard build/test/typecheck commands documented?
- [ ] **Progressive disclosure links**: Does the file point to other resources for domain-specific info?

### Anti-Patterns

- [ ] **File path documentation**: Are specific file paths documented (e.g., "auth is in src/auth/handlers.ts")?
- [ ] **Extensive style rules**: Are detailed coding style rules in the root instead of separate files?
- [ ] **Rigid language**: Does it use words like "ALWAYS", "MUST", "NEVER" instead of conversational tone?
- [ ] **Obvious advice**: Does it state things the agent already knows (e.g., "write clean code")?

### Contradictions

Look for conflicting instructions in these areas:

- [ ] **Code style**: "Use functional patterns" vs "Use classes for X"
- [ ] **Error handling**: "Always throw errors" vs "Return null for not found"
- [ ] **Testing**: "Test everything" vs "Don't test trivial getters"
- [ ] **Naming**: "Use descriptive names" vs "Short names for locals"
- [ ] **Comments**: "Comment everything" vs "Code should be self-documenting"

### Stale Information Risks

- [ ] **File structure**: Does it document specific files or directories that may be renamed?
- [ ] **Module lists**: Does it list specific modules or components?
- [ ] **Version-specific commands**: Are there version-pinned commands that may go stale?
- [ ] **Architecture details**: Does it describe implementation details rather than capabilities?

### Progressive Disclosures

- [ ] **Domain separation**: Are domain-specific rules in separate files?
- [ ] **Link quality**: Do links point to existing, relevant files?
- [ ] **Hierarchy**: Is there a logical organization to referenced files?
- [ ] **Navigation**: Can agents easily discover related information?

### Monorepo Considerations (if applicable)

- [ ] **Root focus**: Is root AGENTS.md focused on monorepo-level concerns only?
- [ ] **Package files**: Do packages have their own AGENTS.md files?
- [ ] **Scope separation**: Is each level appropriately scoped?

## Scoring Guide

**Score your AGENTS.md:**

| Category | Excellent | Good | Needs Improvement |
|----------|-----------|------|-------------------|
| **Size** | < 50 lines | 50-75 lines | > 75 lines |
| **Essentials** | All 4 present | 3 present | < 3 present |
| **Anti-patterns** | None found | 1-2 found | 3+ found |
| **Contradictions** | None | 1 minor | Multiple or major |
| **Stale risks** | None | 1-2 minor | 3+ or major |
| **Progressive** | Well-structured | Some structure | No structure |

**Overall assessment:**
- **Excellent**: Ready to use
- **Good**: Consider minor improvements
- **Needs Improvement**: Refactor using [REFACTORING.md](REFACTORING.md)

## Common Issues Found

### Issue: "Kitchen Sink" AGENTS.md

**Symptom:** File contains everything from git workflow to TypeScript style to deployment instructions.

**Solution:** Apply progressive disclosure. Create separate files for each domain.

### Issue: "Tour Guide" AGENTS.md

**Symptom:** File extensively documents file structure: "src/components/ contains React components, src/utils/ contains utilities..."

**Solution:** Remove file paths. Describe capabilities and let the agent explore.

### Issue: "Rule Book" AGENTS.md

**Symptom:** File uses rigid language: "ALWAYS use const", "NEVER use any", "MUST include tests..."

**Solution:** Use conversational tone. "Prefer const over let", "Avoid any when possible", "Write tests for non-trivial code."

### Issue: "Time Capsule" AGENTS.md

**Symptom:** File documents outdated architecture or renamed files.

**Solution:** Remove specific implementation details. Focus on stable concepts and capabilities.

## Verification Process

1. **Read through**: Read the entire AGENTS.md file
2. **Check against list**: Go through the checklist above
3. **Note issues**: Document each issue found
4. **Score**: Use the scoring guide to assess overall quality
5. **Recommend**: Suggest improvements or refactoring if needed
6. **Report**: Provide clear feedback to the user

## Example Verification Report

```markdown
# AGENTS.md Verification Report

## Summary
- File length: 87 lines (❌ exceeds recommended 75)
- Essentials: 3/4 present (⚠️ missing project description)
- Anti-patterns: 3 found (⚠️ file paths, rigid language, obvious advice)
- Contradictions: 1 found (⚠️ error handling approaches conflict)
- Stale risks: 2 found (⚠️ file structure, module lists)
- Progressive: Minimal structure (⚠️ no domain separation)

## Issues Found

### High Priority
1. **File is too long** (87 lines vs recommended 75)
   - Recommendation: Apply progressive disclosure

2. **Missing project description**
   - Impact: Agent lacks context about project purpose
   - Recommendation: Add one-sentence description at top

3. **Documents file structure extensively**
   - Example: "Authentication in src/auth/handlers.ts"
   - Risk: File paths go stale
   - Recommendation: Remove specific paths, describe capabilities

### Medium Priority
1. **Rigid language throughout**
   - Examples: "ALWAYS use const", "NEVER use any"
   - Recommendation: Use conversational tone

2. **Contradiction in error handling**
   - Line 15: "Always throw errors"
   - Line 45: "Return null for not found cases"
   - Recommendation: Clarify which approach to use

3. **Lists specific modules**
   - Example: Lists 12 specific components in docs/
   - Risk: List will go stale
   - Recommendation: Remove or describe capabilities

### Low Priority
1. **Obvious advice**
   - Example: "Write clean, readable code"
   - Recommendation: Remove (agent already knows this)

## Recommendations

1. Add one-sentence project description
2. Refactor using progressive disclosure (see REFACTORING.md)
3. Remove all file path documentation
4. Replace rigid language with conversational tone
5. Resolve error handling contradiction
6. Remove module lists and obvious advice

Estimated effort: 30-60 minutes
```

## Next Steps

After verification:

1. **If file is excellent**: No action needed
2. **If file has minor issues**: Make targeted improvements
3. **If file needs major work**: Follow the refactoring guide in [REFACTORING.md](REFACTORING.md)

```

### references/REFACTORING.md

```markdown
# AGENTS.md Refactoring Guide

This guide helps you refactor bloated or problematic AGENTS.md files using progressive disclosure principles.

## When to Refactor

Refactor your AGENTS.md if you:
- File is longer than 75 lines
- Added rules reactively over time (the "ball of mud" problem)
- Have conflicting instructions from different developers
- Auto-generated the file (never do this!)
- File has stale file paths or structure documentation
- Agent seems confused or ignores instructions

## Refactoring Process

### Step 1: Find Contradictions

Identify conflicting instructions. For each contradiction, ask the user which version to keep.

**Common contradiction areas:**
- Code style: functional vs class-based
- Error handling: throw vs return null
- Testing: test everything vs test non-trivial
- Comments: comment everything vs self-documenting code
- Naming: descriptive vs concise

**Example:**
```markdown
❌ Line 15: "Always use functional patterns"
❌ Line 42: "Use classes for React components"
→ Ask user: Which approach do you prefer?
```

### Step 2: Identify the Essentials

Extract only what belongs in the root AGENTS.md:

**Keep in root:**
- ✅ One-sentence project description
- ✅ Package manager (if not npm)
- ✅ Non-standard build/typecheck commands
- ✅ Links to progressive disclosure files
- ✅ Anything relevant to EVERY single task

**Move to separate files:**
- ❌ Language-specific style rules
- ❌ Framework-specific patterns
- ❌ Testing conventions
- ❌ API design guidelines
- ❌ Git workflow instructions

**Delete entirely:**
- ❌ Specific file paths
- ❌ Lists of files or modules
- ❌ Obvious advice ("write clean code")
- ❌ Redundant instructions (agent already knows)
- ❌ Vague platitudes ("be professional")

### Step 3: Group the Rest

Organize remaining instructions into logical categories:

**Common categories:**
- TypeScript conventions
- Testing patterns
- API design / Backend patterns
- Frontend / UI patterns
- Git workflow
- Deployment / Release process
- Security considerations

### Step 4: Create the File Structure

Design a progressive disclosure hierarchy:

**Example structure:**
```
docs/
├── TYPESCRIPT.md       # TypeScript patterns
├── TESTING.md          # Testing conventions
├── API.md              # API design patterns
├── FRONTEND.md         # React/Next.js patterns
└── SECURITY.md         # Security guidelines
```

**Or monorepo structure:**
```
/AGENTS.md                          # Monorepo-level
packages/api/AGENTS.md              # API-specific
packages/web/AGENTS.md              # Web-specific
docs/
├── MONOREPO.md                     # Monorepo patterns
├── SHARED_TYPESCRIPT.md            # Shared TS conventions
└── DEPLOYMENT.md                   # Deployment patterns
```

### Step 5: Create Progressive Disclosure Files

Each file should:
- Focus on one domain
- Use conversational tone
- Include examples where helpful
- Link to related files
- Describe principles, not prescriptions

**Example TYPESCRIPT.md:**
```markdown
# TypeScript Conventions

## Type Definitions

Prefer `interface` for object shapes that might be extended:
```typescript
interface User {
  id: string;
  name: string;
}
```

Use `type` for unions, intersections, and utility types:
```typescript
type Status = 'pending' | 'approved' | 'rejected';
type UserWithStatus = User & { status: Status };
```

## Generics

Name generic parameters descriptively:
```typescript
// Good
function getById<T extends { id: string }>(items: T[], id: string): T | undefined

// Avoid
function getById<T>(items: T[], id: string): T | undefined
```

## Related

- For testing patterns, see [TESTING.md](TESTING.md)
- For API conventions, see [API.md](API.md)
```

### Step 6: Update Root AGENTS.md

Create a minimal root AGENTS.md that points to the progressive disclosure files:

```markdown
# AGENTS.md

This is a React component library for accessible data visualization.

## Package Manager

This project uses pnpm.

## Build & Test

- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`

## Conventions

- For TypeScript patterns, see [docs/TYPESCRIPT.md](docs/TYPESCRIPT.md)
- For testing conventions, see [docs/TESTING.md](docs/TESTING.md)
- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
```

## Refactoring Prompt

Use this prompt to refactor a bloated AGENTS.md:

```
I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

1. **Find contradictions**: Identify any instructions that conflict with each other.
   For each contradiction, ask me which version I want to keep.

2. **Identify the essentials**: Extract only what belongs in the root AGENTS.md:
   - One-sentence project description
   - Package manager (if not npm)
   - Non-standard build/typecheck commands
   - Anything truly relevant to every single task

3. **Group the rest**: Organize remaining instructions into logical categories
   (e.g., TypeScript conventions, testing patterns, API design, Git workflow).

4. **Create the file structure**: Output:
   - A minimal root AGENTS.md with markdown links to the separate files
   - Each separate file with its relevant instructions
   - A suggested docs/ folder structure

5. **Flag for deletion**: Identify any instructions that are:
   - Redundant (the agent already knows this)
   - Too vague to be actionable
   - Overly obvious (like "write clean code")
```

## Before & After Examples

### Before: Bloated AGENTS.md (87 lines)

```markdown
# AGENTS.md

## Project

This is a React component library...

## Code Style

- Always use const instead of let
- Always use interface instead of type
- No semicolons
- Single quotes only
- Use functional patterns
- Avoid classes unless necessary
- Prefer composition over inheritance
- Use arrow functions for callbacks
- [20 more lines of style rules]

## File Structure

- src/components/ - React components
- src/utils/ - Utility functions
- src/hooks/ - Custom hooks
- src/types/ - TypeScript types
- src/tests/ - Test files

## Testing

- Always write tests for new code
- Use Vitest for unit tests
- Use Testing Library for components
- Mock external dependencies
- Test user behavior, not implementation
- [15 more lines of testing guidelines]

## Git Workflow

- Commit messages should be descriptive
- Use conventional commits
- Never commit directly to main
- [10 more lines]

[... 30 more lines]
```

### After: Minimal AGENTS.md (18 lines)

```markdown
# AGENTS.md

This is a React component library for accessible data visualization.

## Package Manager

This project uses pnpm.

## Build & Test

- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`

## Conventions

- For TypeScript patterns, see [docs/TYPESCRIPT.md](docs/TYPESCRIPT.md)
- For testing conventions, see [docs/TESTING.md](docs/TESTING.md)
- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
- For Git workflow, see [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)
```

**Benefits:**
- ✅ 80% reduction in lines (87 → 18)
- ✅ Root file only loads essential info
- ✅ Domain-specific rules load only when needed
- ✅ File paths removed (no stale info risk)
- ✅ Conversational tone throughout

## Common Refactoring Patterns

### Pattern 1: Extract Language Rules

**Before:**
```markdown
## Code Style

- Use const instead of let
- Use interface over type
- [15 more TypeScript rules]
```

**After:**
```markdown
## Conventions

- For TypeScript patterns, see [docs/TYPESCRIPT.md](docs/TYPESCRIPT.md)
```

### Pattern 2: Remove File Paths

**Before:**
```markdown
## File Structure

- src/auth/handlers.ts - Authentication handlers
- src/auth/middleware.ts - Auth middleware
- src/auth/routes.ts - Auth routes
```

**After:**
```markdown
## Architecture

Authentication uses JWT tokens with refresh token rotation.
Look for modules matching **/auth/**/*.ts for implementation.
```

### Pattern 3: Soften Rigid Language

**Before:**
```markdown
- ALWAYS use const
- NEVER use any
- MUST write tests
```

**After:**
```markdown
- Prefer const over let
- Avoid any when possible
- Write tests for non-trivial code
```

### Pattern 4: Delete Obvious Advice

**Before:**
```markdown
- Write clean, readable code
- Follow best practices
- Be professional in comments
- Use meaningful names
```

**After:**
```markdown
(Deleted - agent already knows this)
```

## Verification After Refactoring

After refactoring, verify the new AGENTS.md using [VERIFICATION.md](VERIFICATION.md).

## Tips for Success

1. **Start small**: It's better to under-extract than over-extract
2. **Iterate**: Refactor in stages if the file is very large
3. **Get feedback**: Test with actual tasks to see if agent behavior improves
4. **Document decisions**: Add comments in separate files explaining why certain patterns are used
5. **Review periodically**: AGENTS.md should evolve with the project

## Time Estimates

| File Size | Refactoring Time |
|-----------|------------------|
| < 50 lines | 15-30 minutes |
| 50-100 lines | 30-60 minutes |
| 100-200 lines | 1-2 hours |
| 200+ lines | 2+ hours (consider iterative approach) |

```

### references/TEMPLATES.md

```markdown
# AGENTS.md Template Gallery

This gallery provides ready-to-use templates for common project types.

## Single-Package Templates

### Minimal TypeScript Project

```markdown
# AGENTS.md

This is a [brief description of project purpose].

## Package Manager

This project uses pnpm.

## Build & Test

- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
```

### React Component Library

```markdown
# AGENTS.md

This is a React component library for [specific use case].

## Package Manager

This project uses pnpm.

## Build & Test

- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Storybook: `pnpm storybook`

## Conventions

- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
- For TypeScript conventions, see [docs/TYPESCRIPT.md](docs/TYPESCRIPT.md)
```

### Next.js Web Application

```markdown
# AGENTS.md

This is a Next.js application for [brief purpose].

## Package Manager

This project uses pnpm with workspaces.

## Build & Test

- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint`

## Architecture

- App Router (app/ directory)
- Server Components by default
- API routes in app/api/

## Conventions

- For routing patterns, see [docs/ROUTING.md](docs/ROUTING.md)
- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
```

### Node.js API Service

```markdown
# AGENTS.md

This is a Node.js REST API using [Express/Fastify] and [Prisma/TypeORM].

## Package Manager

This project uses npm.

## Build & Test

- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Migrate: `npm run migrate`
- Seed: `npm run seed`

## Database

- Uses Prisma ORM
- Schema in prisma/schema.prisma
- Migrations in prisma/migrations/

## Conventions

- For API design patterns, see [docs/API.md](docs/API.md)
- For database patterns, see [docs/DATABASE.md](docs/DATABASE.md)
```

### Python Project

```markdown
# AGENTS.md

This is a Python project for [brief purpose].

## Package Manager

This project uses Poetry.

## Commands

- Install: `poetry install`
- Dev: `poetry run poe dev`
- Test: `poetry run pytest`
- Format: `poetry run ruff format`
- Lint: `poetry run ruff check`
- Typecheck: `poetry run mypy`

## Conventions

- Use Ruff for formatting and linting
- Use pytest for testing
- For type hints, see [docs/TYPING.md](docs/TYPING.md)
```

### Rust Project

```markdown
# AGENTS.md

This is a Rust CLI tool for [brief purpose].

## Build & Test

- Build: `cargo build --release`
- Dev: `cargo run`
- Test: `cargo test`
- Check: `cargo check`
- Format: `cargo fmt`
- Lint: `cargo clippy`

## Conventions

- Use `cargo clippy` for lints
- Prefer `Result<T, E>` over panic/unwrap
- For error handling patterns, see [docs/ERRORS.md](docs/ERRORS.md)
```

### Go Project

```markdown
# AGENTS.md

This is a Go service for [brief purpose].

## Build & Test

- Build: `go build ./cmd/service`
- Test: `go test ./...`
- Run: `go run ./cmd/service`
- Format: `go fmt ./...`
- Lint: `golangci-lint run`

## Conventions

- Standard Go project layout
- For error handling, see [docs/ERRORS.md](docs/ERRORS.md)
- For API patterns, see [docs/API.md](docs/API.md)
```

## Monorepo Templates

### Simple Monorepo (pnpm)

```markdown
# AGENTS.md

This is a monorepo containing [brief description of packages].

## Package Manager

Use pnpm workspaces to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines

## Packages

- [`web`](packages/web): Next.js frontend application
- [`api`](packages/api): Node.js GraphQL API
- [`shared`](packages/shared): Shared TypeScript types and utilities
```

### Turborepo Monorepo

```markdown
# AGENTS.md

This is a Turborepo monorepo with [description of apps and packages].

## Package Manager

Use pnpm with Turborepo for task orchestration.

## Commands

- Dev: `pnpm dev` (runs all apps and packages in dev mode)
- Build: `pnpm build` (builds all apps and packages)
- Test: `pnpm test` (tests all packages)
- Task: `turbo run <task> --filter=<package>`

## Navigation

- Each app and package has its own AGENTS.md
- Use `turbo run` to run tasks in specific packages

## Apps

- [`web`](apps/web): Next.js application
- [`admin`](apps/admin): Admin dashboard

## Packages

- [`ui`](packages/ui): Component library
- [`api`](packages/api): API client
- [`config`](packages/config): Shared ESLint, TypeScript configs
```

### Nx Monorepo

```markdown
# AGENTS.md

This is an Nx monorepo containing [description].

## Package Manager

Use npm with Nx for task orchestration.

## Commands

- [Affected]: `npx nx affected -t build test`
- [Specific]: `npx nx run <project>:<task>`
- [Graph]: `npx nx graph`

## Navigation

- Use `npx nx affected` to work with changed projects
- Each project has its own AGENTS.md

## Projects

- [`app`](apps/app): Next.js application
- [`api`](apps/api): NestJS API
- [`shared`](libs/shared): Shared utilities
```

## Framework-Specific Templates

### Vue + Nuxt

```markdown
# AGENTS.md

This is a Nuxt 3 application for [brief purpose].

## Package Manager

This project uses pnpm.

## Commands

- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Typecheck: `pnpm nuxi typecheck`

## Conventions

- Composition API with `<script setup>`
- Auto-imports for components and composables
- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
```

### SvelteKit

```markdown
# AGENTS.md

This is a SvelteKit application for [brief purpose].

## Package Manager

This project uses pnpm.

## Commands

- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Check: `pnpm check` (runs svelte-check)

## Conventions

- Use `<script lang="ts">` for TypeScript
- For routing patterns, see [docs/ROUTING.md](docs/ROUTING.md)
```

### Astro

```markdown
# AGENTS.md

This is an Astro site for [brief purpose].

## Package Manager

This project uses pnpm.

## Commands

- Dev: `pnpm dev`
- Build: `pnpm build`
- Preview: `pnpm preview`

## Architecture

- Content collections in src/content/config.ts
- Pages in src/pages/
- Layouts in src/layouts/

## Conventions

- Use .astro files for page components
- For component patterns, see [docs/COMPONENTS.md](docs/COMPONENTS.md)
```

### Django Project

```markdown
# AGENTS.md

This is a Django project for [brief purpose].

## Commands

- Dev: `python manage.py runserver`
- Migrate: `python manage.py migrate`
- Makemigrations: `python manage.py makemigrations`
- Test: `python manage.py test`
- Shell: `python manage.py shell`

## Architecture

- Apps in [apps/](apps/)
- Settings in [config/settings/](config/settings/)
- URLs in [config/urls/](config/urls/)

## Conventions

- Class-based views for complex logic, function-based for simple
- For API patterns, see [docs/API.md](docs/API.md)
```

### Rails Application

```markdown
# AGENTS.md

This is a Rails application for [brief purpose].

## Commands

- Server: `rails server`
- Console: `rails console`
- Test: `rails test`
- Migrate: `rails db:migrate`
- Routes: `rails routes`

## Architecture

- Models in app/models/
- Controllers in app/controllers/
- Views in app/views/
- Jobs in app/jobs/

## Conventions

- Follow Rails conventions
- Use service objects for complex business logic
- For testing patterns, see [docs/TESTING.md](docs/TESTING.md)
```

## Progressive Disclosure File Templates

### TYPESCRIPT.md

```markdown
# TypeScript Conventions

## Type Definitions

Prefer `interface` for object shapes that might be extended.
Use `type` for unions, intersections, and utility types.

## Type Safety

Avoid `any`. Use `unknown` when type is truly unknown.
Use strict mode settings in tsconfig.json.

## Related

- For testing patterns, see [TESTING.md](TESTING.md)
```

### TESTING.md

```markdown
# Testing Conventions

## Framework

We use [Vitest/Jest/pytest] for testing.

## Principles

- Test user behavior, not implementation details
- Mock external dependencies
- Keep tests focused and readable

## Related

- For TypeScript test patterns, see [TYPESCRIPT.md](TYPESCRIPT.md)
```

### COMPONENTS.md

```markdown
# Component Conventions

## Structure

- Co-locate related components
- Use composition over complex prop drilling
- Prefer compound components for related UI

## Naming

- Use descriptive, domain-specific names
- Prefix HOCs and hooks appropriately

## Related

- For TypeScript patterns, see [TYPESCRIPT.md](TYPESCRIPT.md)
```

## Tips for Customizing Templates

1. **Start minimal**: Use the minimal template and add only what's essential
2. **Remove unused sections**: If a section doesn't apply, delete it
3. **Customize commands**: Replace placeholder commands with actual ones
4. **Add progressive disclosure**: Link out to separate files for domain-specific info
5. **Keep it conversational**: Use natural language, not rigid commands

## Template Selection Guide

| Project Type | Use Template |
|--------------|--------------|
| Simple library/app | Minimal TypeScript Project |
| React components | React Component Library |
| Full-stack web | Next.js Web Application |
| Backend API | Node.js API Service |
| Multiple related projects | Simple/Turborepo/Nx Monorepo |
| Data science/ML | Python Project |
| Systems/CLI | Rust Project |
| Microservices | Go Project |

```

### references/MONOREPO.md

```markdown
# AGENTS.md for Monorepos

This guide covers best practices for using AGENTS.md files in monorepo configurations.

## Why Nested AGENTS.md?

In a monorepo, different packages often have:
- Different tech stacks (frontend vs backend)
- Different build processes
- Different conventions and patterns
- Different testing frameworks

Nested AGENTS.md files allow each package to provide specific guidance while maintaining a minimal root configuration.

## How Nested AGENTS.md Works

When an agent works on a file:
1. It reads the root AGENTS.md
2. It reads the nearest AGENTS.md in the directory tree
3. It merges both files
4. The closest AGENTS.md takes precedence for conflicting instructions

**Example structure:**
```
/AGENTS.md                    # Monorepo-level
packages/api/AGENTS.md        # API-specific
packages/web/AGENTS.md        # Web-specific
```

When editing `packages/api/src/users.ts`:
- Agent sees root AGENTS.md + packages/api/AGENTS.md
- Agent does NOT see packages/web/AGENTS.md

## Scope Guidelines

### Root AGENTS.md

**Focus on monorepo-level concerns:**

```markdown
# AGENTS.md

This is a monorepo containing web services and CLI tools.

## Package Manager

Use pnpm workspaces to manage dependencies.

## Navigation

- Use `pnpm --filter <package_name>` to run commands in specific packages
- Each package has its own AGENTS.md with specific guidelines
- Run `pnpm -w` for root-level commands

## Root Commands

- Install all: `pnpm install`
- Build all: `pnpm build`
- Test all: `pnpm test`
- Typecheck all: `pnpm typecheck`

## Packages

- [`web`](packages/web): Next.js frontend application
- [`api`](packages/api): Node.js GraphQL API
- [`cli`](packages/cli): TypeScript CLI tool
- [`shared`](packages/shared): Shared utilities and types
```

### Package-Level AGENTS.md

**Focus on package-specific concerns:**

```markdown
# AGENTS.md

This package is a Node.js GraphQL API using Prisma and Apollo Server.

## Package Manager

This package uses pnpm (inherited from monorepo root).

## Commands

- Dev: `pnpm dev` (runs API with hot reload)
- Build: `pnpm build` (compiles TypeScript)
- Test: `pnpm test` (runs Vitest)
- Migrate: `pnpm migrate` (runs Prisma migrations)
- Generate: `pnpm prisma generate` (generates Prisma client)

## Database

- Uses Prisma ORM with PostgreSQL
- Schema location: prisma/schema.prisma
- Migrations in prisma/migrations/

## Conventions

- For API design patterns, see [docs/API.md](docs/API.md)
- For database patterns, see [docs/DATABASE.md](docs/DATABASE.md)
```

## Common Monorepo Patterns

### Pattern 1: Framework Monorepo

**Structure:** One frontend framework + shared packages

```
/AGENTS.md
apps/
  web/AGENTS.md
  admin/AGENTS.md
packages/
  ui/AGENTS.md
  config/
```

**Root AGENTS.md:**
```markdown
# AGENTS.md

This is a Next.js monorepo with multiple applications and shared UI packages.

## Package Manager

Use pnpm workspaces with Turborepo for task orchestration.

## Commands

- Dev: `pnpm dev` (runs all apps)
- Build: `pnpm build` (builds all apps)
- Test: `pnpm test` (tests all packages)

## Apps

- [`web`](apps/web): Main Next.js application
- [`admin`](apps/admin): Admin dashboard

## Packages

- [`ui`](packages/ui): Shared component library
- [`config`](packages/config): ESLint, TypeScript configs
```

### Pattern 2: Full-Stack Monorepo

**Structure:** Frontend + Backend + Shared types

```
/AGENTS.md
apps/
  web/AGENTS.md
services/
  api/AGENTS.md
packages/
  types/AGENTS.md
  api-client/AGENTS.md
```

**Root AGENTS.md:**
```markdown
# AGENTS.md

This is a full-stack monorepo with web frontend, API backend, and shared types.

## Package Manager

Use pnpm workspaces.

## Commands

- Dev: `pnpm dev` (runs web + api)
- Build: `pnpm build`
- Test: `pnpm test`

## Architecture

- Frontend: Next.js in apps/web
- Backend: NestJS in services/api
- Shared: TypeScript types in packages/types

## Navigation

- Use `pnpm --filter <package>` for package-specific commands
- See each package's AGENTS.md for specific guidelines
```

### Pattern 3: Multi-Language Monorepo

**Structure:** Different languages in different directories

```
/AGENTS.md
services/
  api-node/AGENTS.md       # Node.js
  worker-go/AGENTS.md      # Go
  script-python/AGENTS.md  # Python
```

**Root AGENTS.md:**
```markdown
# AGENTS.md

This is a polyglot monorepo with services in multiple languages.

## Package Manager

Root uses npm for tooling. Individual services use their native package managers.

## Commands

- Dev: `docker-compose up` (runs all services)
- Test: `./scripts/test-all.sh` (runs all tests)

## Services

- [`api-node`](services/api-node): Node.js/TypeScript API
- [`worker-go`](services/worker-go): Go background worker
- [`script-python`](services/script-python): Python data processing

## Navigation

- Each service has its own AGENTS.md with language-specific guidance
- Services communicate via gRPC/REST
```

## Monorepo-Specific Concerns

### Workspace Dependencies

**Problem:** Agent doesn't know how to add workspace dependencies

**Solution:** Document workspace-specific commands in package AGENTS.md:

```markdown
## Adding Dependencies

To add a workspace dependency:
- Internal: `pnpm --filter <package> add <workspace-package>`
- External: `pnpm --filter <package> add <external-package>`

Example:
```bash
pnpm --filter @monorepo/web add @monorepo/ui
```
```

### Shared Build Configuration

**Problem:** How to document shared tooling?

**Solution:** Reference shared packages from root AGENTS.md:

```markdown
## Tooling

- ESLint config: `@monorepo/config-eslint`
- TypeScript config: `@monorepo/config-typescript`
- Build tool: Turborepo

See individual package AGENTS.md for package-specific overrides.
```

### Inter-Package Communication

**Problem:** Agent needs to understand how packages interact

**Solution:** Document at root level, refer to package-specific docs:

```markdown
## Architecture

- **Web** calls **API** via generated client (packages/api-client)
- **API** publishes events to **Worker** via message queue
- **All packages** use shared types from packages/types

For details, see each package's AGENTS.md.
```

## Anti-Patterns to Avoid

### ❌ Don't Duplicate Commands

**Bad:**
```markdown
# Root AGENTS.md
- Build web: pnpm --filter web build
- Build api: pnpm --filter api build
- Build worker: pnpm --filter worker build
```

**Good:**
```markdown
# Root AGENTS.md
- Build all: `pnpm build`

# See each package's AGENTS.md for package-specific commands
```

### ❌ Don't Overload Root

**Bad:** Root AGENTS.md contains every package's conventions

**Good:** Root AGENTS.md focuses on monorepo-level concerns only

### ❌ Don't Mix Concerns

**Bad:** Package AGENTS.md contains monorepo navigation instructions

**Good:** Navigation stays at root level; packages focus on their own concerns

## Example: Complete Monorepo Setup

### Root AGENTS.md
```markdown
# AGENTS.md

This is a full-stack monorepo with Next.js frontend and Node.js API.

## Package Manager

Use pnpm workspaces with Turborepo.

## Commands

- Dev: `pnpm dev` (runs web + api)
- Build: `pnpm build`
- Test: `pnpm test`

## Architecture

- Frontend (apps/web) calls API via generated client
- Backend (apps/api) provides REST + GraphQL endpoints
- Shared types (packages/types) ensure contract safety
```

### apps/web/AGENTS.md
```markdown
# AGENTS.md

This is a Next.js application for the main web interface.

## Commands

- Dev: `pnpm dev` (runs on localhost:3000)
- Build: `pnpm build`
- Typecheck: `pnpm typecheck`

## API Integration

Use generated client from @monorepo/api-client:
```typescript
import { api } from '@monorepo/api-client';
const data = await api.users.list();
```

## Conventions

- For routing patterns, see docs/ROUTING.md
- For component patterns, see docs/COMPONENTS.md
```

### apps/api/AGENTS.md
```markdown
# AGENTS.md

This is a Node.js API using Express and Prisma.

## Commands

- Dev: `pnpm dev` (runs on localhost:4000)
- Build: `pnpm build`
- Test: `pnpm test`
- Migrate: `pnpm migrate`

## Database

Uses Prisma with PostgreSQL. Schema in prisma/schema.prisma.

## Conventions

- For API design, see docs/API.md
- For database patterns, see docs/DATABASE.md
```

## Testing Nested AGENTS.md

To verify your nested AGENTS.md setup:

1. **Check root**: Verify root AGENTS.md contains only monorepo-level concerns
2. **Check packages**: Verify each package AGENTS.md is focused on that package
3. **Check for duplication**: Remove any duplicated content
4. **Check links**: Verify progressive disclosure links work
5. **Test with tasks**: Run sample tasks to see if agent behavior improves

See [VERIFICATION.md](VERIFICATION.md) for general verification guidelines.

```

### references/ANTI_PATTERNS.md

```markdown
# AGENTS.md Anti-Patterns

This guide covers common anti-patterns to avoid when creating or maintaining AGENTS.md files.

## The "Kitchen Sink" Anti-Pattern

### Description
Putting everything in the root AGENTS.md file - git workflow, code style, testing conventions, deployment instructions, etc.

### Why It's Bad
- File becomes unmanageable (200+ lines)
- Agent gets confused by too much information
- Most instructions are irrelevant to any given task
- Token waste on every request

### Example
```markdown
❌ BAD: 150+ lines covering everything

# AGENTS.md

## Git Workflow (30 lines)
## Code Style (40 lines)
## Testing (30 lines)
## API Design (20 lines)
## Deployment (15 lines)
## Security (10 lines)
## ... and more
```

### Solution
Use progressive disclosure. Keep root minimal, move domain-specific rules to separate files.

```markdown
✅ GOOD: 15 lines, links to separate files

# AGENTS.md

This is a React component library for accessible data visualization.

## Package Manager

This project uses pnpm.

## Conventions

- For Git workflow, see [docs/GIT.md](docs/GIT.md)
- For code style, see [docs/STYLE.md](docs/STYLE.md)
- For testing, see [docs/TESTING.md](docs/TESTING.md)
```

## The "Tour Guide" Anti-Pattern

### Description
Extensively documenting file structure with specific paths.

### Why It's Bad
- File paths change constantly
- Documentation goes stale quickly
- Agent confidently looks in wrong places
- High maintenance burden

### Example
```markdown
❌ BAD

## File Structure

```
src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx        # Main component
│   │   ├── Button.test.tsx   # Tests
│   │   └── Button.styles.ts  # Styles
│   └── Input/
│       └── ...
├── hooks/
│   ├── useAuth.ts            # Auth hook
│   └── useData.ts            # Data fetching hook
└── utils/
    └── helpers.ts            # Utility functions
```
```

### Solution
Describe capabilities, not structure. Use patterns to help agent discover files.

```markdown
✅ GOOD

## Architecture

- Components are co-located with their tests and styles
- Look for custom hooks in **/hooks/**/*.ts
- Utility functions in **/utils/**/*.ts
- Use glob patterns when searching for implementations
```

## The "Rule Book" Anti-Pattern

### Description
Using rigid, authoritarian language ("ALWAYS", "MUST", "NEVER").

### Why It's Bad
- Creates confrontational tone
- Often has exceptions that aren't documented
- Agent may follow rules literally even when inappropriate
- Makes file feel oppressive to maintain

### Example
```markdown
❌ BAD

## Code Style

- ALWAYS use const instead of let
- NEVER use any type
- MUST write tests for everything
- ALWAYS use functional components
- NEVER use class components
```

### Solution
Use conversational, pragmatic tone. Acknowledge context matters.

```markdown
✅ GOOD

## Code Style

- Prefer const over let
- Avoid any when possible, use unknown instead
- Write tests for non-trivial code
- Default to functional components
- Use classes only when necessary (e.g., complex state machines)
```

## The "Time Capsule" Anti-Pattern

### Description
Documenting specific implementation details that will go stale.

### Why It's Bad
- Documentation rots quickly
- Agent acts on outdated information
- Hard to maintain when code changes
- Creates false confidence

### Example
```markdown
❌ BAD

## Authentication

Authentication is handled by the AuthService class in src/auth/AuthService.ts.
It uses JWT tokens stored in localStorage under the key 'auth_token'.
Tokens are refreshed every 5 minutes by the tokenRefreshInterval in src/utils/timers.ts.
```

### Solution
Describe stable concepts and patterns, not specific implementations.

```markdown
✅ GOOD

## Authentication

Authentication uses JWT tokens with refresh token rotation.
Look for auth-related modules in **/auth/**/*.ts.
Token management is handled automatically by the auth context.
```

## The "Auto-Generated" Anti-Pattern

### Description
Using initialization scripts to auto-generate AGENTS.md files.

### Why It's Bad
- Prioritizes comprehensiveness over restraint
- Adds "useful for most scenarios" content that isn't relevant
- Creates bloated files from day one
- Violates progressive disclosure principles

### Example
```markdown
❌ BAD: Generated by CLI tool

# AGENTS.md

## Project Overview
## Getting Started
## Available Scripts
## Technology Stack
## Folder Structure
## Coding Standards
## Testing Guidelines
## Git Workflow
## Deployment Process
## Troubleshooting
## Contributing
## License
## Contact
## FAQ
## ... (100+ lines)
```

### Solution
Start minimal. Add only what's essential. Let the file grow organically based on actual needs.

```markdown
✅ GOOD: Hand-crafted, minimal

# AGENTS.md

This is a [one-sentence description].

## Package Manager

This project uses pnpm.

## Commands

- Build: `pnpm build`
- Test: `pnpm test`
```

## The "Obvious Advice" Anti-Pattern

### Description
Including advice that's either obvious to developers or already known by AI agents.

### Why It's Bad
- Wastes tokens
- Clutters the file
- Reduces signal-to-noise ratio
- Makes file longer than necessary

### Examples
```markdown
❌ BAD: Obvious to humans

- Write clean, readable code
- Follow best practices
- Use meaningful variable names
- Don't repeat yourself (DRY)
- Keep functions small and focused
```

```markdown
❌ BAD: Already known by agents

- Use import to import modules
- Use export to export functions
- Use console.log for debugging
- Use async/await for promises
```

### Solution
Remove entirely. The agent already knows this, and human developers don't need it in AGENTS.md.

## The "Contradiction" Anti-Pattern

### Description
Having conflicting instructions, often from multiple contributors over time.

### Why It's Bad
- Agent doesn't know which rule to follow
- Creates unpredictable behavior
- Indicates lack of consensus
- Reduces trust in the file

### Example
```markdown
❌ BAD

Line 15: "Always use functional patterns"
Line 42: "Use classes for React components"

Line 20: "Throw errors for invalid input"
Line 55: "Return null for not-found cases"

Line 30: "Test everything"
Line 60: "Don't test trivial getters"
```

### Solution
Review for contradictions and resolve them. Ask stakeholders which approach to prefer.

```markdown
✅ GOOD: Consistent approach

"Prefer functional patterns in most cases. Use classes only for complex state management."

"Throw errors for invalid input. Return null only for expected not-found cases."

"Write tests for non-trivial code. Skip tests for simple getters/setters."
```

## The "Ball of Mud" Anti-Pattern

### Description
File that grew organically through reactive additions without organization.

### How It Happens
1. Agent does something you don't like
2. You add a rule to prevent it
3. Repeat hundreds of times over months
4. File becomes unmaintainable mess

### Why It's Bad
- No clear organization
- Impossible to find relevant instructions
- Full of edge cases and one-off rules
- Maintenance nightmare

### Solution
Refactor using the process in [REFACTORING.md](REFACTORING.md).

1. Find contradictions
2. Extract essentials
3. Group by domain
4. Create separate files
5. Keep root minimal

## The "Mixed Conventions" Anti-Pattern

### Description
File contains guidance that belongs in other documentation files.

### Why It's Bad
- Clutters AGENTS.md with irrelevant content
- Makes the file harder to use
- Duplicates information better suited elsewhere

### Examples
```markdown
❌ BAD: Git workflow in AGENTS.md

## Git Workflow

- Use conventional commits
- Never commit directly to main
- Write descriptive commit messages
- PR titles should follow format: [type] description
```

```markdown
❌ BAD: Security guidelines in AGENTS.md

## Security

- Never commit secrets
- Use environment variables for config
- Validate all user input
- Sanitize data before display
```

### Solution
Move to appropriate documentation files. AGENTS.md should link to them, not contain them.

```markdown
✅ GOOD: AGENTS.md links to separate files

## Conventions

- For Git workflow, see [CONTRIBUTING.md](CONTRIBUTING.md)
- For security guidelines, see [docs/SECURITY.md](docs/SECURITY.md)
- For code review criteria, see [docs/REVIEW.md](docs/REVIEW.md)
```

## The "Monorepo Overload" Anti-Pattern

### Description
In monorepos, putting everything in the root AGENTS.md.

### Why It's Bad
- Root file becomes massive
- Package-specific guidance gets lost
- Agent sees irrelevant instructions
- Violates scope boundaries

### Example
```markdown
❌ BAD: Root AGENTS.md with everything

# AGENTS.md

## Monorepo Overview
## Frontend Conventions (30 lines)
## Backend Conventions (30 lines)
## Shared Package Conventions (20 lines)
## API Design (20 lines)
## Component Patterns (20 lines)
## ... (150+ lines)
```

### Solution
Use nested AGENTS.md files. Keep root focused on monorepo-level concerns.

```markdown
✅ GOOD: Root is minimal, packages have their own

# Root AGENTS.md (15 lines)
This is a full-stack monorepo with Next.js frontend and Node.js API.

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`

See each package's AGENTS.md for specific guidelines.

# apps/web/AGENTS.md (20 lines)
Frontend-specific conventions...

# apps/api/AGENTS.md (20 lines)
Backend-specific conventions...
```

## Anti-Pattern Detection Checklist

Use this checklist to detect anti-patterns in your AGENTS.md:

- [ ] File is longer than 75 lines (kitchen sink?)
- [ ] Contains extensive file structure documentation (tour guide?)
- [ ] Uses "ALWAYS", "MUST", "NEVER" throughout (rule book?)
- [ ] Documents specific file paths or modules (time capsule?)
- [ ] Was auto-generated by initialization script (auto-generated?)
- [ ] Contains obvious advice like "write clean code" (obvious advice?)
- [ ] Has conflicting instructions (contradiction?)
- [ ] Grew organically without organization (ball of mud?)
- [ ] Contains Git workflow or security guidelines (mixed conventions?)
- [ ] In monorepo, root contains package-specific details (monorepo overload?)

If you checked any boxes, see the corresponding section above for solutions.

## Recovery Guide

If your AGENTS.md has fallen into anti-patterns:

1. **Assess severity**: How many anti-patterns? How bad?
2. **Prioritize**: Fix the most impactful first (usually kitchen sink or ball of mud)
3. **Use the refactoring guide**: Follow [REFACTORING.md](REFACTORING.md)
4. **Verify after changes**: Use [VERIFICATION.md](VERIFICATION.md) to check improvements
5. **Monitor**: Watch for old patterns creeping back in

Remember: AGENTS.md should be living documentation that evolves with your project. Regular reviews prevent anti-patterns from taking hold.

```