From 3654ce5f85fb89704494201880f7258f53b33505 Mon Sep 17 00:00:00 2001 From: etrobert-bot Date: Wed, 1 Jul 2026 13:17:54 +0200 Subject: [PATCH] docs(claude): add the deletion test for code comments Sharpen the comment-proportionality rule with an applyable test: cut a comment if it only restates what the code, filename, or option names already convey, and don't narrate where or how code is wired up (that's greppable, rots, and belongs in the PR). The existing rule was framed around length and historical narrative, which let restate-the-code and describe-the-wiring comments slip through. Co-Authored-By: Claude Opus 4.8 --- pkgs/claude-code-wrapped/config/CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pkgs/claude-code-wrapped/config/CLAUDE.md b/pkgs/claude-code-wrapped/config/CLAUDE.md index 142baa59..900b1f78 100644 --- a/pkgs/claude-code-wrapped/config/CLAUDE.md +++ b/pkgs/claude-code-wrapped/config/CLAUDE.md @@ -130,6 +130,10 @@ point — the gotcha or "why" — and leave narrative context (root-cause chains incident history) for the commit or PR. A two-line change rarely needs more than a two-line comment. +Apply the deletion test: if a comment only restates what the code, filename, or +option names already convey, cut it. Don't describe how or where code is wired +up (e.g. which hosts import a module). + ## Testing Before committing, verify the change: typecheck, lint, and run the relevant