Discussion on "A Working CLAUDE.md/AGENTS.md Template You Can Copy Today"

Dhrutika Rathod · 2026-09-21T04:40:17.280Z

If you've added a CLAUDE.md or AGENTS.md file to your repo and felt like your coding agent still ignores half of it, you're not alone. Most of these files are just vague prose — "write clean code," "f

The strongest point here is that CLAUDE.md/AGENTS.md should encode decisions the model cannot reliably infer, not repeat generic engineering advice. The Preferred/Avoid examples and concrete code patterns make that distinction very clear.

One thing I’ve found useful in production AI work at IT Path Solutions is treating these files almost like an architectural contract: keep the rules small, tie them to actual tooling/tests where possible, and remove a rule once the repository no longer needs it. Otherwise the context file becomes another source of drift.

The five-minute A/B test is especially practical. If removing the file doesn’t measurably change the agent’s implementation choices, you’ve probably documented knowledge rather than constraints.

"Vague prose doesn't change agent behavior any more than it changes a new hire's behavior on day one" is exactly right, and the comparison holds further than it first looks. What actually changes a new hire is a failing test, a linter and a review that blocks, not the onboarding doc. Same here: the rules that survive are the ones something else enforces.

The pattern that has worked best for me is treating the file as a pointer to enforcement rather than a substitute for it. State the rule, then state which check fails when it is broken.

Anything in the file with no corresponding check is a preference, and marking it as one keeps the genuinely load-bearing lines from being diluted.

the pointer-to-enforcement framing is a great way to think about it. Appreciate you sharing this, definitely something worth building on.

The do-not-touch section is the part I'd lean on hardest. We keep something similar across our own repos and the plain list alone doesn't hold up on its own -- an agent working under task pressure will still edit a frozen path if nothing but a comment is stopping it. What's actually worked for us is a pre-commit check that rejects any diff touching those paths unless a human explicitly overrides it, so the rule gets enforced rather than just documented. The review_cadence field in the header is a nice idea too, but I'd want something checking it -- a stale last_updated sitting there for six months doesn't page anyone on its own, it just quietly stops being true.

Mihai_LeanZero - This is a really good point. A do-not-touch list is a documentation-layer fix for what's ultimately an enforcement-layer problem — under task pressure, "explicitly told not to" and "structurally prevented from" are very different guarantees, and I was implicitly leaning on the former. The pre-commit check with an explicit human override is the right shape for this. It also fixes a subtler issue: a written rule can be technically correct but still get "worked around" by an agent that convinces itself an edit is fine, whereas a hard gate doesn't care about the justification. Same logic applies to your review_cadence point, and I think it's the sharper of the two - a metadata field that nobody's watching is really just a comment with extra steps. A CI check that flags any file where last_updated is older than the stated cadence (and fails the build, or at least nags loud enough to be annoying) turns it from a norm into something that actually gets caught. Do you enforce the cadence check in CI, or is it more of a periodic manual audit on your end? Curious how granular you've gone with it — per-file, per-directory, or one blanket rule for the whole context file.

Right now it's closer to a manual audit than CI-enforced. I read through the file when something in that area breaks or when I'm touching it for other reasons, not on a fixed schedule, so no check currently flags a stale last_updated on its own. If I built one, I'd make it per-directory rather than per-file or one blanket rule for the whole thing, since the actual failure mode is a whole area, an API surface, a workflow, drifting together, not a single line going stale in isolation. A single cadence for the entire file would end up either flagging stuff that's still fine or missing the part that's actually gone stale.

Search Hashnode

A Working CLAUDE.md/AGENTS.md Template You Can Copy Today

Responses(6)