コメント精査

前提

AIはコード内コメントを疑わずに読み、設計書やFigmaより優先して実装の根拠にする。 そのためコメントの嘘・推測・感想は、そのまま誤った実装を生む。

コメントは lint も型チェックもテストも通らないため、**コードベース内で唯一「検証されない仕様書」**になっている。 このスキルはその検証を担う。

重大度の定義（すべての判断の基準）:

• error = AIが根拠として採用すると、誤った実装を生むもの（嘘・推測・感想・いずれ陳腐化する情報・根拠不明の主張）
• warning = 採用されても害はないが、読むコストだけかかるもの

→ 詳細は references/severity.md

3層構成

A→B→C の順で、安い工程から実行する。 Bで人間がコメントを確定させると、コメントが「AIの推測」から「承認された意図」に変わり、Cの検証基準として使えるようになる。

用途別の入口

コメントを書く／実装する

references/comment-rules.md を読み、残してよいコメントの条件に従う。 プロジェクトの CLAUDE.md / AGENTS.md に規約を入れる場合は assets/agent-rules.md を貼る。

コミット前に機械チェックする

前提: 対象リポジトリの scripts/comment-lint.mjs に実体が配置されていること。 未配置なら README.md の「導入手順 2」に従ってコピーする。

cp <このスキル>/scripts/comment-lint.mjs scripts/comment-lint.mjs

一度きりの確認で配置したくない場合は、このスキルの scripts/comment-lint.mjs を 直接指して実行してもよい（設定ファイルはカレントディレクトリから読む）。

node scripts/comment-lint.mjs                  # ステージ済み差分
node scripts/comment-lint.mjs --all            # 追跡中の全ファイル
node scripts/comment-lint.mjs --base <ref>     # <ref> からの差分（CI向け）
node scripts/comment-lint.mjs --json           # JSON出力

終了コードは error があれば 1、設定ファイルが不正なら 2。

重大度と検査対象はリポジトリ直下の comment-lint.config.json で調整する（無ければ既定値）。 正当なコメントにも一致する4ルールは既定が warning なので、error に引き上げる前に --all で件数を確認する。

ルールの一覧・設定キー・拡張方法・機械では判定できない範囲は references/lint-rules.md。

コメントと実装の一致を検証する（このスキルの中核）

references/consistency-check.md の手順に従う。

要点のみ:

1. コメントを「正しい説明」ではなく検証すべき主張として扱う
2. 信頼順位は 上位ソース（設計書・Figma・チケット） > 確認済みコメント > 実装 > 未確認コメント
3. 報告だけを行う。コメントもコードも修正しない。どちらが正しいかは人間が決める
4. 未確認コメントを根拠に「実装が誤り」と判定してはいけない。上位ソースがない矛盾は「判断不能」とする

人間がレビューする

references/review-checklist.md のチェックリストを使う。PRテンプレートにも転記できる。

このスキルがやらないこと

• コメント・コードの修正（判断は人間に返す）
• ロジック・設計・パフォーマンス・命名のレビュー（層Cの役割）
• 引用先の実在確認のうち外部API依存のもの（チケットの状態、Figmaのnode-id有効性）はCI側で行う