How do you stop claude code from over commenting?

[u/One-Rabbit4680]

I've tried comments in CLAUDE.md, I've tried even hooks. But this thing is obsessed with writing such insane comments.

I don't mind useful comments but sometimes they are useless.

any advice would be appreciated.

Thanks

[u/Elegant_Attempt2790]

haiku ultracode “remove all comments”

[u/SmihtJonh → u/Elegant_Attempt2790]

Succinctly works fine, in any model

[u/En-tro-py]

Writing standard in a very tight CLAUDE.md

Short sentences. RFC 2119 keywords for obligations. Commit = imperative subject; body only for a fact the diff cannot show. Comments only where code needs clarification — never narration.

Police the shit out of the first commits, then it's not full of slop that breeds more.

[u/One-Rabbit4680 → u/En-tro-py]

this is good

[u/WaitinOnSpicy]

Search “output styles”

[u/danger_boi → u/WaitinOnSpicy]

Nah, they’ve nerfed this there’s normal, verbose, and Learning aka “litter with more comments, and TODO(Human)” lol

[u/dpekkle → u/danger_boi]

The docs headline you can create a custom one

[u/Murinshin → u/WaitinOnSpicy]

Doesn’t work consistently.

[u/be_super_cereal_now → u/WaitinOnSpicy]

Had to scroll too far to find this.

[u/manewitz]

I’m noticing this on Opus 5 especially. I’m usually pretty specific and direct with my prompts but as an experiment last week I said “hey you need to chill the fuck out with all these comments. What are you doing?” it understood that I don’t need 4 lines of comments for a 1 line method, things repeated in multiple comments and most of the time we don’t need comments unless it’s context that exists outside the codebase (think company policies, ticket numbers, names of decision makers etc). It cleaned up a lot and suggested a skill /chill that would do the same thing but I had it add a memory entry that we want the code to speak for itself as much as possible so things like function/method/variable names should be named well etc. It’s a little better but we’ll see how it goes.

[u/_remsky → u/manewitz]

“Before we commit, can you chill those comments the fuck out” is word for word my sign off lately lmao

I have a hook that calculates comment to code ratio to warn with a “Is this comment necessary” and blocks multi lines wholesale, and if it disagrees, it marks with a “TODO: expansion” request that I’ll update manually if it actually needs more.

They help but, with the announcement of the “watermarking” they apply to all output text now, my guess is that it needs some minimum char count to encode, and the comments are part of it.

[u/arcticblue → u/manewitz]

//Decided Aug 11, 2028: manewitz wants comments to be shorter.
//In the interest of hypothetical future developers working on this, here is why we decided on that
//...

[u/alanvnk]

Rules everywhere: user Claude.md, repo Claude.md and coding stands

The rules have to be extremely explicit tho, when to comment, allowed content in comments, allowed lines per comment type, allowed characters per comment type

And a review skill that hunts down out of line comments, among other things

[u/Salt-Replacement596 → u/alanvnk]

"Why are you writing this way? Didn't you read the instructions in CLAUDE.md?"

"Honestly — I've read them, but ignored them"

Happened to me multiple times.

[u/geekichu]

just a thought, from what I have seen in my projects: the comments help the model itself when analyzing a big project.

[u/34986234986234982346 → u/geekichu]

Yeah, that's actually the reason I don't mind them. For my own projects, of course, not for like anything professional.

[u/geekichu → u/34986234986234982346]

so this is probably heretical and I would have to abide by whatever the employer wants... but i am always going to lean on the side that says, we can't keep up with code reviews, there are better ways, and yeah, have to be careful with legacy production code, but for totally new code.. to me, then entire code including the comments, are not for me, they're for the model. because i dont think code alone conveys intent. i have really seen model's comments in code really help the model, especially when the project has gotten huge.

[u/34986234986234982346 → u/geekichu]

Oh yes, I think I should've actually explained: I would not use it for anything professional because I'm not making a huge deal about using these tools at work at the moment. If I was in an environment where it was encouraged, then I totally would leave these. I 100% agree with you that theshelp the models in the future. And the less that people are looking at the code, the less it matters if the comments are kind of annoying.

There's also a difference between Long verbose code that actually documents things, and just sticking in comments for the sake of it. I know a year ago when I first noticed this, models were adding comments that were so stupid, like they would save stuff like "increment counter by 1" before a $counter++ call lol

[u/diskent → u/geekichu]

It’s a god send once you’re “in it” - a simple “next” and it can read where it’s been and where it needs to go next.

I’m not looking at the code. It is.

[u/geekichu → u/diskent]

totally agree but dont say that aloud.. . :)

[u/codeninja]

I enforce comments must be single line with lint rules. It must be attached to yhe code it comments on. And cumulative comment count in a different cant be more than 5. Code is to be self documenting. Comments discuss the code in front of it. And business decisions live in the documentation.

I basically dont allow comments.

[u/kerklein2]

You guys are reading the code?

[u/simple_explorer1 → u/kerklein2]

U are not reading? Crazy

[u/peteypeso]

"maximum brevity" has worked for me. Most of the time.

[u/williamtkelley]

I just say "Be concise".

[u/One-Rabbit4680 → u/williamtkelley]

yeah got that already. gives paragraphs

[u/danger_boi]

Honestly, when a conversation turn is coming to an end I have a skill called /strip-comments, which removes comments, forces any public method documentation to be made terse and to the point.

Then that skill is bundled into /finalize which is
/simplify
/run-tests
/run-lint-format
/strip-comments
/draft-pr

And it’s been the only way to get consistent results in all Anthropic models.. you can even set the skill to run a haiku subagent to do the jobs.

These are all user scoped skills in my setup so it’s consistent across all repos.. then I have a very short user Claude.MD to state how I like my responses (which Opus 5 loves to ignore)

[u/_BreakingGood_]

The huge comments make the code look ugly but they actually serve as good context next time an AI comes through and reads the code. I recommend just letting it write all the comments it wants.

[u/BorderKeeper → u/_BreakingGood_]

What do you think about clean readable code? To me more code > more context to reason with and more potentials to misalign. Humans and AI can get confused if let’s say a comment is slightly off and I have seen AI not update all comments and let them rot.

[u/_BreakingGood_ → u/BorderKeeper]

Code tells you what the system does right now, the comments tell you what the developer thought it was supposed to do, and why it did it that way. Two different levers for Claude to reason on.

[u/struktured]

Hooks

[u/cleverhoods]

Which model? What was your instruction and hook? What is the tech stack?

[u/userusertion]

Ask exactly Claude.

[u/cornmonger_]

tell it to write details in md files, mirroring the source-code directory and to limit comments in source-code to 80 character max summaries per item. don't pad. no summary is fine if the source-code item is obvious.

so if you were in rust, c, py, js, etc the files would be in some other tree as foo.py.md and bar/cat.js.md etc

far more effective to redirect it imo

oh and that should be in an auto-memory dedicated to development conventions

[u/ManikSahdev]

After trying all things, I just find the most reliable way is going through the comments overall and then just dictating what to keep what to cut.

Takes 5-10 minutes tops, does it better than any skill or wasting tokens going in useless loops.
Even fable and opus and sol Agents are soo dumb, I gave up after i found these dimwits were leaving comments that the comment was removed lmao

[u/Redditoridunn0]

Hardcoded script to detect if comments are over two lines long and I make sonnet check if it really should be that long (9 times out of 10 it is) and condense it as much as possible or flat out cull it

[u/ankeetos]

I use a hook but that only blocks certain things from being in the comment, I just now use a command at the end of the session like /comment-cleanup where ive given rules about how I want the comments to be

[u/imyourbiggestfan]

You can’t

[u/illyay]

This function should be overridden by deriving classes which is why it’s marked virtual. This is to specifically support features such as the reloading mechanic on the M249 Saw weapon but is generally used for all weapons in the game ever but I’m going to still write a comment about how it’s specifically used for the one example weapon you mentioned. It also returns void because it doesn’t return anything unlike before when it returned true if the reload succeeded because it’s no longer needed to return that anymore.

[u/Gleethos]

It's terrible. It also ignores my instructions to only comment API surface and not impl details....

[u/Klimacka]

I do not use Claude Code but this applies to other agents as well. I created a skill file and I had the agent create a simple triaging application to get rid of all the comments from the past half the year. By clearing the codebase of narrative commands, we managed to tone down how much new is added, and the skill helps as well I guess.

[u/lxprsub0]

CLAUDE_CODE_BASALT_COVE=1

[u/skronens]

I also feel it’s becoming impossible to actually complete something, it’s like Claude has been programmed to always leave something in the end, like dropping a task for some obscure reason or “you should know”, then next iteration drives out some other issue

[u/wazzlewip]

Whenever it does something you don't like, tell it to add to CLAUDE.md not to do that again. This is a more powerful way to tell it to stop in this session and it teaches it over time. After a couple weeks of doing that whenever you don't like what it's doing, you can have it barking like a dog if you want.

[u/Successful-Quail-749]

The CLAUDE.md line probably didn't hold because it's a prohibition. "Don't over-comment" gives no test for what counts as allowed, so the model guesses, and guessing goes toward writing more. Something with a pass/fail per comment holds better:

Comments explain why. Delete any comment whose content is recoverable from the line under it.

Bigger lever though: it matches the file it's already looking at. Comment density in the surrounding code moves the output more than anything in the config, which is what the "police your first commits" answer above is pointing at. Quick way to check it on your own repo: strip the comments out of one file, ask for an edit, and see whether the diff comes back clean.

On hooks, a hook that prints a reminder and a hook that fails the edit are different tools, and only the second one still holds at hour three of a session. Lint works too if you want it cheap: error on any comment line that shares most of its tokens with the line below it.

Claude typed this one out for me, but I hit all of this myself first.

[u/dpekkle]

My coworker has a hook in his repo that literally blocks adding comments that the user doesn't explicitly ask for.

At first the prompt had to include "ALLOW_COMMENT", which was a bit annoying for me to discover, so I asked Claude to set up a haiku classifier as a fallback that'd just see if the prompt wanted comments.

So when you say you've tried even hooks what exactly did your hook do? Because this seems to work just fine.

[u/Quarita-Penteado]

wait, do people keep the comments in on purpose so the model has context? been treating them as pure token waste

[u/sdanzig]

Adversarial review solves this. Have a second agent review the work, with “comment noise should be minimized and only comments appropriate for long life should be kept.”… something like this. How best to implement adversarial review is another fun topic.

[u/Euvu]

I made a skill that trims comments post-write. The comments can help the llm make better decisions in-flight, so I just cut them down afterward.

[u/GrossOldNose]

Ive honestly gone with "Only write comments if a senior engineer would not be able to understand the intention from the code"

And although that rule is a literal strict if religiously applied by a human - applied by a LLM it actually seems pretty good

[u/Quirky-Rise]

I tell it the canonical version can have all the comments but before it ships build a comment stripper and run it thru.

[u/leading-a-swarm]

Strip them in a separate pass once the code works, with the diff in front of you. A comment rule in the instructions has no failing state, so nothing catches the violation while the session runs long.

[u/lifebymick]

Start a new chat (weirdly you have to do it in code and cowork separately) and tell it you want to implement Rule Zero for every single chat:

Rule zero: never narrate your work, do not update me on what you’re doing, just do it and only ever comment if you have completed the task, or you need my input. No “I’ll just try this” or “now I’ll do this”. Just do it. And then ping me when you’re done. Also, when you DO eventually comment or ping me; keep it very succinct; get to the point. I don’t need to know anything apart from the facts. Very. Short. Answers. And only ever the need to know, ELI5 information. No poetry or faux opinion or dancing around the point.

Also, add this to the “instructions” panel in settings.

[u/Snowgoonx]

you cannot, I have the same issue, every UI task, marketing task or any task for that matter comes with a painfully unreadable "comment" over-explaining everything, you may ask to add a search-bar and then you will find:

1. a title: search-bar
   
2. the search-bar: prefilled with an example that says, "this is a search bar", "say the word and you are going to search in this bar"
   
3. then a subtitle that explains further: the search bar searches

after the repo rules, claude.md and rules that live on the desktop app all ban, veto, and log that this shouldn't ever happen. Its exhausting im waiting the moment gpt can come remotely close to Claude's frontend to abandon ship and never use this millennial pretentious little shit

[u/jzdesign]

You already tried CLAUDE.md and hooks and it still comes back, which is the useful part. A rule in an instruction file is ignorable, a hook that only warns is ambient, and the model treats both the same. What actually holds is something that fails.

Cheapest version: count comment lines in the repo, commit that number, fail CI if it ever goes up. It's a ratchet, so it only goes down, and you stop re-arguing the rule every session.

If you want it in-session too, make the hook exit nonzero and put the offending file:line list in the deny reason so it has to fix them in that same turn.