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.

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.

My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking