Why Does Claude Add So Many Code Comments?

Claude adds excessive code comments when it picks up signals that documentation is expected: heavily commented examples in your prompt, a request for "readable" or "well-documented" code, or review instructions that ask it to explain its reasoning. It is not a quirk; it is the model reading context. Change the context and the comments drop. Tools like fenbs let you store an agreed commenting rule once so every assistant session starts from the same expectation.

The effect is especially common in code review tasks, where Claude often mirrors what it sees rather than what you want. Knowing which cues it responds to makes the fix straightforward.

Why Claude defaults to heavy commenting

Claude's training emphasized helpfulness and readability. When the task is ambiguous, for example "write a function that does X", it leans toward producing code another developer could follow without additional explanation. That means comments on intent, inputs and edge cases.

This default is sensible for many situations. It becomes a problem when you want terse, production-style code, or when comments will be stripped before review. The model is not wrong to comment; it lacks your preference and assumes the safe side is more explanation.

What triggers more comments than usual

Several prompt patterns reliably produce heavier output:

• Showing an example with extensive comments. Claude mirrors the style of examples you include.
• Asking for "clean", "readable", "well-documented" or "beginner-friendly" code.
• Asking Claude to "explain what the code does" in the same request as writing it.
• Code review prompts that ask it to note every line it changed.
• Pasting lightly commented code and asking it to "improve" or "refactor" the file.

The boundary between helpful annotation and noise is a personal style choice. If your house rule is comments only on non-obvious logic, say that. If you prefer no inline comments at all, say that too. Neither is wrong; Claude just needs to know which applies.

How to reduce comments in a single session

Add an explicit instruction at the start of your request or system prompt:

Write no inline comments unless I ask. Function names and short docstrings at the function level only.

For code review prompts, separate the explanation from the code. Ask Claude to write the code first, then in a follow-up ask what changed and why. That keeps the code output clean while still getting the explanation you need.

When providing examples, strip comments from them before pasting. Claude learns from the shape of what it sees. A clean example produces cleaner output than a commented one paired with an instruction to produce less.

Making the rule stick across sessions

Single-session instructions reset when the chat ends. For a project with an agreed commenting standard, whether that is "no inline comments", "JSDoc on public functions only", or a house style, the rule needs to survive session changes and different AI tools.

One approach is an AGENTS.md or CLAUDE.md file at the project root that states the convention; Claude Code reads those natively. For projects where several people use different AI apps, a shared record works better. Save the agreed standard as a Decision in fenbs so every connected assistant reads it before starting work. See what is Claude AI for more on how Claude reads its starting context.

When a code review catches over-commenting, record it as a Lesson in fenbs: what the model produced, what the agreed rule is, and what to check next time. That lesson surfaces in the AI context before similar work begins, cutting the chance of repeating the same pattern. For more on managing AI output style across sessions, see the ai-prompts topic.

What to check when the rule does not work

If Claude keeps adding comments after a clear instruction, check three things. First, whether the examples in your prompt are still heavily commented. Second, whether an earlier system message or CLAUDE.md contradicts the new rule. Third, whether you used a word like "document" or "explain" in the request without meaning to trigger the commenting behavior.

If the model reverts during a long conversation, restate the rule at the point behavior changed. Long contexts can make earlier instructions less salient. For persistent projects, keep the rule in the starting context rather than relying on it staying active through a multi-hour session.

How to do this with fenbs

1. Create a free account and open your project, or add a new one for the codebase you are working on.
2. In Decisions and rules, add the commenting standard: for example, "no inline comments; JSDoc only on exported functions". Record who chose it and the reason.
3. Connect Claude or Claude Code from Integrations and approve the connection. Claude reads that rule at the start of each session.
4. After the next code review, add a Lesson if the rule was broken: what happened and what to look for next time.
5. Update the Decision if the standard changes. The new rule takes effect on the next session without re-pasting anything.

For solo projects with a CLAUDE.md file, you can also add the rule there for use with tools that read those files directly. fenbs works alongside that file and handles decisions that change across the life of the project, such as rule revisions after a review.