code-review

コードレビューのスキル

概要

git diff を使った構造化コードレビューです。変更内容の正確性、セキュリティ、複雑さ、保守性、言語固有のベストプラクティスを分析し、結果を Markdown レポートと自己完結型のインタラクティブな HTML レポートとして保存します。これは diff-summary および diff-viewer と同じ成果物パターンです。

HTML レポートはバイリンガル（韓国語＋英語、ページ全体の言語切り替え機能付き。デフォルトでは韓国語を表示）で、重要度バッジ、ライト／ダーク／自動テーマと 8 種類のコード配色を選べる構文ハイライト、折りたたみとサイズ変更が可能なコンパクトなサイドバー、指摘ごとの「Copy Markdown」、ブラウザーに保存される指摘ごとのコメント、レビューを調整する再生成用ペイロードを出力する「Copy feedback」ボタンが含まれます。

基本原則： 差分を入力し、重要度タグ付きの指摘を出力します。対象は変更箇所に厳密に限定します。

コマンド

コマンド	スキル	出力	使用する状況
/code-review [scope]（または暗黙のトリガー）	code-review	.reviews/ に Markdown レポートとバイリンガル HTML を保存し、ブラウザーで開きます	デフォルトのレビュー
/code-review-md [scope]	code-review-md	.reviews/<date>_<sha>.md に Markdown ファイルを保存します（HTML なし）	Markdown のみの記録を作成し、git 経由で共有する場合

コマンドの使用例

/code-review — Markdown ＋ HTML

User: /code-review review PR #42
→ gh pr diff 42
→ diff_stats.py reports has_security_sensitive_files: true
→ Load python.md + common-vulnerabilities.md
→ Analyze; find SQL injection (CRITICAL)
→ Write .reviews/2026-05-03_a1b2c3d.md      (Korean, **Language:** ko)
→ Write .reviews/2026-05-03_a1b2c3d.en.md   (English, same IDs/structure)
→ python <skill-path>/scripts/generate_html_report.py .reviews/2026-05-03_a1b2c3d.md
→ open .reviews/2026-05-03_a1b2c3d.html     (Korean shown by default; toggle to English)
→ Report finding counts, risk, artifact paths, fresh verification, and browser-open result

User: 마지막 커밋 코드 리뷰해줘
→ git diff HEAD~1..HEAD
→ Analyze; write the Korean report and its English sibling
→ Generate + open the bilingual HTML report
→ Report finding counts, risk, artifact paths, fresh verification, and browser-open result

/code-review-md — Markdown のみ

User: /code-review-md review staged changes
→ git diff --staged
→ Analyze
→ mkdir -p .reviews/
→ Write .reviews/2026-05-03_staged.md
→ Report finding counts, risk, report path, and fresh verification
→ If `.reviews/` is not ignored, suggest adding it to .gitignore (do NOT modify it)

レビュー範囲の判断

ユーザーのリクエストを解析してレビュー対象のコードを判断し、対応する git コマンドを実行します。

ユーザーの意図	Git コマンド
「変更をレビューして」／範囲の指定なし	git diff（ステージングされていない変更）＋ git diff --staged（ステージング済みの変更）
「ステージング済みの変更をレビューして」	git diff --staged
「直近のコミットをレビューして」	git diff HEAD~1..HEAD
「コミット <sha> をレビューして」	git diff <sha>~1..<sha>
「直近の N 件のコミットをレビューして」	git diff HEAD~N..HEAD
「ブランチ X をレビューして」／「main と比較して」	git diff main...<branch>（三点ドットのマージベース）
「PR #N をレビューして」	gh pr diff N

ユーザーの意図が曖昧な場合は、ステージング済みとステージングされていない変更をレビューします。変更がまったくない場合は、そのことをユーザーに伝え、考えられる原因（ステージングを忘れた、ブランチが違うなど）を提示します。

レポートのファイル名に使う短縮 SHA を取得します。

• 特定のコミットの場合：そのコミットの短縮 SHA を使います
• 範囲の場合：最新のコミットの短縮 SHA を使います
• コミットのないステージング済み／ステージングされていない変更の場合：staged または working を使います

レビュープロセス

次の手順に沿って進めます。

1. コンテキストを収集する

適切な git diff コマンドを実行します。次に、差分統計ヘルパーを実行して、機械可読な概要を取得します。

git diff [range] --numstat | python <skill-path>/scripts/diff_stats.py

このコマンドは、変更されたファイル、検出された言語、セキュリティ上重要なファイルに変更があったかどうかを含む JSON を出力します。

2. 参照資料を読み込む

diff_stats.py で検出された言語に応じて、該当する参照ファイルを読み込みます。必要なものだけを読み込み、一度にすべて読み込まないでください。

• .py ファイル → references/python.md を読み込みます
• .js、.ts、.jsx、.tsx ファイル → references/javascript-typescript.md を読み込みます
• .go ファイル → references/go.md を読み込みます（存在する場合）
• .rs ファイル → references/rust.md を読み込みます（存在する場合）
• .java、.kt ファイル → references/java.md を読み込みます（存在する場合）

レビューのフレームワークと重要度の定義については、必ず references/review-criteria.md を読み込みます。

diff_stats.py が has_security_sensitive_files: true を報告した場合は、references/common-vulnerabilities.md も読み込みます。

3. 差分を分析する

変更された各ファイルの差分を読み、次の5つの観点で分析します。

1. 正確性 — コードは作成者の意図どおりに動作しますか？ ロジックエラー、エッジケース、型の不一致、エラー処理の不足を確認します。
2. セキュリティ — インジェクションのリスク、認証の不備、機密データの露出、安全でない暗号化、入力検証を確認します。
3. 複雑さと一貫性 — 認知負荷が増していませんか？ 既存のパターンや命名規則を崩していませんか？
4. 保守性 — 将来の開発者が理解できますか？ 密結合、公開 API のドキュメント不足、マジックナンバー、テスト容易性を確認します。
5. ベストプラクティス — 言語やフレームワーク固有のイディオムとアンチパターンを確認します（読み込まれた参照ファイルに基づきます）。

各指摘には重大度を割り当てます。

重大度	意味	必要な対応
CRITICAL	データ損失、セキュリティ侵害、本番環境でのクラッシュ	マージ前に必ず修正
HIGH	バグ、脆弱性、または重大な設計上の欠陥	マージ前に修正することを推奨
MEDIUM	コードの臭い、不整合、中程度のリスク	修正を推奨
LOW	スタイル、命名、軽微な改善	できれば修正
INFO	レビュー判断に実質的な影響を与える確認済みの状況。ただし、コード変更は不要	対応不要

不確実さや称賛だけを理由に INFO を使ってはいけません。証拠が不足している場合、それによって重大度や対応が変わる場合に限り、特定の Open Questions 項目を1つ設けて記載します。それ以外の場合は記載しません。

すべての指摘のタイトルには安定した ID が必要です：#### [CR-001] ...、[CR-002] など。HTML レポートではこの ID をキーに指摘ごとのコメントを対応付けるため、同じ指摘には両方の言語ファイルで同じ IDを付けてください（Report Language を参照）。ID は英語のままにし、言語ファイル間で番号を振り直してはいけません。

証拠を優先する記述ルール

このルールは Markdown と HTML のレビューに適用されます。

• 対応が必要な指摘は、必ず次の順に記載します：確認された動作 → 実際に起こり得る影響 → 根拠に見合った最小限の修正。
• 主張する前に、変更されたパスと行を示し、証拠として必要な最小限の抜粋だけを引用します。
• 確認済みの事実は明確に述べます。重大な推論には Inference: を付け、引用した証拠との関連を示します。
• 記述は証拠に見合った分量にします。コードの言い換え、結論の繰り返し、根拠のない INFO 項目、「堅牢」「優れている」「整理されている」「よく構成されている」などの一般的な称賛を加えてはいけません。
• 対応が必要な指摘がない場合は、その旨を明記し、重大な残存リスクや検証上の不足のみを記載します。
• どちらの出力モードでも、冒頭の告知、一般的な前置き、祝辞、全体的な品質に関する評価を加えてはいけません。

保存レポートモード（/code-review と /code-review-md）

• レポートはタイトルとパーサーが解釈するメタデータから始め、その後に指摘を記載します。
• 生成後の引き継ぎは事実のみとし、重大度ごとの指摘数、全体的なリスク、生成された成果物のパス、新たに実施した検証、HTML のブラウザー表示結果または警告を記載します。
• レポートの記述を繰り返したり、指摘数を固定して約束したりしてはいけません。
• 永続化された成果物が生成され、.reviews/ が無視対象になっていない場合に限り、引き継ぎに .reviews/ を無視対象に追加する提案を含められます。

4. Markdown レポートを作成する

リポジトリのルートに .reviews/ ディレクトリがなければ作成します。以下の最小限のレポート形式を使用し、該当する指摘が0件の重大度見出しは省略します。

# Code Review Report

**Date:** YYYY-MM-DD
**Reviewer:** automated review
**Scope:** [e.g., "Staged changes", "Commits a1b2c3d..f4e5d6a on branch feature-auth"]
**Repository:** [repo name]
**Language:** en
**Risk:** LOW / MEDIUM / HIGH / CRITICAL
**Findings:** N critical, N high, N medium, N low, N info

## Findings

### HIGH

#### [CR-001] Short title describing the finding
**File:** `path/to/file.py` (lines 42-58)
**Category:** Security | Correctness | Complexity | Maintainability | Best Practice

**Evidence excerpt:**
\```python
# smallest excerpt needed to support the claim
\```

**Observed behavior:** [What the changed code demonstrably does.]
**Practical consequence:** [The concrete failure mode, risk, or maintenance cost.]
**Smallest justified correction:** [The narrowest change supported by the evidence.]

条件付きセクション

• Decision Summary： 複数箇所にまたがるリスクについて、繰り返しを避けた判断を1つ示す必要がある場合にのみ含めます。
• Positive Observations： 具体的な証拠に基づくパターンがリスクやレビュー作業を軽減する場合にのみ含めます。
• Open Questions： 証拠の不足によって重大度や対応が変わる場合にのみ含め、その不足に関する具体的な項目を1つだけ記載します。
• File Summary： 指摘を繰り返さずに読み手の移動を助ける場合にのみ含めます。

内容のない記述、空の見出し、指摘ですでに述べられている結論は省略します。

保存先：.reviews/<YYYY-MM-DD>_<short-sha>.md

5. HTML を生成する（デフォルト。/code-review-md の場合はスキップ）

/code-review および暗黙のトリガーではデフォルトで実行します。code-review-md スキル／/code-review-md 経由で呼び出された場合に限り、この手順をスキップします。HTML レポートはバイリンガルです。韓国語のレポートと英語のレポートを作成し（「レポートの言語」を参照）、1 つの HTML ファイルに統合します。

ファイル名 — 韓国語のレポートをメインとし、同一の構成（同じ指摘 ID、同じコードブロック）を持つ .en.md の対になるファイルを用意します。

.reviews/<YYYY-MM-DD>_<short-sha>.md      # Korean (main)
.reviews/<YYYY-MM-DD>_<short-sha>.en.md   # English

メインファイルに対してジェネレーターを実行します。.en.md の対になるファイルは自動検出され、単一の自己完結型 HTML が出力されます。

python <skill-path>/scripts/generate_html_report.py .reviews/<report>.md
open .reviews/<report>.html

HTML には、ページ全体の言語切り替え（デフォルトでは韓国語を表示）、ライト／ダーク／自動のテーマとコード構文配色のセレクター、折りたたみ可能なコンパクトなサイドバー、指摘ごとの「Markdown をコピー」、指摘ごとのコメント（ブラウザーに保存）、および「フィードバックをコピー」ボタンが含まれます。このボタンは再生成用のペイロードを作成します。これを新しい /code-review の実行に貼り付けると、レビュー担当者のコメントを反映してレビューを修正できます。

言語ファイルが 1 つしかない場合もジェネレーターは動作し、言語切り替えは非表示になります（単一言語のフォールバック）。翻訳を明示的に指定するには --alt <path> を渡します。デフォルトを変更するには --theme／--code-scheme を渡します。

6. 出力モードに応じて完了する

• Markdown + HTML（/code-review）： ブラウザーで開いた結果または警告を含め、上記の事実のみを記載する引き継ぎを適用します。追加が許可されるのは、条件に該当する場合の .reviews/ の ignore 提案のみです。
• Markdown のみ（/code-review-md）： HTML 成果物やブラウザーで開いた事実を含めず、同じ事実のみを記載する引き継ぎを適用します。

レポートの言語

ユーザーのプロンプトと同じ言語でレポートを作成します。ユーザーが韓国語で書いた場合、レポートは韓国語にします。英語で書いた場合は英語にします。言語が判別できない場合は、デフォルトで英語にします。

適宜、説明的な見出し、指摘の説明、条件付きの文章、表の見出しや値を翻訳します。

パーサーで重要な次のメタデータキーは、英語のまま正確に維持します：Date、Reviewer、Scope、Repository、Language。値は適宜翻訳し、韓国語のレポートでは **Language:** ko と設定します。

常に英語のままにするもの：

• パーサーで重要なメタデータキー：Date、Reviewer、Scope、Repository、Language
• 指摘 ID：CR-001、CR-002 など
• 重大度ラベル：CRITICAL、HIGH、MEDIUM、LOW、INFO
• コードスニペット（コードはコードです）
• ファイルパスと技術識別子

HTML ジェネレーターが正しい lang 属性を設定できるよう、レポートのメタデータヘッダーに **Language:** フィールドを追加します。

**Language:** ko

BCP 47 言語タグを使用します：en、ko、ja、zh など。

バイリンガル HTML レポート（/code-review）

HTML レポートはデフォルトでバイリンガルです。読者が言語を切り替えられるよう、韓国語と英語のレポートを作成します。デフォルトでは韓国語を表示します。

• 構成が同一のファイルを 2 つ作成します — 見出し、指摘 ID（[CR-001] など）、コードブロックを同一にします。翻訳するのは説明文（タイトル、説明、要約、表のラベル）のみです。コード、ID、ファイルパス、重大度ラベルは共通のまま変更しません。
• 各ファイルに **Language:** ヘッダーを設定します（メインファイルは ko、.en.md は en）。
• メインファイルには <YYYY-MM-DD>_<short-sha>.md という名前を付け、翻訳ファイルには言語サフィックス（.en.md）を追加します。
• HTML 内の指摘ごとのコメントは指摘 ID に関連付けられます。両方のファイルで ID を揃えることで、読者が言語を切り替えてもコメントを同じ指摘に紐づけたままにできます。

ユーザーが単一言語を明示的に指定した場合は、その言語のファイルのみを作成します。ジェネレーターは言語切り替えのない単一言語レポートにフォールバックします。

クイックリファレンス

ファイル名の規則：

• コミットベース：.reviews/2026-04-08_a1b2c3d.md
• ステージ済み：.reviews/2026-04-08_staged.md
• 作業ツリー：.reviews/2026-04-08_working.md

レポートの言語： 本文はユーザーのプロンプトの言語に合わせます。メタデータキーの Date、Reviewer、Scope、Repository、Language は英語のままにします。指摘 ID（CR-001）、重大度ラベル、コード、ファイルパスも英語のままにします。HTML ジェネレーターが正しい lang を設定できるよう、**Language:** <bcp47> を追加します。

大規模な差分（1000 行超）： CRITICAL／HIGH に重点を置きます。類似する MEDIUM／LOW の指摘は、個別に列挙するのではなく、「未使用のインポートが 12 件」のようにパターン別にまとめます。

よくある間違い

場所を示さない一般的な指摘

• 問題： ファイルや行を示さずに「エラーハンドリングの追加を検討してください」と述べる
• 修正： すべての指摘でファイルと行範囲を示し、現在のコードを提示して修正を提案します

変更されていないコードのレビュー

• 問題： 差分の範囲外のコードにコメントする
• 修正： 対象は差分です。リポジトリ全体に範囲を広げないでください。

些細な差分に対する指摘の捏造

• 問題： 空白やバージョン更新だけの差分に問題をでっち上げる
• 修正： 指摘がないことを確認できた場合は、その結果をそのまま述べます。水増しはしないでください。

すべての参照ファイルを読み込む

• 問題： 差分が JavaScript のみなのに python.md を読む
• 修正： diff_stats.py が報告した言語の参照ファイルだけを読み込みます

誤検知を事実として述べる

• 問題： 確認できないのに「これはバグです」と述べる
• 修正： 不足している証拠によって重大度や対応が変わる場合は、Open Questions に具体的な質問を 1 つ記載します。それ以外の場合は、その主張を省きます。

一般的な称賛を指摘として挙げる

• 問題： レビューの判断を変えない称賛で注意をそらす
• 修正： リスクやレビューの労力を具体的なパターンが明確に軽減すると示せる場合を除き、省きます。

注意事項

決して行わないこと：

• /code-review-md の HTML レポートを生成する（Markdown のみ）
• .gitignore を自動で変更する（適用せず、提案する）
• 差分の範囲外のコードにコメントする
• 指摘を水増しする
• 根拠の代わりに INFO を使う

必ず行うこと：

• すべての指摘でファイルと行範囲を示す
• 必要最小限の証拠のみを引用し、正当化できる最小限の修正を提案する
• 本文の言語をユーザーのプロンプトに合わせる
• 永続化するレポートでは、パーサーにとって重要なメタデータキーを英語のままにする

統合

連携先：

• git-commit — 最終的な品質チェックとして、コミット前にレビューします
• プラグインコマンドから起動します。任意の git diff の出力を対象とするため、git の履歴があるすべてのリポジトリで動作します