AGENTS.md / CLAUDE.md Creator

Create and maintain AI documentation files that help agents understand your project efficiently using progressive disclosure principles.

Core Philosophy: Iron Rule

Never use line count as a metric. Judge by single source of truth (no duplication), cognitive relevance (only task-relevant info), and maintainability (change once, not everywhere).

Quick Decision Trees

"I want to create AGENTS.md"

Create AGENTS.md?
├─ Detect project structure → references/project_detection.md
├─ Determine if monorepo → Check for apps/, packages/, workspace configs
├─ Extract essential info → README.md, package.json, folder layout
├─ Choose template → references/templates.md
└─ Apply progressive disclosure → references/progressive_disclosure.md

"My AGENTS.md is too bloated"

Optimize existing AGENTS.md?
├─ Back up file first → cp AGENTS.md AGENTS.md.bak.$(date)
├─ Classify each section → references/progressive_disclosure.md#content-classification
├─ Create Level 2 references → docs/references/ for detailed content
├─ Update Level 1 → Keep only high-frequency, critical info
└─ Verify completeness → Ensure no information is lost

"I don't know my project structure type"

Detect project structure?
├─ Check for apps/ or packages/ directories → Monorepo
├─ Check for workspace config (pnpm-workspace.yaml, etc.) → Monorepo
├─ Check for lerna.json, turbo.json, nx.json → Monorepo
├─ Single package.json at root → Polyrepo (likely)
└─ Show detection confidence and ask user to confirm

Project Structure Detection

Auto-Detection Indicators

Detection Confidence Levels

High confidence (≥3 indicators): Proceed without asking
Medium confidence (1-2 indicators): Show findings, ask user to confirm
No clear indicators: Ask user directly

Progressive Disclosure Architecture

Three-Level Loading System

Level 1 (AGENTS.md) - Always loaded
├── One-line project description
├── Essential commands (run, test, build)
├── Repository structure (top-level dirs only)
├── Reference index tables (multi-entry)
└── Key entry points

Level 2 (docs/references/) - On-demand
├── Detailed SOP flows
├── Edge case handling
├── Complete config examples
└── Historical decisions

Level 3 (Project files) - As needed
├── README.md
├── package.json files
└── Config files

Multi-Entry Principle

The same Level 2 resource can have multiple entry points for different discovery paths:

This is NOT duplication. It's like a book having a table of contents, an index, and quick reference cards.

AGENTS.md vs CLAUDE.md

File Relationship

AGENTS.md # Root context - always loaded by agents
CLAUDE.md # Required for Claude Code - loads AGENTS.md

CLAUDE.md Contents (Minimal Bridge)

Read [AGENTS.md](AGENTS.md) before starting any task.

CLAUDE.md exists only because Claude Code doesn't load AGENTS.md natively. Keep it minimal.

AGENTS.md Essential Structure

Required Sections (Level 1)

Never Include in AGENTS.md (Level 1)

Content Classification Decision Tree

For each section, ask:

Is this high-frequency use?
├─ Yes → Level 1 (AGENTS.md)
└─ No → ↓

Is the violation consequence severe?
├─ Yes → Level 1 (AGENTS.md)
└─ No → ↓

Is there a code pattern to copy directly?
├─ Yes → Level 1 keep the pattern
└─ No → ↓

Is there a clear trigger condition?
├─ Yes → Level 2 + trigger condition
└─ No → Consider deleting

Reference Index Format

At Start (Problem-Oriented)

## Reference Index (When you encounter problems)

| Trigger scenario | Document | Core content |
|------------------|----------|--------------|
| Build fails after dependency change | `docs/references/build-sop.md` | Dependency order, clean build |
| Test environment variables not loading | `docs/references/env-setup.md` | .env files, globalEnv config |
| Cache not invalidating | `docs/references/caching.md` | outputs, inputs, env keys |

At Middle (Task-Oriented)

## Before Modifying Code

| What you're changing | Read this first | Key gotchas |
|---------------------|-----------------|-------------|
| Build configuration | `docs/references/build-sop.md` | dependsOn order matters |
| Environment setup | `docs/references/env-setup.md` | globalEnv affects all tasks |
| Cache behavior | `docs/references/caching.md` | outputs required for file-producing tasks |

At End (Re-Orientation)

## Reference Trigger Index

| When to read | Document | What you'll find |
|--------------|----------|------------------|
| Build fails | `docs/references/build-sop.md` | Dependency troubleshooting |
| Env issues | `docs/references/env-setup.md` | .env and variable setup |
| Cache problems | `docs/references/caching.md` | Hash input debugging |

Anti-Patterns to Avoid

Monorepo-Specific Considerations

Additional Detection for Monorepos

When a monorepo is detected, also extract:

Package Name Detection

Package naming varies significantly across monorepos. Detect actual package names from:

1. Directory patterns:

   • apps/* → Application packages
   • packages/* → Library packages
   • services/* → Backend services

2. Package naming conventions:

   • Scoped: @repo/*, @company/*, @project/*
   • Unscoped: backend, frontend, api, web
   • Mixed: Both scoped and unscoped in same repo

3. Common backend package names:

   • @repo/api, @repo/backend, @repo/server
   • apps/api, apps/backend, apps/server
   • services/api, services/backend

4. Common frontend package names:

   • @repo/web, @repo/frontend, @repo/app
   • apps/web, apps/frontend, apps/app
   • apps/admin, apps/dashboard

Monorepo AGENTS.md Additions

Generate the package table dynamically based on actual project structure:

## Monorepo Structure

| Package | Location | Purpose | Key commands |
|---------|----------|---------|--------------|
| `backend` | apps/backend | REST API server | `turbo run dev --filter=backend` |
| `frontend` | apps/web | Next.js web app | `turbo run dev --filter=frontend` |
| `ui` | packages/ui | Shared React components | `turbo run build --filter=ui` |

## Working with Packages

- Run task in specific package: `turbo run <task> --filter=<package-name>`
- Run only changed packages: `turbo run <task> --affected`
- Include dependents: `turbo run <task> --filter=...<package-name>`
- Run by directory: `turbo run <task> --filter=./apps/*`

Key guidelines for package tables:

1. Use actual package names from package.json name field
2. Infer purpose from description field or directory name
3. Group by type (apps vs packages) if helpful
4. Keep it concise — focus on most commonly used packages
5. Reference detailed docs for complete package list

Verification Checklist

After creating or modifying AGENTS.md, verify:

Information Completeness (Most Important)

• Every section from original has a home (in Level 1, Level 2, or has canonical source)
• Level 2 files match original content exactly (no "simplification" during move)
• No content was silently deleted
• No line count statistics were mentioned

Structure Quality

• Reference index at document start
• Core commands table complete
• Iron rules/prohibitions with code examples
• Common error diagnostics (symptom → cause → fix)
• Code patterns directly copyable
• Directory mapping (function → file)
• "Before modifying code" table
• Reference trigger index at document end
• Every Level 2 reference has trigger conditions
• All referenced files exist

Information Recording Principles

Add this to AGENTS.md after project description to prevent future bloat:

## Information Recording Principles (Agents Must Read)

This document uses **progressive disclosure** to optimize agent effectiveness.

### Level 1 (This file) contains only

| Type | Example |
|------|---------|
| Core commands | `npm run dev`, `npm test` |
| Iron rules/prohibitions | Must use lazy loading |
| Common error diagnostics | Symptom → cause → fix (complete flow) |
| Code patterns | Directly copyable code blocks |
| Directory navigation | Function → file mapping |
| Trigger index tables | Pointers to Level 2 |

### Level 2 (docs/references/) contains

| Type | Example |
|------|---------|
| Detailed SOP flows | Complete 20-step guides |
| Edge case handling | Rare error diagnostics |
| Complete config examples | All parameter descriptions |
| Historical decisions | Why it was designed this way |

### When recording information

1. **Assess frequency:** High frequency → Level 1, otherwise Level 2
2. **Level 1 references Level 2 must include:**
   - Trigger condition (when to read)
   - Content summary (what you'll find)
3. **Never:**
   - Place low-frequency detailed flows in Level 1
   - Reference Level 2 without trigger conditions

Reference Files