# Stop paying to polish AGENTS.md / CLAUDE.md: keep it lean, move rules into hooks, and test it with 5 probe tasks — retained record

> Retained reddit record from reddit:ClaudeCode.

Canonical: https://highsignal.app/data/records/141ac0ba45aaca24

[← sources](https://highsignal.app/data)


source: [reddit](https://highsignal.app/data/reddit) (reddit:ClaudeCode)  published 2026-10-25 13:42 ingested 2026-10-26 02:39

[original source ↗](https://www.reddit.com/r/ClaudeCode/comments/1xf2pkt/stop_paying_to_polish_agentsmd_claudemd_keep_it/)

## retained text



```
r/codex had a thread this week asking how much people have *spent* on their AGENTS.md. One person was on gen 3, about $50 of usage in with $25 to go. The replies split into "tune it forever" and "mine is 20 lines." Here's where I've landed, with what the Claude Code and Codex docs actually say.

**Why the spiral happens.** A rule gets ignored, you add a paragraph, the file grows, other rules get weaker. The Claude Code best-practices page says it directly: "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost." Its test for every line: "Would removing this cause Claude to make mistakes?"

**What I keep in the file:** build/test/lint commands it can't guess, never-touch paths and actions, the definition of done (one command), non-obvious gotchas, and pointers with *when* to read each. Workflows go to linked docs or skills, decisions to ADRs, and anything that must always hold goes into a hook, CI or permissions with a one-line pointer.

**The loading gotcha.** Since v2.1.277 Claude Code reads AGENTS.md natively, but by default **only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md** in your working directory or above. Adding a personal CLAUDE.local.md stops Claude from reading AGENTS.md for you. Fixes: `@AGENTS.md` at the top of CLAUDE.md, or `/config` → Project instructions → read both. A CLAUDE.md that says "read AGENTS.md" *in words* only works if Claude decides to open it. Also: `@` imports load at launch, so they don't save context. Use plain paths with a "when" for things you don't need every session.

**Test it instead of rewriting it.** Five probe tasks, each in a fresh session, stopped as soon as you see the first moves:

    "Fix the failing date test in src/server."  -> runs the right test cmd, finds the TZ gotcha
    "Add a column to orders."                    -> new migration, doesn't edit an old one
    "Format dates nicely in the invoice view."   -> no new package
    "Add rate limiting to the login route."      -> opens the auth ADR first
    "Is the build green? Then push."             -> stops before pushing

When one fails, first ask "can a tool enforce this?" (the push one should fail at permissions, not at the instructions). Only then change one line, and re-run all five. `/memory` confirms what loaded, and `/doctor prompt-audit` (v2.1.283+) audits CLAUDE.md and AGENTS.md for stale or contradictory instructions.

Write-up with the full keep/move table, a ~25-line example AGENTS.md, what loads when in Codex vs Claude Code, and when a rewrite is actually worth it: https://medium.com/@r3dtuxedo/how-much-should-you-invest-in-your-agents-md-69f8e36583bc

(Disclosure: I wrote it. No affiliation, no referral links.)
```



document fetched 2026-10-26 00:36 · canonical https://reddit.com/r/ClaudeCode/comments/1xf2pkt/stop_paying_to_polish_agentsmd_claudemd_keep_it
