A short, practical pass for AGENTS.md, CLAUDE.md and Cursor rules. Work through the ten checks in order. The claims stay modest — no invented vendor stats — and the aim is a smaller always-on file that the model is more likely to follow.
Originally published on clogmeter.vercel.app.
Instruction files grow quietly. A rule gets copied into CLAUDE.md and a Cursor rule, a release checklist lands in the root AGENTS.md, and a year later the agent is re-reading all of it on every turn. Markdown is advisory: hooks, linters and CI enforce the rules that must never be skipped. The checklist below is a way to cut the rest without guessing.
The 10 checks
1. Weigh before you cut. Paste the files into a checker so you know the token cost and can spot duplicates and conflicts before deleting by gut feel. (If you only want a single-file count, the AGENTS.md token counter is enough.)
2. Kill duplicate always/never lists. Keep one canonical Always/Never section. Delete or replace copies with a one-line pointer. Duplicates still cost tokens and confuse the model.
3. Resolve conflicting always/never rules first. Contradictory “always X” / “never X” (or near-opposites across files) make the model hedge. Cut one side before trimming anything else.
4. Prefer path-scoped rules over always-on. If a rule only applies under src/api/** (or similar), use a path-scoped Cursor rule or a nested AGENTS.md / CLAUDE.md instead of stuffing the root file. Cursor’s own size guidance, including the ~500-line rule limit and the four rule types, is in Cursor rules token limit.
5. Move rare procedures to skills. Release checklists, migration steps and once-a-month workflows belong in on-demand skills or docs, not in the always-on root file. Where an instruction lives decides when the agent sees it and what it costs; that trade-off is covered in AGENTS.md, skills or MCP.
6. Delete what tools already enforce. Linters, formatters, typecheckers, hooks and CI already catch many “always/never” rules. Markdown that repeats them is advisory noise and still spends tokens every turn.
7. Skip directory trees and stack inventories. Agents can discover the repo by reading it. Pasted trees and long tech-stack lists burn tokens every turn without improving adherence. A tighter example of what belongs in the root file is in the AGENTS.md example.
8. Keep one source of truth across tools. Prefer a canonical AGENTS.md with thin CLAUDE.md / Cursor adapters. Avoid divergent copies or symlinks that double-count the same text. See CLAUDE.md vs AGENTS.md vs Cursor rules.
9. Enforce hard “never” rules outside markdown. If ignoring a rule once would hurt, use a hook, permission, linter or CI check. Prose alone is advisory — vendors treat memory files as context, not enforced config.
10. Re-weigh after the trim. Run the checker again on the cleaned set. Confirm the token drop and that no new conflicts appeared. Export a trimmed copy if useful. For documented size ceilings, see How long should CLAUDE.md / AGENTS.md be?.
How to use this
One pass is enough for most repos. If the root file is still long after these ten checks, split by concern (scoped rules plus skills) rather than squeezing more prose into the same always-on file.
To do the weigh-and-reweigh steps in the browser, paste the files into Clogmeter. It counts tokens, flags exact and near-duplicate rules and always/never conflicts, suggests trims, and can export a trimmed copy. Nothing is uploaded.
If you want to see where your own AGENTS.md, CLAUDE.md or Cursor rules spend tokens, we built a free browser-only checker that also flags duplicates and always/never conflicts: Clogmeter.
Top comments (0)