[MODEL] Claude verbose code comments by default — ignores instructions to stop.
Preflight Checklist
- [x] I have searched existing issues for similar behavior reports
- [x] This report does NOT contain sensitive information (API keys, passwords, etc.)
Type of Behavior Issue
Persistent bad behavior. Claude ignores my instructions or configuration.
What You Asked Claude to Do
Description
Claude Code adds far too many code comments by default. The comments are mostly redundant, restating what the adjacent code already makes obvious or simply making references to the chat with Claude itself, leaking its chain of thoughts. It happens on every language, every model.
Crucially, this default persists even when explicitly told to stop:
- A clear, mandatory rule in
CLAUDE.mddoes not reliably suppress it. - Reinforcing the rule via the memory system does not stop it either.
I suppose the core problem is that verbose commenting is the out-of-the-box default, and that default is strong enough to override explicit user instructions. Users shouldn't have to stack a CLAUDE.md rule + memory entries + enforcement hooks just to get clean code, and that still working partially.
Environment
- Claude Code
- Model: claude-opus-4-8, also verified on Opus 5 and Sonnet 5.
What Claude Actually Did
Contant verbose code commenting.
Expected Behavior
Restrained commenting as the default — comment only genuinely non-obvious constraints or "why" decisions, not self-evident "what." And when a project instruction says to minimize comments, that instruction should be reliably respected.
Actual behavior
Reflexive explanatory comments on most code output, even when instructed otherwise. Requires constant manual cleanup or cleanup sessions with other models.
Files Affected
allPermission Mode
Accept Edits was ON (auto-accepting changes)
Can You Reproduce This?
Yes, every time. Happens pretty much on every session.
Steps to Reproduce
Just ask it to write code
Claude Model
Opus, Sonnet, Fable
Relevant Conversation
Some comment examples:
// A contribution ID collided with one owned by someone else, or a channel kind that doesn't match it.
// Must stay below CHUNK_WORDS — the loop steps by the difference.
// Ollama answers empty text with 200 and no vector, which would read as a model fault.
// Unwrapped this is a bare "fetch failed" — no URL, no reason. The usual cause is a container pointing at 127.0.0.1 instead of host.docker.internal.
// Another service on that port answers 200 with HTML, and a raw parse error names neither it nor the URL.
// Asked, never assumed — no path may fall back to the column default.
Impact
High - Significant unwanted changes.
Claude Code Version
2.1.228
Platform
Anthropic API
Additional Context
_No response_
24 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
keep it until it is solved 💃
totally agree! Comments re very verbose and mostly non even human readable
Agreed this is a large usability issue currently. I have to tell it to stop over commenting every time, and it still gets it wrong despite it having this in the CLAUDE.md file and memory more than once.
Comments should only exist for complex parts of the code which aren't understandable without the comment, not to explain every little line of code or every file
Sometimes I still see code between the comments. They should rename the product.
Same here, tried many different approaches to getting the comments down (rules, hooks, instructions) but none seem to be effective. It also got worse in the last few model versions (since Opus 4.7 it really increased).
In some cases, I quite like it though: as a reviewer the comments sometimes help to understand certain things a little bit faster. I go over all the comments, clean them up manually, then approve and merge.
But I don't want this for every task. Some kind of built-in slider / setting per session would be nice to have (defaulting to low comments), or just Claude adhiring to CLAUDE.md instructions.
OMG this is annoying.
The primary issue is that the code comments make references to the chat with claude itself, which should not be persistent in the codebase and are confusing to anyone else reading it who was not part of that same chat.
Code comments should just describe its current state. I don't see why it should every write something like "removed X because of Y ..."
Another annoying this is all the references to "phases" when using the plan mode in code comments. These comments never make sense after completion of the implementation since they reference a chat the user might not have access too and merely describe intermediary implementation steps.
Sometimes the agent needs to change multiple files just to keep comments up-to-date, this is really counter-productive.
Comments should describe the current state of the code, if it is not clear, and eventually reference meaningful documentation Specs/ADRs etc. So the agent knows where to look to find the right context.
To me, comments are just a tiny piece of the problem. EVERYTHING Claude ever says is way, way too verbose (not _just_ code comments). Short of using Caveman, there appears to be nothing anyone can do to fix that.
I get that Anthropic wants the smartest Claude possible, one that can hit every benchmark: I truly get it. But in only training for "intelligence", you've made an asshole AI that won't shut up.
Real users (read any online forum where people discuss Claude: Reddit, Hacker News, Slashdot, etc. ... they will all agree) would _happily_ trade a few benchmark points in exchange for an AI that told you a two sentence answer in two sentences ... instead of two paragraphs.
Commenting so this doesn't get closed
It's a VERY annoying issue we also have. I have to do "comment review" passes to remove most of them
I have instructions in CLAUDE.MD, in skills and in memory. Opus mostly ignores these instructions.
We have been stricken with these excessive comments recently too. Bump this higher.
Hey Claude, next time can I have some code with my comments, thanks?
Commenting so this doesn't get closed.
I tracked LOC and comments per PR and roughly 17% diff is just comments before I ask to condense it during review.
Parsed 464 local session transcripts plus git history. Wanted to add a couple major findings that I have.
It scales with session depth. Comment density of code written, bucketed by how many tool calls had already run in that session:
| tool calls so far | lines written | comment % | blocks >=8 lines per 1k code |
|---|---|---|---|
| 11-30 | 4,175 | 12.1% | 0.82 |
| 31-80 | 16,966 | 13.9% | 2.12 |
| 81-200 | 14,310 | 16.3% | 3.01 |
| 200+ | 16,005 | 15.2% | 4.20 |
It's session findings, not documentation. Among comment blocks of 8+ lines, the share containing an internal issue ID went 8% → 33%. Content is typically a dated investigation result or the narrative of a past regression: commit-message material written into the nearest source file. Same default #85130 asks to change.
And it accretes. Of 255 blocks of 8+ lines in the tree, 121 (47%) were built across more than one commit. One 38-line block was assembled over 14 commits. Nothing ever removes a paragraph.
A/B, same model, same edit task, three fixtures differing only in context:
| fixture | comment lines added |
|---|---|
| terse file, bare instruction | 0 |
| terse file, prompt loaded with rationale (past regression, dates, IDs) | 0 |
| identical code with a 16-line comment block above it | +3 |
Being told rationale did nothing. A verbose neighbour did it. That points at the "match the surrounding comment density" instruction, which has no length bound, so touched regions ratchet up and hold. Cold greenfield prompts stayed terse (Opus 5: 3 comment lines in 30), so this isn't an unconditional default.
With the introduction of watermarking, I doubt this behaviour will be fixed. More comments will increase the effectiveness of watermarking on Claude generated code.
Same issue, Claude writes super long comment blocks with very little code. The comments are based on input, changes but they are over-detailed. If Claude needs this, it should outsource most of the comment info into meta files.
Thiiis! So annoying. I created a custom clean-comments command that I need to run after finishing every new feature.
so annoying, I have to remind it everytime to have less comments and even add in memory but still
Up, particularly annoying issue
Thanks for this research.
I like to add a rule in CLAUDE.md to prepend a prefix tag
CLAUDENOTE:to temporary comments 'for later stripping' (I let the model choose when to strip the comments). I also have a hard limit of 4 lines for permanent non-doc comments (i.e. simple code comments), usually I'll have some kind of exception (for e.g. math-heavy comments, or maybe every 500 lines).The bigger problem I have is the model writing weird poetry instead of human readable prose. I don't know if this is caused by those rules, by Claude.MD compaction (which is what the model claimed to me, CLAUDE.md is the 'house style' and letting the LLM compact it via strange sentence forms propagated the style elsewhere over time).
If this happens to you:
Note: auditing comments on entire codebases can be quite expensive. You can do this quickly with ultracode but expect it to use a lot of tokens (I think for a ~200k lines codebase it used 14 million tokens to check all the comments).
We're also experiencing the same. Excessive comments being added next to the code, references to the chat itself, etc. Seems to have gotten a lot worse with the latest releases. I'm on v2.1.246.
Is there someone we can @mention here who could take a look and potentially prioritise this?
70% changes of PR is comments from Opus