My agent ignores my rules. Is CLAUDE.md too long?

Guides

If your agent follows a rule one day and ignores it the next, the file may be the problem rather than the model. Every line in CLAUDE.md or AGENTS.md loads into every session. A long file buries the important rules among stale ones, contradicts itself, and leaves less room for the task.

Measure it first

Count what the engine actually loads: your personal file plus the project file. Estimate tokens as characters divided by four. CommonRig's footprint score starts at 100 and deducts for:

  • Size: one point per 250 estimated tokens past 3,500 per engine, up to 30.
  • Dated lines: one point each, up to 10. Dates mark history, not rules.
  • SUPERSEDED, DEPRECATED, RETIRED: two points each, up to 10.
  • Repeated lines over 40 characters: one point each, up to 10.
  • Secret-shaped values: ten points each, up to 30.
  • Absolute home paths and em or en dashes: half a point each, up to 5.

You can score a pasted file here for free, or run rig doctor --lite locally from the free sample. A score describes the footprint; it does not prove the rules are right.

What a cut looks like

The kit includes a fictional before-and-after example. The 263-line "before" file had incident dates, repeated test reminders, SUPERSEDED notes and a fake API key. After curation it went from about 2,067 estimated tokens to 350, and from a score of 62 to 100. Nothing useful was lost: the queue incident became one lasting retry rule, three test reminders became one test gate, and the rest moved to where it belongs.

Where things go instead

  • Incidents and decisions go to a work log or ledger, with the date there.
  • Current tasks go to your tracker. They are stale by next week.
  • Commands and procedures go to project docs or a skill that loads when the task needs it. Leave one line: "release steps: docs/release.md, read when releasing".
  • Facts the agent learns go to an indexed memory folder, not the always-loaded file.
  • Secrets go to a secret store. If one was in the file, rotate it.

Then enforce the critical few

A short file helps the model remember. It still forgets sometimes. For the two or three rules that must never break (no force push to main, no deleting outside the project), add a hook that checks before the tool runs.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides