[FEATURE] Strip comments from CLAUDE.md before sending to model context (or add a setting for it)
Problem
CLAUDE.md is read as raw text — nothing strips comments (HTML-style <!-- --> or otherwise) before the file's content is injected into the model's context. Any comment left in the file is sent to the model verbatim, including via the "this file was modified" system-reminder that quotes the diff.
Repro
- Add a comment to
CLAUDE.md, e.g.:
``
<!-- personal note: don't let the model see this -->
- Save the file, continue (or start) a session.
- Claude Code emits a system-reminder noting the file changed and quotes the modified lines — comment included, verbatim, as part of the model's context.
- Ask the model whether it can see the comment. It can, and will act on instructions placed inside one exactly as if they were plain prose.
There is currently no way to leave a note in CLAUDE.md that's visible to human collaborators (in an editor, in git blame, in a PR diff) but invisible to the model.
Requested behavior
One of:
- Built-in stripping: comments in a recognized syntax (e.g. HTML
<!-- -->) are stripped from CLAUDE.md content before it's added to context, the same way a browser or Markdown renderer would treat them as non-content. - A setting: e.g.
stripCommentsFromClaudeMd(or similar) insettings.json, opt-in or opt-out, so teams that want human-only annotations in this file can have them without consuming context tokens or influencing model behavior.
Why this matters
CLAUDE.md files are frequently long, hand-maintained, and edited by multiple people. Being able to leave a human-only annotation (a TODO, a rationale note, a "why this rule exists" aside intended for the next engineer, not the model) is a normal editing pattern in any other config/doc format. Right now doing so silently changes model behavior and burns context tokens, which is surprising and easy to get wrong — a comment meant purely for a teammate becomes an instruction the model will read and potentially act on.
3 Comments
+1. Found an interesting paper on this: *Why Does CLAUDE.md Keep Growing?
Catastrophic Remembering in Agentic Coding*
It argues that CLAUDE.md bloat comes from an asymmetry: adding an
instruction is cheap, but removing one requires remembering why it was
added in the first place.
Their proposed fix is prompt comments that record an instruction's
rationale — visible to the next editor, but stripped before reaching the
model's execution context — and their experiments show this is effective
at curbing the growth.
If this feature shipped, it would make that solution practically usable.
A feature about supporting comment lines in CLAUDE.md was requested in https://github.com/anthropics/claude-code/issues/18119.
To prevent your issue from auto-closing, you'll need to comment on it every time before 14 days thresholds expires https://github.com/anthropics/claude-code/issues/30407#issuecomment-4813778775, or collect 10 or more thumbs up upvotes. However, for an issue to get any traction it needs to reach social media platforms.
The paper teppeis linked matches something I ran into measuring these files, so here's a number for it.
I parsed 559 public rules files — CLAUDE.md, AGENTS.md, .cursorrules and similar, from PyTorch, Kubernetes, Elasticsearch and a few hundred smaller repos. 23,704 items came out of them, and about 63% contained no instruction at all. Directory trees, reference tables, command examples, notes about why something is the way it is. So the accumulation the paper describes isn't a tail case — by volume it's most of what's in these files.
The wrinkle I'd flag for the design, though: that 63% isn't all strippable. A lot of it is deliberate context that people genuinely want the model to have — the stack, the folder layout, the commands to run.What's actually missing isn't comment-stripping so much as a way to mark intent, because right now "here is our directory layout, please use it" and "note to whoever edits this next, we added rule 12 after an incident" are the same kind of line in the same file with no way to tell them apart.
Which is maybe an argument for the setting rather than automatic stripping. If comments are silently dropped, people will put context in them by mistake and then wonder why the model ignores it. If it's explicit,the syntax itself becomes the signal — this part is for humans, that part is for the model — and that distinction doesn't currently exist anywhere in the format.