Preventing Over-Commenting in Claude Code with CLAUDE.md Directives, Context, Hooks, and Linting

Workflow value: 75/100
Status: active · Freshness: 70/100 · Confidence: 0.90 · Level: intermediate
Categories: Quality Control, Token Saving, Context & Memory, Debugging, CLAUDE.md, Hooks
Original source: r/ClaudeCode post/comment

What problem this solves

Claude Code generating excessive, redundant, or unhelpful comments in generated code.

Summary

This workflow provides multiple strategies to prevent Claude Code from over-commenting. It includes specific CLAUDE.md directives, leveraging the comment density of surrounding code, and implementing pre-commit hooks or linting rules to enforce comment standards.

Why it is useful

This workflow is valuable because it addresses a common and frustrating problem with LLM code generation: excessive verbosity, specifically over-commenting. It provides multiple, concrete, and actionable strategies across different Claude Code surfaces (CLAUDE.md, hooks, context, linting). The advice is specific enough to be implemented and offers a clear way to test the impact, making it highly reusable for users looking to improve the conciseness and quality of generated code.

Workflow

1. Modify your CLAUDE.md file with specific directives to guide comment generation, such as "Comments explain why." and "Delete any comment whose content is recoverable from the line under it."
2. Ensure the surrounding code in your repository has an appropriate comment density, as Claude Code tends to match the existing style.
3. To test the impact of comment density, strip comments out of a file, ask Claude Code for an edit, and observe if the diff comes back clean (without excessive new comments).
4. Implement a pre-commit hook that prints a reminder about desired comment standards.
5. Implement a more stringent pre-commit hook that fails the edit if comments do not meet the defined standards.
6. Configure a linting tool to error on any comment line that shares most of its tokens with the line directly below it, enforcing conciseness.

Tools / artifacts

• CLAUDE.md file
• Pre-commit hooks (e.g., Git hooks)
• Linting tool (e.g., ESLint, Pylint, custom linter)
• Code diffs

Validation signals

• Author states personal validation: "I hit all of this myself first."
• Author suggests a validation method: "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."
• Implied practical testing: "only the second one still holds at hour three of a session"

Limitations

• Low community validation (score 1, 0 comments).
• The linting rule is described conceptually, without specific configuration examples for common linting tools.
• Details for implementing the pre-commit hooks are not provided, requiring users to develop them based on the concept.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.