review-comments

Instructions

src/ 配下の TypeScript（テストを含む）を対象に、コメントの引き算（不要・過剰・陳腐化・重複）をレビューする。「コメントが付いているか」「1 行で why を書いているか」といった足し算側は review-code 2.5 の責務であり、本スキルは重複させない（責務境界を参照）。

前提となる本リポジトリのコメント規約（現行方針: 省略が既定）

コメントは省略が既定。コードから導出できない事実（why・不変条件・責務の所在・戻り値の特殊な意味）を言うときだけ 1 行で足す（review-code 2.5）。docs/DEVELOPMENT.md の「関数の目的が明確でない場合は JSDoc を追加」「複雑なロジックにはインラインコメントを追加」は、裏返せば目的が明確な関数・自明なロジックには付けないという規約である。

これらは違反ではないので指摘対象にしない:

• 非自明な why・不変条件・責務境界を 1 行で述べたコメント（例: src/domain/entities/Horse.ts:227 // 芝ダ・距離カテゴリ別の集計を会場単位に合算する。）
• 公開エントリポイント級（command の execute、ScoringOrchestrator.calculateScoresForRace）だけの @remarks による骨格説明
• 論理ブロックごとの区切りコメント（// ===== プロパティアクセサ ===== 等。ファイルの見取り図として有用）
• ファイルヘッダ 3〜5 行程度
• 定数定義に付く単位・意味の注記（src/constants/ScoringConstants.ts:31 /** 直近5戦の重み（新しいレースほど高い） */）

一方、次は削る対象:

• 関数名・getter 名・型シグネチャから自明な内容を繰り返す JSDoc（自明なら付けないのが正）
• 「コメントが付いている」こと自体は OK 根拠にならない。その 1 行がコードに無い意味を持つかで判断する

対象スコープと指摘範囲

起動時に「対象スコープ」と「対象ファイル一覧」が渡される場合がある（review-all 等からの dispatch 時）。その扱いは次の通り:

• 探索は広く、指摘は狭く: 文脈把握のための Glob/Grep はプロジェクト全体に対して行ってよい。ただしテーブルに載せる WARN/FAIL は対象ファイル一覧内の事象に限定する
• 量の増加は差分で判定する: 「増えすぎ」は base との差分（追加された + 行のコメント）で見る。取得済み diff 本文、または git diff <base>..HEAD -- <file>（base 既定は main）で追加コメント行を数える。既存債務（base 由来・本変更で未変更の冗長コメント）は WARN 以下に下げ、備考に「既存債務(本変更非起因)」と明記する
• 該当ファイル不在の項目: 評価対象が無い項目は OK として計上しない（行を省くかステータス N-A）
• 自観点の評価対象が皆無: Summary: SKIPPED を出力する
• スコープ未指定時: src/ 全体を対象にする
• 一覧に実在しないファイルがある場合: 除外して続行し、詳細所見に 1 行明記する

チェックリスト

1. 不要コメント（コードの再掲・自明）

• コメントがコードをそのまま日本語化しただけ（what の再掲）になっていないか
• getter・プロパティ・フィールドに、名前と同義の JSDoc を重ねていないか
• 自明な import / ボイラープレートにコメントが付いていないか

NG例: src/domain/entities/Horse.ts のプロパティアクセサ区画 — /** 馬ID */ get id()、/** 馬名 */ get name()、/** レース結果履歴（日付降順） */ get raceResults() が並ぶ（型と名前で完全に読める。ただし「日付降順」のようなコードに現れない不変条件は残す価値がある。残すなら 1 箇所に集約する）／ScoreComponents クラス直前の /** スコア構成要素（値オブジェクト） */ はファイルヘッダと同義 OK例: src/domain/entities/Horse.ts:237 // 会場での出走実績がない場合は中間値を返す（初出走馬対応）（既定値を選んだ理由というコードに無い意味）

2. コメント量の増えすぎ（bloat・純増）

• base 差分で、1 つの関数・ブロックに対し背景説明が多行に積み上がっていないか（why は要点数行に。長い経緯・代替案の議論はコミットメッセージへ寄せる）
• ファイルヘッダが 3〜5 行を大きく超えていないか。特に @example のコードブロックを丸ごと貼る形は、実装が変わると即座に陳腐化するため新規追加は避ける（既存: src/domain/entities/Horse.ts:1-30 は 30 行・@example 付き、src/domain/entities/Jockey.ts:1-23 も同型。いずれも既存債務）
• 追加された塊で、追加コメント行が追加コード行を上回るような不釣り合いが無いか（新規ファイルのヘッダは除外）
• 装飾（// ========== の多用、罫線の過剰、意味の無い空コメント行）が増えていないか。区切りコメントは既存の範囲（// ===== プロパティアクセサ ===== 程度）に収まっているか

3. 陳腐化・死んだコメント

• コメントアウトされた旧コード・未実装コードが残っていないか（履歴管理があるので消す）
• コードと矛盾する古いコメントが無いか（リネーム後の旧名参照、変更前の挙動説明、実際と違う戻り値説明）
• 重み・閾値の数値をコメントに書き写していないか。arima optimize-weights で SCORE_WEIGHTS が更新されると、コメント側の百分率だけが古くなる。新規に数値を書き写すのは陳腐化の作り込みとして WARN
• 理由・対応方針の無い放置 TODO/FIXME が増えていないか（理由を併記した意図的なメモは対象外）

NG例: src/domain/services/ScoringOrchestrator.ts:113-116 — // TODO: Trainerエンティティの構築は将来実装 と、その下にコメントアウトされた 3 行の旧コード（FAIL 相当。既存債務） OK例: 未実装であることを 1 行で述べ、コードは消す（必要になったら履歴から戻す）

4. 冗長・重複コメント

• 同じ説明が近接する複数箇所に重複していないか（1 箇所へ集約できないか）
• 直前のコメントで述べたことを数行後に言い換えて繰り返していないか
• 10 要素の重み配分の説明が複数ファイルに散在していないか（既存: src/constants/ScoringConstants.ts のヘッダと SCORE_WEIGHTS / src/domain/valueObjects/ScoreComponents.ts のヘッダと ScoreComponentsData のコメント / src/domain/entities/Horse.ts のヘッダ / docs/ARCHITECTURE.md。正は SCORE_WEIGHTS であり、新規に説明を増やさない）

判定基準

• FAIL: 誤読が実害になるもの（コメントアウトされた旧コードの残置、コードと矛盾する誤ったコメント）
• WARN: 不要コメント（what 再掲）・量の増えすぎ・装飾過多・冗長重複・理由なし放置 TODO・重み数値の書き写し
• OK: 問題なし。OK 行はテーブルに含めない（FAIL / WARN のみ列挙。OK は Summary のカウントにだけ反映）
• N-A: 差分スコープに当該観点の変更がない（Summary から除外）
• 既存債務の扱い: base 由来のコメント（Horse.ts の getter JSDoc 群、長いファイルヘッダ、ScoringOrchestrator の TODO 塊）は、本変更で触れていなければ WARN 以下に留め、備考に「既存債務(本変更非起因)」と明記する。本変更で同型を増やした場合のみ通常の重度で計上する

本スキルの責務境界

• 足し算側は review-code: 「コメントが付いているか」「1 行で why を書いているか」「区切りコメントで階層を見せているか」は review-code 2.5 の責務。本スキルはその過剰・不要を削る側だけを見る（足りない=review-code / 多すぎ・不要=review-comments）
• 名前の自明性（説明的な名前ならコメント不要、という判断の前提となる命名の良否）は review-naming
• 機能削除に伴う消し残し（削除済み機能への言及がドキュメント・スキーマ・CLI 定義に残る等）は review-code 2.3。ソース中のコメントそのものの過剰・陳腐化のみが本スキルの対象
• CLI 出力文字列（console.log の文言・記号）はコメントではないため対象外
• チェック表の行は本チェックリスト項目のみで構成する。項目外の気づきは「### 他観点への申し送り」へ（FAIL/WARN を付けない）
• 同一事象が複数項目に該当する場合は最も特異的な 1 項目だけで計上する。優劣が付けにくいときはチェックリスト番号の小さい方で計上する（決定論的に揃える）

レポート形式

## コメント（不要・過剰・陳腐化）レビュー結果

| # | チェック項目 | ステータス | 該当箇所 | 内容 | 推奨（削除/圧縮/修正） |
| - | ------------ | ---------- | -------- | ---- | ---------------------- |

### 詳細所見
（base 差分で追加されたコメントの過剰・不要を中心に。既存債務は「既存債務(本変更非起因)」と明記）

### 他観点への申し送り

### 推奨アクション
- HIGH: <FAIL 行を全列挙>
- MEDIUM: <WARN 行のうち量の増えすぎ・誤読寄りのもの>
- LOW: <WARN 行のうち局所的なもの>
（該当が無い優先度は「なし」と明示）

Summary 行（必須・review-all 集計用）

レポート末尾に必ず以下の 1 行を出力する:

Summary: OK=<n> WARN=<n> FAIL=<n>

• カウント単位はチェック項目（4 項目）: 指摘の無い項目は OK として計上し（テーブルには載せない）、WARN/FAIL のある項目はその最重度ステータスで 1 カウント。N-A の項目は除外。OK + WARN + FAIL = 評価した項目数になる
• レビュー対象不在時のみ Summary: SKIPPED。その場合もレポート骨格（空テーブル + 推奨アクション各「なし」）を維持し、SKIPPED の根拠を詳細所見に 1 行書く