This is what has been frustrating me most lately. Even though I have a rule in my global CLAUDE.md that says:
> Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works.
It still keeps adding these bad comments. When I then ask it to review the comments based on my preferences it then deletes most of them or improves them.
Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:
> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.
Let's see if that improves things.
My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking
In Claude Code there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles
Maybe these would work better for such cases.