📝 docs: 超過は長さでなく本数だった — 測定ツールとゲート3案の反証

[tyabu12]

Summary

• rules/knowledge-layering.md に § "Anti-pattern: a comment written for the reviewer" を追加（常時ロード）。誤配置の発火条件に加え、書く側の手順を持つ
• docs/claim-verification.md に同名の depth 節。測定値・反例・反証した機構はここに置く
• scripts/comment-density.py（新規）。コホート単位の測定ツール。ゲートは積んでいない — 3設計を較正して全部落ちたため

診断が2回訂正された

これがこの PR の本体。

1回目（#35）: 「Opus 5 でコメントが冗長」の主因は C クラス（レビュアー宛て）の増加だと結論していたが、最初のサンプルがダークモード/WCAG 系の測定作業に偏っていて題材と世代が交絡していた。取り直すと分類分布は不変で、残るのは長さだけだった。

2回目（この PR）: その「長さ」も主成分ではなかった。測定ツールを書いてコホートを取り直した結果:

	Opus 4.8 (n=124)	Opus 5 (n=25)	差
ブロック/コミット	16	26	+63%
行/ブロック	4.3	5.9	+37%
ブロック長の中央値	3.0	3.0	同一
コメント比	43.0%	55.5%	—

超過は「長いブロックを書く」より「ブロックを多く書く」に出ている。 中央値は一致していて差は裾にしかない。長さを鍵にした機構は欠陥の小さい方の半分しか狙えないので、rule の執筆手順は count を先に見る形にした。

Fable 5 は両コホートより簡潔（3.4行/ブロック、32.1%）。軸は世代ではなくモデルなので、rule の "current models" という括りは単位が誤りだった。

なお rule をブロック単位に限定した根拠（時制で判別する案が169ブロック中17件の判定を要して4件誤答、A ブロック全体の約7%に誤爆）は #35 の通りで、この PR でも変えていない。

ゲートを3設計とも落とした

「新規コードは比率を上げない」の reframe 型で検出器を積む予定だった。簡潔な世代（Opus 4.8）を陰性対照に較正して、全部落ちた:

設計	冗長世代の検出	簡潔世代の誤爆
コミット単位・いずれかの閾値超過	80-96%	52-79%
コミット単位・両方超過	32-48%	12-22%
ブロック単位（≥12行）	11.4%	7.8%

中央値は分離するのに、コミット単位のばらつきがそれを飲み込む。ブロック単位は中央値自体が一致していて分離しない。この誤爆率のゲートは読み手に無視を教えるだけなので、ツールは測定専用として出荷した。数値は docstring と docs 側に残してある — 次に再構築を試みる人が同じ実験を回さずに済むように。--dump で再実行できる。

計器のバグ

較正の初回は commit_stats が @@ ハンクヘッダでブロックをリセットしておらず、--unified=0 では非隣接ハンクのコメントが1ブロックに融合していた。行/ブロックが 4.8 → 7.7 と出て、長さの寄与を過大評価していた。上の表はすべて修正後の値。

この形の欠陥はコホート集計には現れない（合計は変わらず分割だけ壊れる）ので、--self-test に既知 diff の fixture を5件積んだ。負の対照として修正前コードに当て、当該ケースのみ [2,2] 期待に対し [4] を返すことを確認済み。

書く側の手順は仮説として出荷

節の当初版には書き手宛ての命令が1つも無く、レビュー時の指摘しか変えられない形だった。挙動記録がそれを実証している — 規則が常時ロードされた状態で3連続の冗長出力、いずれも外部からの指摘後にのみ修正。

なので rule に手順を置いた。ただし効くという証拠は無い。効いたのは live な構造指示であって常時ロード文ではないので、docs 側に仮説である旨と成功判定（blocks/commit がコホートの 16 に向かうか、A/B/C/D 分布は不変か）を明記し、動かなければ常時ロード分を引き剥がすと書いた。

Test plan

• python3 scripts/comment-density.py --self-test → PASS (5/5)。修正前コードでは当該1件が赤（負の対照確認済み）
• bash scripts/scrub-check.sh → PASS。コーパスの実体名・絶対パスは kit 側に入っていない
• 相互参照アンカーを両方向 grep で検証（各1件）
• 節を 420 → 313語に圧縮。この PR 自身が長さの defect を扱うので、文書側も同じ規律に従わせた

既知の隙間

• 較正の数値は 📝 docs: コメントは長さが世代差、C クラス（レビュアー宛て）は題材差だった #35 に無い（セッション由来）。docs 側にその旨を明記してあるが、恒久的な置き場が要るなら 📝 docs: コメントは長さが世代差、C クラス（レビュアー宛て）は題材差だった #35 にコメントを1本足すのが安い
• ツールは A/B/C/D 分布を測れない。成功判定の分類側は手作業のまま

Closes #35

🤖 Generated with Claude Code

https://claude.ai/code/session_01EXUZckBU1oD6hMoVCdy6iQ

[tyabu12]

⚠️ このPRの見出し主張「超過は長さでなく本数」は #37 で撤回した。

16 → 26 blocks/commit (+63%) は、単位の大きさが違うコホート同士を生の per-commit カウントで比べた結果だった。冗長側のコミットは追加コード行が 108 → 179 と大きく、その差をコメント習慣として計上していた。

100 追加コード行あたりで正規化すると 本数 +31% / 長さ +32% でほぼ同率、どちらも支配的ではない。

このPRで有効なまま残るもの: ゲート3設計の反証、ブロック長の中央値が両コホートとも 3.0、Fable 5 が最も簡潔（ただし本文中の生の blocks/commit だけは逆を示していた）。