code-review:review-local-changes

ローカル変更のレビュー手順

ローカルの未コミット変更を徹底的に評価する、経験豊富なコードレビュアーとして作業してください。レビューは体系的に進め、改善案を含む実行可能なフィードバックを提示してください。

ユーザー入力：

$ARGUMENTS

重要：特に依頼された場合を除き、spec/ フォルダーと reports/ フォルダー内の変更はレビューしないでください。

---

コマンド引数

$ARGUMENTS から次の引数を解析してください。

引数の定義

引数	形式	デフォルト	説明
review-aspects	自由形式のテキスト	なし	レビューに関する任意の観点や重点領域です（例：「セキュリティ、パフォーマンス」）
--min-impact	--min-impact <level>	high	報告する問題の最低影響度です。値：critical、high、medium、medium-low、low
--json	フラグ	false	Markdown ではなく JSON 形式で結果を出力します

フラグの組み合わせ

--min-impact と --json を同時に使用した場合、--min-impact は JSON 出力に含める問題をフィルタリングします。たとえば、--min-impact medium --json は、影響スコアが 41 以上の問題のみを JSON 形式で出力します。--json フラグは出力形式のみを制御し、フィルタリングには影響しません。--min-impact フラグはフィルタリングのみを制御し、出力形式にかかわらず同じように機能します。

使用例

# Review all local changes with default settings (min-impact: high, markdown output)
/review-local-changes

# Focus on security and performance, lower the threshold to medium
/review-local-changes security, performance --min-impact medium

# Critical-only issues in JSON for programmatic consumption
/review-local-changes --min-impact critical --json

影響度レベルの対応

レベル	影響スコアの範囲
critical	81-100
high	61-80
medium	41-60
medium-low	21-40
low	0-20

設定の解決

$ARGUMENTS を解析し、次のように設定を解決してください。

# Extract review aspects (free text, everything that is not a flag)
REVIEW_ASPECTS = all non-flag text from $ARGUMENTS

# Parse flags
MIN_IMPACT = --min-impact || "high"
JSON_OUTPUT = --json flag present (true/false)

# Resolve minimum impact score from level name
MIN_IMPACT_SCORE = lookup MIN_IMPACT in Impact Level Mapping:
  "critical"   -> 81
  "high"       -> 61
  "medium"     -> 41
  "medium-low" -> 21
  "low"        -> 0

レビューワークフロー

それぞれ異なるコード品質の観点を担当する、複数の専門エージェントを使用して、ローカルの未コミット変更を包括的にコードレビューしてください。以下の手順を正確に実行してください。

フェーズ 1：準備

次のコマンドを順番に実行してください。

1. レビュー対象の特定

   • 変更内容を把握するために次のコマンドを確認します。変更された行数を返すコマンドのみを使用し、ファイル内容は表示しないでください。
     • git status --short
     • git diff --stat（ステージされていない変更）
     • git diff --cached --stat（ステージされた変更）
     • git diff --name-only
     • git diff --cached --name-only
   • ステージ済みと未ステージの変更：ステージ済み（git diff --cached）と未ステージ（git diff）の変更を区別してください。デフォルトでは両方をレビューします。問題を報告する際は、該当する変更がステージ済みか未ステージかを明記し、コミット可能な変更と作業中の変更がユーザーにわかるようにしてください。
   • 上記の「コマンド引数」セクションに従って $ARGUMENTS を解析し、REVIEW_ASPECTS、MIN_IMPACT、MIN_IMPACT_SCORE、JSON_OUTPUT を解決してください。
   • 変更がない場合はユーザーに知らせて終了してください。

2. 最大 6 つの Haiku エージェントを並列で起動し、次のタスクを実行します。

   • 該当するエージェント指示ファイルがあれば、そのファイルパスの一覧（内容は含めない）を検索して提示するエージェントを 1 つ起動します。対象は、CLAUDE.md、AGENTS.md、**/constitution.md、ルートの README.md、および変更されたファイルがあるディレクトリ内の README.md です。

   • 変更行数に基づいて変更ファイルを残りの 1～5 つのエージェントに振り分け、次のように依頼します。

     GOAL: 次のファイルのローカル未コミット変更を分析し、要約してください
     
     次の手順を実行してください。
        - `git diff -- [list of files]` と `git diff --cached -- [list of files]` を実行し、ステージされていない変更とステージされた変更の両方を確認する
        - 次のファイルを分析する：[list of files]
     
     各ファイルの変更内容を詳細に要約してください。変更の種類、影響を受けるクラス／関数／変数など、複雑さ、変更の全体的な説明を含めてください。各ファイルについて、変更がステージ済み、未ステージ、または両方のいずれかを明記してください。
     

フェーズ 2：問題点と改善点の調査

適用するレビューを判断し、最大 6 つの並列エージェント（Sonnet または Opus）を起動して、ローカルのすべての変更を個別にコードレビューします。各エージェントは以下を行い、問題点の一覧と、各問題が指摘された理由（例：CLAUDE.md または constitution.md への準拠、バグ、Git の履歴的なコンテキストなど）を返します。

注：code-quality-reviewer エージェントは、具体例と理由を示したコードの改善および簡略化の提案も行います。

利用可能なレビューエージェント：

• security-auditor - コードのセキュリティ脆弱性を分析します
• bug-hunter - サイレントな失敗を含め、バグや問題点を調査します
• code-quality-reviewer - プロジェクトのガイドライン、保守性、品質全般についてコードレビューを行います。明瞭さと保守性を高めるためにコードを簡略化します
• contracts-reviewer - 型設計と不変条件（新しい型が追加された場合）、API の変更、データモデリングなど、コードのコントラクトを分析します
• test-coverage-reviewer - テストカバレッジの品質と網羅性をレビューします
• historical-context-reviewer - 変更されたコードの git blame と履歴、対象ファイルに関わった過去のコミットなど、コードの履歴的なコンテキストをレビューします。

注：デフォルトでは、適用可能なすべてのレビューエージェントを実行します。

適用するレビューの判断

フェーズ 1 の変更概要とその複雑さに基づいて、適用するレビューエージェントを判断します。

• 純粋に見た目だけの変更を除く、コードまたは設定の変更の場合：bug-hunter、security-auditor
• ビジネスロジックやインフラストラクチャロジック、フォーマットなど、コードの変更がある場合：code-quality-reviewer（品質全般）
• コードまたはテストファイルに変更がある場合：test-coverage-reviewer
• 型、API、データモデリングに変更がある場合：contracts-reviewer
• 変更の複雑さが高い場合、または履歴的なコンテキストが必要な場合：historical-context-reviewer

レビューエージェントの起動

並列アプローチ：

• すべてのエージェントを同時に起動します
• 変更されたファイルの完全な一覧と変更概要をコンテキストとして渡し、レビュー対象となるローカルの変更内容を明示します。また、README.md、CLAUDE.md、constitution.md が存在する場合はそれらを含め、プロジェクトのガイドラインと規約が記載されたファイルの一覧も渡します。
• 結果はまとめて返します

フェーズ 3：確信度と影響度のスコアリング

このフェーズでは、上記のコマンド引数の「Configuration Resolution」ブロックで解決された MIN_IMPACT_SCORE を使用します（デフォルト：high の場合は 61）。

1. フェーズ 2 で見つかった各問題について、変更内容、問題の説明、および CLAUDE.md ファイルの一覧（手順 2 のもの）を受け取り、2 つのスコアを返す Haiku エージェントを並列で起動します。

   確信度スコア（0～100） - その問題が誤検知ではなく、実際の問題であることへの確信度：

   a. 0：まったく確信がありません。軽く精査するだけで成立しない、または既存の問題である誤検知です。 b. 25：ある程度の確信があります。実際の問題かもしれませんが、誤検知の可能性もあります。エージェントは、それが実際の問題であることを確認できませんでした。スタイル上の問題の場合は、該当する CLAUDE.md で明示的に指摘されていないものです。 c. 50：中程度の確信があります。エージェントは実際の問題であることを確認できましたが、細かな指摘であるか、実際にはあまり起きない可能性があります。ほかの変更と比べると、重要度は高くありません。 d. 75：高い確信があります。エージェントは問題を再確認し、実際に発生する可能性が非常に高いことを確認しました。変更における既存のアプローチでは不十分です。コードの機能に直接影響する非常に重要な問題であるか、該当する CLAUDE.md で直接言及されている問題です。 e. 100：絶対的な確信があります。エージェントは問題を再確認し、実際の問題であり、実際に頻繁に発生することを確認しました。証拠がそれを直接裏付けています。

   影響度スコア（0～100） - 修正されなかった場合の問題の重大度と影響： a. 0〜20（低）: 軽微なコードスメルまたはスタイルの不一致。機能や保守性に大きな影響はありません。 b. 21〜40（中低）: 保守性や可読性を損なう可能性のあるコード品質の問題ですが、機能的な影響はありません。 c. 41〜60（中）: エッジケースでエラーを引き起こしたり、パフォーマンスを低下させたり、将来の変更を困難にしたりします。 d. 61〜80（高）: 主要な機能を壊したり、通常の使用でデータを破損したり、重大な技術的負債を生み出したりします。 e. 81〜100（重大）: 実行時エラー、データ損失、システムクラッシュ、セキュリティ侵害、または機能の完全な失敗を引き起こします。

   CLAUDE.md の指示に起因してフラグが立てられた問題については、エージェントは CLAUDE.md が実際にその問題を具体的に指摘していることを再確認する必要があります。

2. 以下の段階的しきい値表を使用して問題をフィルタリングする - 影響度の高い問題ほど、通過するために必要な信頼度が低くなります:

   影響スコア	必要な最小信頼度	根拠
   81〜100（重大）	50	重大な問題は、中程度の信頼度であっても調査する価値があります
   61〜80（高）	65	影響度の高い問題は、誤検知を避けるために十分な信頼度が必要です
   41〜60（中）	75	中程度の問題は、対処することを正当化するために高い信頼度が必要です
   21〜40（中低）	85	中低の影響度の問題は、非常に高い信頼度が必要です
   0〜20（低）	95	軽微な問題は、ほぼ確実な場合にのみ含めます

   それぞれの影響レベルに対する最小信頼度しきい値を満たさない問題はすべて除外してください。 この基準を満たす問題がない場合は、先に進まないでください。

   重要: 以下を報告しないでください:

   • 設定された MIN_IMPACT レベルを下回る問題 - 影響スコアが MIN_IMPACT_SCORE（--min-impact 引数から解決され、デフォルト: high / 61）を下回る問題はすべて除外する必要があります。
   • 信頼度の低い問題 - その影響レベルに対する最小信頼度しきい値を下回る問題は、完全に除外する必要があります。

   フィルターの適用順序: 両方のフィルターを順番に適用します。問題が含まれるには、両方の条件を満たす必要があります:

   1. 最小影響カットオフ（最初に適用）: 影響スコアが MIN_IMPACT_SCORE（上記の「コマンド引数」セクションの --min-impact 引数から解決され、デフォルト: high / 61）を下回る問題を除外します。
   2. 段階的信頼度しきい値（2番目に適用）: 残った問題について、信頼度スコアがその影響レベルに必要な最小値を下回るものを除外します（上記の段階的しきい値表から）。

   具体例: --min-impact medium（MIN_IMPACT_SCORE = 41）の場合、影響度 45（中）で信頼度 70 の問題を考えます。ステップ 1 は通過します: 45 >= 41。ステップ 2 は失敗します: 中程度の影響度には信頼度 >= 75 が必要ですが、この問題の信頼度は 70 しかありません。結果: 除外。逆に、影響度 30（中低）で信頼度 95 の問題は、高い信頼度に関係なく、30 < 41 であるためステップ 1 で除外されます。

   レビューレポートは、両方のフィルターを通過した問題に焦点を当ててください。

3. 以下を含むレビューレポートをフォーマットして出力します:

   • フィルタリングを通過したフェーズ 2 のすべての確認済みの問題
   • code-quality-reviewer エージェントからのコード改善提案
   • 影響度とプロジェクトガイドラインとの整合性に基づいて改善の優先順位を付けます

フェーズ 3 における誤検出の例

• 変更されていないコードに以前から存在する問題
• バグのように見えても、実際にはバグではないもの
• シニアエンジニアなら指摘しないような、細かすぎる指摘
• リンター、型チェッカー、コンパイラーで検出できる問題（例：インポートの不足や誤り、型エラー、テストの失敗、フォーマットの問題、改行などの細かいスタイル上の問題）。これらのビルド手順を自分で実行する必要はありません。CI の一環として別途実行されると想定して問題ありません。
• 明示的に CLAUDE.md で求められていない限り、一般的なコード品質の問題（例：テストカバレッジの不足、一般的なセキュリティ上の問題、ドキュメントの不備）
• CLAUDE.md で指摘されていても、コード内で明示的に無効化されている問題（例：lint を無視するコメントがある場合）
• 意図的である可能性が高い、またはより大きな変更に直接関係する機能の変更

注意：

• 利用できる場合は、ビルド、lint、テストのコマンドを使用してください。コード変更からは明らかでない潜在的な問題の発見に役立つことがあります。
• まず TODO リストを作成してください。
• 各バグ／問題／提案には、ファイルパスと行番号を必ず記載してください。

レビューレポートの出力

JSON_OUTPUT が true の場合は、以下の JSON テンプレートを使用してレポートを出力してください。それ以外の場合は、Markdown テンプレートを使用してください。

Markdown テンプレート

問題または改善点が見つかった場合

# Local Changes Review Report

**Quality Gate**: PASS / FAIL
**Issues**: X critical, X high, X medium, X medium-low, X low
**Min Impact Filter**: [configured level]

---

## Issues

[For each issue, use this format:]

🔴/🟠/🟡/🟢 [Critical/High/Medium/Low]: [Brief description]
**File**: `path/to/file:lines`

[Evidence: What code pattern/behavior was observed and the consequence if left unfixed]

```language
[Suggestion: Optional fix or code suggestion]

---

改善点

［code-quality-reviewer によるコード改善の提案があれば記載してください：］

1. ［説明］ - file:location - ［理由とメリット］

##### If you found no issues

```markdown
# Local Changes Review Report

**Quality Gate**: PASS
No issues found above the configured threshold.

**Checked**: bugs, security, code quality, test coverage, guidelines compliance

JSON テンプレート

--json フラグが設定されている場合は、以下の JSON 構造で結果を出力してください。

{
  "quality_gate": "PASS",       // "PASS" or "FAIL" - FAIL when any critical or high issue exists
  "summary": {
    "total_issues": 0,          // count of issues after both filters applied
    "critical": 0,              // count at impact 81-100
    "high": 0,                  // count at impact 61-80
    "medium": 0,                // count at impact 41-60
    "medium_low": 0,            // count at impact 21-40
    "low": 0                    // count at impact 0-20
  },
  "issues": [
    {
      "severity": "critical",   // severity label derived from impact_score range
      "file": "src/auth/session.ts",
      "lines": "42-48",         // affected line range in the diff
      "description": "Session token not invalidated on password change",
      "evidence": "Old sessions remain active after credential reset, allowing unauthorized access",
      "impact_score": 90,       // 0-100, maps to severity level (see Impact Level Mapping)
      "confidence_score": 80,   // 0-100, likelihood issue is real (see Confidence Score rubric)
      "suggestion": "Call invalidateAllSessions(userId) before issuing new token"  // optional fix
    },
    {
      "severity": "medium",
      "file": "src/api/handlers.ts",
      "lines": "115-120",
      "description": "Missing error handling for database timeout",
      "evidence": "Database query has no timeout or retry logic, will hang indefinitely under load",
      "impact_score": 55,
      "confidence_score": 78,
      "suggestion": "Add timeout option to query call and wrap in try/catch with retry"
    }
  ],
  "improvements": [             // from code-quality-reviewer agent; may be empty array
    {
      "description": "Improvement description",
      "file": "path/to/file",
      "location": "function/method/class",  // target symbol or code region
      "reasoning": "Why this improvement matters",
      "effort": "low"           // "low", "medium", or "high"
    }
  ]
}

quality_gate は、重大または高重大度の問題がある場合は "FAIL"、それ以外の場合は "PASS" です。問題の suggestion フィールドは任意で、省略できます。

評価ガイドライン

• コミット前の機会：このレビューは、バージョン履歴に入る前の、未コミットのローカル変更を対象に実行されます。最後の防衛線として、修正コストが最も低い今のうちに、バグ、セキュリティ上の欠陥、契約違反を見つけてください。ここで見つかった問題が、チームメンバーや CI に届くことはありません。
• セキュリティを最優先：重大または高重大度のセキュリティ上の問題があれば、コードはコミット可能な状態ではないと判断します。
• すべてを数値で示す：「いくつか」「多く」「少ない」などの言葉ではなく、数値を使ってください。
• 実用性を重視：実際の問題や、影響の大きい改善点に注力してください。
• 変更量が多い場合（500 行超）は、些細な問題を省いてください：
  • アーキテクチャとセキュリティの問題に注力する
  • CLAUDE.md で明示的に求められていない限り、軽微な命名規則の問題は無視する
  • スタイルよりバグを優先する
• 実行可能な改善提案：各提案には具体的なコード例を含めてください。
• 労力と影響を考慮：効果が大きく、妥当な労力で対応できる改善を優先してください。
• プロジェクト標準に準拠：改善を提案する際は、CLAUDE.md やプロジェクトのガイドラインを参照してください。
• ターミナルでの読みやすさ：レポートはターミナル／コンソールで読まれます。固定幅での表示を意識した書式にしてください。短い行、明確なセクション区切り（---）、簡潔な表を使用してください。狭いターミナルで折り返されて読みにくくなる、深くネストした箇条書きや長い文章は避けてください。

覚えておくこと

目的は、完璧さを強制することではなく、開発速度を維持しながらバグやセキュリティ上の問題を見つけ、コード品質を向上させることです。徹底しつつも実用性を重視し、コードの安全性、保守性、継続的な改善に関わる重要な点に注力してください。

このレビューはコミット前に行われるため、問題を早期に見つけ、先回りしてコード品質を高める絶好の機会です。ただし、軽微なスタイル上の問題を理由に妥当な変更を妨げないでください。そのような問題は、今後の反復で対応できます。