How to Stop Claude Code Writing Comments (and Other Slop)

To stop Claude Code writing narrative comments, add a comment rule to CLAUDE.md and install a hook that scans every file it edits, so Claude removes the comments in the same turn. An optional gate and a cleanup for existing comments follow. The general case, for any agent, is in stop letting your agent write comments.

Claude Code narrates what the code does

// Validate the user input before processing
// This ensures we only work with valid data
function processOrder(order: Order) {
// Check if the order has items
if (order.items.length === 0) {
  // Return early if there are no items
  return null;
}
// Updated to use the new pricing service for better accuracy
return pricing.total(order);
}

None of these five comments says anything the code does not. The last is a changelog entry in the source: true for one commit, misleading after the next. The better version keeps one comment that says something the code cannot:

function processOrder(order: Order) {
if (order.items.length === 0) return null;
// Totals come from the pricing service so tax rules stay in one place.
return pricing.total(order);
}

aislop calls these narrative comments and trivial comments.

Step 1: set the bar in CLAUDE.md

Claude Code reads CLAUDE.md at the start of a session. Put the comment rule there, with examples rather than adjectives like “minimal”:

## Comments
- Default to no comment. Good names and small functions come first.
- Write a comment only for: why a choice was made, a non-obvious
constraint or workaround, or a public API contract.
- Never narrate what the next line does.
- Never describe the edit you just made ("Updated to...", "Now uses...").
That belongs in the commit message.
- Never leave commented-out code.

A rule is guidance: Claude reads it once and weighs it against everything else in the context, so long sessions drift. The hook in step 2 is the enforcement. For a fuller standard covering errors, types and scope, see the copyable AI coding rules file.

Step 2: check every edit with a hook

npx aislop hook install --claude

This adds a PostToolUse hook on Edit|Write|MultiEdit to ~/.claude/settings.json and writes ~/.claude/AISLOP.md. Every file Claude Code edits is then scanned before the turn ends, and Claude gets the score, the findings with file and line, and next steps.

• --project installs into this repository’s .claude/ instead of your user settings.
• --dry-run shows exactly what would be written.
• npx aislop hook status shows what is installed; npx aislop hook uninstall removes only aislop’s entries and leaves your hand edits alone.

The same scan catches swallowed exceptions, unsafe casts, unused imports and helpers left over from a first attempt. Details: agent hooks docs.

Step 3: block the turn if quality drops

npx aislop hook install --claude --quality-gate

Quality-gate mode records your current score as a baseline. At the end of each turn aislop runs a full scan, and if the score is below the baseline the Stop hook blocks and tells Claude why, so it keeps working until the score is back. After an intentional drop, run npx aislop hook baseline to reset it.

Clean up comments Claude already wrote

npx aislop scan
npx aislop fix
npx aislop fix --claude

aislop fix handles the safe cleanup. aislop fix --claude opens Claude Code with every remaining finding, file and line as its prompt. Then add the same check to CI with the two-minute quality gate, so a session without the hook still cannot merge slop.

The same setup for other agents: Cursor and Codex.