diff --git a/CLAUDE.md b/CLAUDE.md
index 768e5e4f..66f1b934 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -277,3 +277,7 @@ The docs below own the details — this section just points at them.
 - **Pre-push lint hook** (catches tracker-tag and comment-block failures
   before CI does — install once per clone):
   `ln -sf ../../scripts/pre-push .git/hooks/pre-push`
+- **Comment/PR-description length**: size it to how non-obvious the
+  thing is, not to how much investigation it took to find it — a
+  mechanical fix gets a one-line comment, a genuinely non-obvious
+  invariant or decision earns real prose.