legendtkl Agents MD Polish
A short, repeatable workflow for keeping AGENTS.md and CLAUDE.md files short, project-specific, and executable. Anthropic recommends keeping CLAUDE.md under 200 lines; longer files "consume more context and reduce adherence." Bloated files cause agents to ignore your actual rules.
When invoked, run this workflow
1. Discover
Find guidance files in the current project:
AGENTS.md, CLAUDE.md
Check the repo root first, then any nested AGENTS.md files in subdirectories
(monorepos use one per package, with the closest file taking precedence).
2. Audit
Use references/audit-checklist.md to score each file. The deterministic
checks (line count, byte size, broken file references) live in
scripts/audit_agents_md.mjs — run it first:
node scripts/audit_agents_md.mjs <file>
The script exits non-zero on broken file references or missing files. Read
its JSON output (when invoked with --json) to drive follow-up actions.
3. Diagnose
For each issue, look up the matching pattern in references/polish-patterns.md
and explain the why in one sentence. Don't dump the whole pattern — just the
1-line summary so the user understands the recommendation.
4. Propose
Group the proposed changes by severity (error → warn → info). For each, show a unified diff using the Edit tool's preview format. Don't apply yet.
5. AWS test (sanity gate)
Before applying, ask of every line you would keep:
"If I remove this line, will an agent make a mistake?"
If the answer is no, propose deletion instead of modification. Bias toward shorter files.
6. Apply
Apply changes the user accepted. For long extracted content (architecture
notes, API specs, full command lists), write to docs/<topic>.md or
AGENTS-references/<topic>.md and reference from AGENTS.md by relative
path with a file:line pointer where possible.
7. Bridge-ify (if applicable)
If both AGENTS.md and CLAUDE.md exist and overlap by more than 50%, propose collapsing CLAUDE.md to a single-line bridge:
@AGENTS.md
Use references/claude-bridge-template.md for the bridge pattern and the
short explanation to show the user.
Only keep Claude-specific addenda below the import line if they are not useful to Codex.
Create path (when no guidance file exists)
If the user wants a starter AGENTS.md and none exists, copy
references/agents-md-template.md and fill in the project-specific sections
by inspecting the repo:
- Read
package.json/pyproject.toml/Cargo.tomlfor scripts and entry points - Skim top-level directories to populate Project map
- Don't invent invariants — ask the user for 1-3 they actually care about
What goes in AGENTS.md vs elsewhere
| Type of guidance | Where it goes |
|---|---|
| Route map, commands, invariants, validation entrypoints | AGENTS.md |
| Repeatable multi-step workflows | Skills (.agents/skills/, .claude/skills/) |
| Long architecture notes, API specs, testing guides | docs/ referenced from AGENTS.md |
| Lint / formatter / style rules | pre-commit, ruff/eslint config — NOT AGENTS.md |
| Live external systems (GitHub, DBs, browser) | MCP servers / CLIs |
Hard limits to keep in mind
- Root AGENTS.md: target <200 lines (Anthropic), warn at 200, error at 500
- Root file size: warn >12 KB, error >25 KB
- Sections (H1/H2): warn >17, error >30
- Bullets per section: warn >18
- Inline code blocks: warn >15 lines (extract to referenced file)
- Imports do not save tokens — Anthropic loads them in full at launch. The only real reduction is deleting content.