Agents Md

AGENTS.md Audit

AGENTS.md is the source of truth for agent instructions. Claude Code loads both AGENTS.md and CLAUDE.md natively — no symlink required. If a project already has a CLAUDE.md, rename it to AGENTS.md (the tool-agnostic name).

AGENTS.md files are execution contracts, not knowledge bases.

Litmus test for every line: "Would removing this cause the agent to make a mistake?" If no, cut it. Bloated instruction files cause agents to ignore actual rules. KISS applies to instruction files too — the simplest set of rules that prevents mistakes is the best set.

Reference Files

Quick Example

Input: AGENTS.md with stale commands and generic advice Quick audit result: 5/10 (Fail) Key issues: Missing test command, generic "follow best practices" advice, dead link to deleted folder Fix: Add npm test, replace generic advice with specific gotcha, remove dead link After: 9/10 (Pass)

How to Use

Default path:

• Start with quick audit using references/quick-checklist.md (10 checks)
• Escalate to full audit (references/quality-criteria.md) only when quick audit fails, file is high-risk, or user requests it
• Apply edits only after reporting findings and getting confirmation

Progressive loading:

• Always load the checklist for the selected audit mode
• Load references/refactor-workflow.md only for low-signal files (below target score, stale commands, or root file over ~150 lines)
• Load references/templates.md only when drafting a new file or rebuilding from scratch
• Load references/root-content-guidance.md only when deciding what stays in root vs moved out

Audit Workflow

Copy this checklist to track progress:

Audit Progress:
- [ ] Step 1: Discover files
- [ ] Step 2: Select audit mode (quick or full)
- [ ] Step 3: Run audit against checklist
- [ ] Step 4: Report findings with score table
- [ ] Step 5: Propose minimal diffs
- [ ] Step 6: Validate changes
- [ ] Step 7: Apply and verify

Step 1: Discover files

Run:

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) 2>/dev/null | sort

Also check for a home-level file: ~/.claude/CLAUDE.md (applies to all sessions).

AGENTS.md is the source of truth. If a project has a CLAUDE.md without an AGENTS.md, recommend renaming it:

mv CLAUDE.md AGENTS.md

Claude Code loads AGENTS.md, CLAUDE.md, and CLAUDE.local.md natively from any level. No symlinks needed. Instruction files at multiple levels (project root, parent directories, child directories) are all loaded automatically. CLAUDE.local.md is the gitignored personal variant. Audit each level independently.

For monorepos, include workspace-level AGENTS.md files.

Step 2: Select audit mode

• Quick audit: Default for most files (10 checks, target >= 8/10)
• Full audit: When quick audit fails, file is high-risk, or user requests full scoring

Step 3: Run audit

• Quick audit target: >= 8/10 checks from references/quick-checklist.md
• Full audit file-quality target: >= 91% of applicable points from references/quality-criteria.md
• Full audit execution target: 2/2 when producing an edit proposal
• Score each root file independently

Step 4: Report findings

Output a concise report before edits:

## AGENTS.md Audit Report

| File | Mode | Score | Grade | Key Issues |
|------|------|-------|-------|------------|
| ./AGENTS.md | Quick | 6/10 | Fail | Missing test command, stale path, doc-heavy section |

Step 5: Propose minimal diffs

• Fix broken/stale commands first
• Remove generic, duplicate, or obsolete guidance
• Move deep detail into linked files using @path/to/file.md import syntax
• Use emphasis ("IMPORTANT:", "YOU MUST") on critical rules that agents tend to skip
• Keep rewrites incremental and preserve useful wording when possible

Show each proposed change with rationale and a diff snippet.

Step 6: Validate changes

Validation loop: 1. Run smoke checks for core commands (dev, test, build, lint/typecheck) when applicable 2. If commands cannot be run, verify script existence and note the limitation 3. Check that linked paths resolve 4. Confirm no contradictory rules remain 5. If issues found → revise → validate again 6. Only proceed when validation passes

Step 7: Apply and verify

• Apply approved edits
• After each PR, add at most one new gotcha only if it prevented or fixed a real mistake
• Verify changes by re-running relevant commands

Gotchas

• Don't rewrite the entire file when targeted edits would pass audit — incremental fixes preserve useful wording and reduce review burden.
• Don't add gotchas that aren't grounded in a real failure — hypothetical warnings become noise the agent learns to ignore.
• Don't audit CLAUDE.local.md the same way as AGENTS.md — local files are personal and not committed, so enforce less strictly.
• Don't remove emphasis markers (IMPORTANT, YOU MUST) from rules agents consistently skip — these exist because the default phrasing was not enough.
• Don't treat a high quick-audit score as permission to skip validation — stale commands can hide behind passing checklists.

Full Quality Criteria (File 45 + Audit 2)

Score each AGENTS.md root file with this checklist.

Contents

• A. Commands and execution readiness (12 checks)
• B. Gotchas and repeated mistakes (10 checks)
• C. Conventions and decision boundaries (8 checks)
• D. Signal-to-noise and bloat control (8 checks)
• E. Currency and validation (7 checks)
• F. Audit execution checks (2 checks)
• Grade mapping and automatic fails

Target: >= 91% of applicable points for grade A

Scoring

• File quality (1-45): Yes = 1, No = 0, N/A = excluded from denominator
• Audit execution (46-47): score only when producing a report/edit proposal
• File grade uses earned / applicable

Use this when auditing from first principles: the file should help an agent execute correctly with minimal context.

A. Commands and execution readiness (12)

1. Includes a working dev command (or equivalent local run command) 2. Includes a working test command 3. Includes a working build command 4. Includes a working lint and/or typecheck command 5. Includes deploy/release command when applicable 6. Includes migration/seed/db command when applicable 7. Commands are copy-paste ready (no placeholders) 8. Commands match the actual package manager and scripts 9. Includes required environment bootstrap steps (including secondary runtimes like Python venvs) 10. Includes quick path/context for where to run commands (root/workspace) 11. Includes one command for targeted test/debug iteration 12. Avoids duplicate or conflicting command variants

B. Gotchas and repeated mistakes (10)

13. Documents at least one high-frequency failure mode 14. Gotchas are project-specific, not generic 15. Gotchas include corrective action (what to do instead) 16. Gotchas include trigger context (when the rule applies) 17. Captures at least one issue discovered from recent PR/review feedback 18. Includes ordering/dependency gotchas where order matters 19. Includes data/env gotchas where setup mistakes cause failures 20. Avoids vague advice like "be careful" or "follow patterns" 21. Separates universal rules from edge-case rules 22. Removes gotchas that no longer happen

C. Conventions and decision boundaries (8)

23. States conventions that materially change implementation choices 24. States naming/path conventions when CI/tooling depends on them 25. States test strategy conventions (unit/e2e boundaries) when relevant 26. Uses @import syntax or links for non-universal detail instead of inlining in root 27. Marks scope boundaries for monorepo root vs workspace instruction files 28. Avoids restating obvious defaults known by modern coding agents 29. Uses precise language (specific verbs, explicit conditions) 30. Uses emphasis markers (IMPORTANT, NEVER, YOU MUST) sparingly on critical rules that agents tend to skip

D. Signal-to-noise and bloat control (8)

31. Root file stays concise for repo complexity (60-150 lines is common for active app repos) 32. No full framework documentation pasted inline 33. No copy-pasted full templates 34. No exhaustive file tree or "every file" inventory 35. No long architecture deep dives in root file 36. Uses links to detail files for non-universal guidance 37. Removes duplicate guidance repeated across sections 38. Each section passes the litmus test: removing it would cause the agent to make mistakes

E. Currency and validation (7)

39. Referenced file paths exist 40. Referenced tools/dependencies are currently used 41. Commands have been run (or limitations are explicitly documented when run is not possible) 42. Removed references to deleted folders/APIs 43. Version-sensitive guidance is date/version scoped where needed 44. Includes a clear maintenance loop (how to keep file current) 45. CLAUDE.local.md used for personal/gitignored overrides (not mixed into shared AGENTS.md)

F. Audit execution checks (2)

46. Post-change report includes concrete issues and resulting score 47. Suggested edits are minimal and traceable (diff-first)

Grade mapping (file quality only)

Use earned / applicable percentage:

• A: >= 91%
• B: 76% to < 91%
• C: 59% to < 76%
• D: 39% to < 59%
• F: < 39%

Example: 36/40 = 90% -> Grade B.

Automatic fails

Mark grade as F regardless of score if any are true:

• Commands are mostly broken/stale
• Instructions are primarily generic advice
• File is dominated by copied docs/templates and not executable guidance

Quick Checklist (10)

Use this for a fast triage pass.

Scoring:

• Yes = 1
• No = 0
• N/A = exclude from denominator
• Quick target: >= 8/10 (or equivalent with N/A)

1. Core run/test/build/lint commands exist when applicable 2. Commands appear runnable and match project scripts/tooling 3. Setup/bootstrap requirements are documented 4. At least one project-specific gotcha is documented 5. Gotchas include corrective action (what to do instead) 6. Conventions that change implementation choices are explicit 7. Every line passes the litmus test: removing it would cause the agent to make mistakes 8. Root file avoids framework doc dumps/templates 9. Linked paths and commands are current (not stale/dead) 10. Non-universal detail is linked out (via @import or child files), not inlined

Quick grade:

• Pass: >= 8
• Borderline: 6-7
• Fail: <= 5

Automatic fail:

• Commands are mostly broken/stale
• Content is mostly generic advice/template text

Refactor Workflow

Use this when AGENTS.md is bloated, stale, or low-signal.

Trigger conditions

Refactor when any of these are true:

• Root file is over ~150 lines and hard to scan
• Commands are missing, stale, or contradictory
• File contains framework docs or copy-pasted templates
• Guidance is generic and does not prevent real mistakes

Step 1: Snapshot and isolate essentials

Extract only what is required for every task:

• Run/test/build/lint commands
• Critical environment/setup requirements
• High-frequency gotchas
• Project conventions that affect implementation

Everything else is candidate for linked references or deletion.

Step 2: Remove bloat fast

Delete first, then add back only what earns its place. For every removed line/section, record one reason: generic, duplicate, stale, or moved (to a linked reference).

Remove:

• Full documentation and tutorial-style prose
• Long architecture explanations in root
• Exhaustive file maps
• Generic advice ("write clean code", "use best practices")
• Outdated commands and dead links

Step 3: Rebuild root file in strict order

Use this order to keep files scannable: 1. Project one-liner 2. Commands 3. Gotchas (failure mode -> fix) 4. Conventions and boundaries 5. Links to deeper references

Step 4: Move detail out with progressive disclosure

Create or update supporting files for non-universal detail:

• .claude/testing.md
• .claude/architecture.md
• .claude/code-style.md
• workspace-specific AGENTS.md files in monorepos

Link from root using @import syntax:

- Testing details: @.claude/testing.md
- Architecture: @docs/architecture.md

Rule: if guidance is needed in fewer than ~30% of tasks, move it out of root.

Step 5: Validate before finalizing

Run or verify:

• Core commands are runnable from documented location (or explicitly marked as not runnable in the current environment)
• Linked files exist
• No contradictory rules remain
• Root file stays concise and operational
• Removed guidance did not include rare-but-critical constraints (security, migration, release, incident flows)

Step 6: Publish an audit summary

Use a concise summary table:

| File | Before | After | File quality | Audit execution | Key wins |
|------|--------|-------|--------------|-----------------|----------|
| ./AGENTS.md | 240 lines | 96 lines | 26/45 -> 42/45 | 0/2 -> 2/2 | Added commands, removed doc dump, fixed stale paths |

Pitfalls

• Preserving large sections "just in case"
• Replacing one template dump with another template dump
• Keeping contradictory rules to avoid conflict with history
• Adding style advice that linters already enforce

Root Content Guidance

Use this when deciding what stays in root instruction files.

Keep in root

• Copy-paste commands (dev, test, build, lint/typecheck, deploy/migrate when relevant)
• High-frequency failure modes with fixes
• Non-obvious conventions that affect implementation choices
• Required environment/setup facts needed to execute tasks
• Pointers to deeper docs (.claude/*.md, workspace-level instruction files)

Move out of root

• Framework documentation and architecture deep dives
• Copy-pasted templates
• Exhaustive file inventories
• Generic advice not tied to this codebase
• Rules already enforced by linters/CI defaults

Use @path/to/file.md import syntax to link detail files from root:

# Additional context
- Architecture: @docs/architecture.md
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

Framework note

• Do not paste framework docs into AGENTS.md.
• If framework behavior causes repeated mistakes, add one short gotcha plus the command/link that resolves it.

File placement hierarchy

AGENTS.md is the source of truth. Claude Code loads both AGENTS.md and CLAUDE.md natively — no symlink required.

Instruction files are loaded from multiple locations:

• `~/.claude/CLAUDE.md` — applies to all sessions (personal defaults)
• Project root `./AGENTS.md` — shared with team via git (tool-agnostic name)
• `./CLAUDE.local.md` — gitignored personal overrides at project level
• Parent directories — inherited in monorepos (root + child both load)
• Child directories — loaded on demand when working in that directory

Always write to AGENTS.md (the tool-agnostic name). Audit each level independently. Root should contain only universal rules; child files should contain directory-specific rules.

Emphasis for critical rules

Use emphasis markers ("IMPORTANT:", "YOU MUST", "NEVER") on rules that agents tend to skip. This improves adherence for high-stakes constraints (security, data loss, deployment). Do not overuse — if everything is "IMPORTANT", nothing is.

Common anti-patterns

• "Follow best practices." -> replace with explicit commands/rules
• "Use TypeScript." in an all-TypeScript repo -> remove
• 300+ line root file with no links -> split with @import progressive disclosure
• Commands copied from stale CI config -> verify or delete

Minimal Skeletons (Not Full Templates)

Use these as structure starters only. Fill with project-specific commands, gotchas, and conventions.

Do not ship these verbatim.

Before/After Examples

Bad Example (Generic Template)

# My Project

This is a TypeScript project. Follow best practices.

## Getting Started
Install dependencies and run the app.

## Code Style
Write clean code. Use TypeScript properly.

Issues: No commands, generic advice, no gotchas, no actionable guidance

Good Example (Execution-First)

# payments-api

REST API for payment processing.

## Commands
- `npm run dev` - Start local server (port 3000)
- `npm test` - Run test suite
- `npm run typecheck` - Type check without building
- `npm run db:migrate` - Run database migrations

## Gotchas
- Use `PaymentIntent.create()`, not `Charge.create()` (Stripe v3 deprecation)
- Always validate webhook signatures with `stripe.webhooks.constructEvent()`
- Run migrations before tests: `npm run db:migrate && npm test`

## Conventions
- Payment amounts are in cents, not dollars
- Use `createPaymentIntent()` helper for all payment creation

Wins: Copy-paste commands, specific gotchas with fixes, implementation-affecting conventions

Root file skeleton (single project)

# <Project name>

One-line description.

## Commands
- `<dev command>`
- `<test command>`
- `<build command>`
- `<lint/typecheck command>`

## Gotchas
- `<failure mode> -> <corrective action>`
- `<failure mode> -> <corrective action>`

## Conventions
- `<project-specific convention that changes implementation choices>`

## References
- @docs/architecture.md
- @.claude/testing.md

Root file skeleton (monorepo)

# <Monorepo name>

One-line description.

## Commands
- `<root install/build/test/lint commands>`

## Workspace map
Each workspace has its own `AGENTS.md`:
@apps/<app>/AGENTS.md
@packages/<pkg>/AGENTS.md

## Rules
- `<cross-workspace rule that affects all workspaces>`

## Do not commit
<Files/dirs that are runtime inputs or build outputs, not source>

Root file skeleton (multi-language monorepo)

For projects mixing runtimes (e.g., Node + Python, Node + Rust):

# <Monorepo name>

One-line description. <Language A> + <Language B> monorepo using <tooling>.

## Commands
- `<root install/build/test/lint commands>`
- `<language-B setup command>`

## Workspace map
Each workspace has its own `AGENTS.md`:
@apps/<app>/AGENTS.md
@packages/<pkg>/AGENTS.md

(`packages/<lang-b-pkg>` is <Language B>-only; see its README for entry points.)

## Rules
- **Always use `<venv-or-toolchain-path>`, never global `<tool>`** — dependencies may not be on PATH.
- <Cross-language boundary rule>

## Do not commit
<Runtime inputs, build outputs, venvs, node_modules, caches>

Bad vs good

Bad:

• 300 lines of framework docs
• Full folder tree for entire repo
• Generic advice with no commands

Good:

• Clear run/test/build/lint commands
• 3-8 high-value gotchas from real failures
• Non-obvious conventions and boundaries
• Links to deeper files for non-universal detail

Authoring rules

• Prefer bullets over paragraphs
• Keep root file typically within 60-150 lines
• Each line should save debugging time or prevent a known mistake