Claude Codeのレビュースキル5種を同一PRで比較して分かった、AIコードレビューのプロンプト設計のヒント

はじめに

システム開発第二事業部の冨永です。主にiOSアプリの開発を担当しております。

最近のプロジェクトで Claude Code を活用し、コードレビューの効率化に取り組んでいます。Claude Codeには「スキル」と呼ばれるカスタムプロンプトを定義する仕組みがあり、用途別にレビュースキルを複数作成して運用しています。

運用を続ける中で、同じコード差分に対してもスキルによってレビュー結果が大きく異なることに気付きました。ある指摘はスキルAだけが出し、別のスキルBは全く違う観点から問題を発見する、といった具合です。

「なぜ差が出るのか？」「最も効果的なスキルの条件は何か？」

この疑問を解消するため、5つのレビュースキルを同一PRに対して計10回実行し、プロンプト設計・diffスコープ・モデルの3つの変数を個別に制御する対照実験を行いました。本記事ではその結果から得られた、AIコードレビューにおけるプロンプト設計の原則を紹介します。

Claude Codeのスキルとは

Claude Codeのスキル（Skills）は、特定のタスクに対してカスタムプロンプトを定義する仕組みです。プロジェクトの .claude/skills/ ディレクトリにMarkdownファイルとして配置することで、/スキル名 のコマンドとして呼び出せます。

たとえば /ci-review と入力すれば、事前に定義したレビュー観点に基づいてClaude Codeがコードレビューを実行します。プロンプトの書き方次第でレビューの質が大きく変わるため、スキルのプロンプト設計がAIコードレビューの品質を左右すると言えます。

なお、Claude Code v2.1.63からは /simplify という標準スキルが搭載されています。これは3つの専門エージェント（コード再利用・品質・効率性）が並列でコードをレビューするビルトイン機能です。今回はこの標準スキルも比較対象に加えることで、カスタムスキルの効果を標準機能と対比できるようにしました。

比較した5つのスキル

スキル プロンプト行数 設計思想 ドメイン特化度 デフォルトモデル 種別
CI Review 44行 観点列挙型 iOS特化 Opus カスタムスキル
General Review 137行 手順書型 汎用 Opus カスタムスキル
Refactoring 1,212行 超詳細手順書型 iOS特化 Sonnet カスタムスキル
SwiftUI Review 119行 チェックリスト型 SwiftUI特化 Opus カスタムスキル
Simplify 53行 並列エージェント型 汎用 Opus Claude Code標準

注目していただきたいポイントが2つあります。

1つ目は、プロンプト設計思想の多様さです。

  • 観点列挙型：「何を見るか」だけ指示し、「どう見るか」はAIに委ねる
  • 手順書型：ステップバイステップの手順を詳細に記載する
  • 超詳細手順書型：チェック項目ごとにコード例まで含む詳細マニュアル
  • チェックリスト型：チェック項目を順番に実行させる
  • 並列エージェント型：複数の専門エージェントが異なる視点で同時にレビューする

2つ目は、デフォルトモデルが統一されていない点です。 Refactoringだけが Sonnet を指定しており、他は Opus です。この差が後の重要な発見につながります。

今回の調査では、レビュー品質に影響する変数を プロンプト設計・diffスコープ・モデル の3つと仮定し、それぞれの影響を個別に測定しました。

プロンプトの具体例

各設計思想の違いをイメージしていただくため、プロンプトの抜粋を紹介します（プロジェクト固有の情報は汎用化しています）。

✅ 観点列挙型（CI Review — 44行）

シンプルに「何を見るか」だけを列挙しています。

あなたはiOSアプリケーションのエキスパートデベロッパーです。
このプルリクエストの変更点をレビューし、フィードバックを提供してください。

## レビュー観点
- コードの品質とSwiftのベストプラクティス
- Clean Architecture + MVVM パターンの遵守
- リアクティブフレームワークの適切な使用法
- 永続化フレームワークの正しい使用法
- メモリリーク、循環参照のリスク
- iOS固有の潜在的な問題（スレッド安全性、ライフサイクル等）
- 修正後の横展開での修正漏れがないか

わずか44行のプロンプトですが、「永続化フレームワーク」「スレッド安全性」「横展開の修正漏れ」といったドメイン特化の観点が含まれている点が重要です。「どうやってチェックするか」は一切書いていません。

🔀 並列エージェント型（Simplify — 53行）

3つの専門エージェントを並列に起動し、同じdiffを異なる角度から同時レビューする構造です。

## Phase 2: Launch Three Review Agents in Parallel

### Agent 1: Code Reuse Review
1. Search for existing utilities that could replace newly written code.
2. Flag any new function that duplicates existing functionality.
3. Flag any inline logic that could use an existing utility.

### Agent 2: Code Quality Review
1. Redundant state: cached values that could be derived
2. Copy-paste with slight variation: near-duplicate code blocks
3. Leaky abstractions: exposing internal details

### Agent 3: Efficiency Review
1. Unnecessary work: redundant computations, N+1 patterns
2. Hot-path bloat: blocking work on per-render paths
3. Memory: unbounded data structures, missing cleanup

## Phase 3: Fix Issues
Aggregate findings. If a finding is a false positive, note it and move on.

iOS固有の知識は含まれていませんが、3つのエージェントが独立して全ファイルを走査するため、クロスファイルのパターン（ファイルAとファイルBの重複、N+1的な非効率）を検出できる構造です。

📋 手順書型（General Review — 137行）

MCPツールの呼び出し手順を詳細に記載するスタイルです。

## レビュー手順

### Step 1: PR情報の取得
GitHub MCPを使用してPRの差分を取得してください。

### Step 2: 変更内容の分析
取得した差分に対して以下の観点でレビューしてください：
- 実装の整合性
- コーディングガイドライン
- テストカバレッジ

### Step 3: 結果の出力
以下のフォーマットで出力してください：
[must] 説明 → ファイル名 L行番号

137行のうち多くがツール呼び出しの手順に割かれており、レビュー観点自体はプロジェクト非依存の汎用的なものにとどまっています。

📖 超詳細手順書型（Refactoring — 1,212行）

最も長大なプロンプトです。12のチェック項目それぞれにコード例と判断基準を記載しています。このスキルだけがデフォルトモデルにSonnetを指定しています。

## チェック項目 1: マジックナンバーの抽出

### 判断基準
- 数値リテラルが直接使われている箇所を検出
- ただし 0, 1 は除外

### Before
func fetchItems(page: Int) {
    let url = "\(baseURL)/items?limit=20&offset=\(page * 20)"
}

### After
private enum Constants {
    static let itemsPerPage = 20
}
func fetchItems(page: Int) {
    let url = "\(baseURL)/items?limit=\(Constants.itemsPerPage)&offset=\(page * Constants.itemsPerPage)"
}

## チェック項目 2: 早期リターンの適用
...（以下、項目12まで同様のフォーマットが続く）

🔍 チェックリスト型（SwiftUI Review — 119行）

5つの観点を順番に実行させるスタイルです。

## レビュー手順

### Step 1: 対象ファイルの特定
git diff でSwiftファイルの変更一覧を取得

### Step 2: 5つの観点でチェック
1. 非推奨API検出（Apple公式ドキュメントで確認）
2. 変数名・コメントの整合性（タイポ、命名の一貫性）
3. 型の統一性（型エイリアスの重複、親子View間の型統一）
4. SwiftUI構造のベストプラクティス（Viewの粒度、ハードコード値）
5. プロジェクト固有パターンへの準拠

統一条件での比較結果

まず結論からお見せします。全スキルを 同一スコープ（PRベースブランチ diff、26ファイル）× 同一モデル（Opus） で実行した結果です。

順位 スキル must should その他 合計 ユニーク発見
1 CI Review 3 5 11 19 3
1 Simplify 3 6 10 19 7
3 SwiftUI Review 4 5 4 13 4
4 Refactoring（Opus） 0 4 5 9 —
4 General Review 1 3 5 9 2

ユニーク発見 = そのスキルでしか検出できなかった指摘の数

CI ReviewとSimplifyが同率1位（19件）。 ただし発見の性質は全く異なります。

検出領域 強いスキル 弱いスキル
ランタイムバグ（ハング、クラッシュ） CI Review Simplify
効率性（N+1、二重呼び出し、O(N²)） Simplify 他の全スキル
コード再利用・重複検出 Simplify General Review
スレッド安全性 CI Review Simplify, SwiftUI Review
非推奨API SwiftUI Review Simplify
命名・表記ゆれ SwiftUI Review CI Review

CI Reviewはバグの「深さ」、Simplifyはパターン検出の「広さ」に優れます。 両者は補完関係にあります。

では、この結果がどのような検証から得られたのかを見ていきます。

検証1：プロンプト設計は品質に影響するか？

条件

スコープ・モデルを統一（PRベースブランチ diff × Opus）し、プロンプト設計のみが異なる状態で比較しました。

結果

スキル プロンプト設計 合計 must
CI Review 観点列挙型（iOS特化） 19 3
Simplify 並列エージェント型（汎用） 19 3
SwiftUI Review チェックリスト型（SwiftUI特化） 13 4
Refactoring 超詳細手順書型（iOS特化） 9 0
General Review 手順書型（汎用） 9 1

同じスコープ・モデルでも最大2倍以上の差（19件 vs 9件）。プロンプト設計がレビュー品質の主要因であることが確認されました。

注目すべき2つのポイント

1. プロンプトの長さ ≠ 品質

CI Review（44行）と Refactoring（1,212行）は共にiOS特化ですが、件数に2倍の差がつきました。1,212行の詳細な手順はAIが「手順をこなすこと」に認知リソースを消費し、手順外の創造的な発見を抑制する傾向があります。

2. ドメイン特化でなくても、並列構造で補える

Simplify（汎用・iOS知識なし）がCI Review（iOS特化）と同数の19件を達成。ただし発見の性質が異なります。

要素 効果
ドメイン特化の観点 他スキルが見逃すランタイムバグを発見。発見の質に寄与
並列エージェント構造 クロスファイルのパターンを同時検出。発見の量に寄与

CI Reviewだけが発見したスレッド安全性違反のようなバグは、ドメイン観点なしには到達できません。逆にSimplifyだけが検出した効率性の問題（N+1、O(N²)、二重呼び出し）は、他の全スキルが全く拾えなかった領域です。

⚠️ 同じ箇所を見ても分析の「深さ」が異なる

プロンプトの観点の差は、同じコード箇所に対する分析の深さにも影響しました。

General Review の指摘：

「このAPIはiOS 16で非推奨です。新しいAPIに置き換えてください」

CI Review の指摘：

「このAPIは非推奨であるだけでなく、UIKitのナビゲーションスタック上にホスティングされているため、そもそも期待通りに動作しない可能性があります」

CI Reviewのプロンプトには「iOS固有の潜在的な問題」という観点が含まれていたため、単なる非推奨の指摘を超えて、アーキテクチャの文脈を踏まえた実践的な指摘に到達しています。

検証2：diffスコープは品質に影響するか？

条件

同一スキル・同一モデルで、スコープだけを変えて比較しました。

結果

スキル 狭いスコープ 広いスコープ 変化
Simplify 直近コミット → 4件 PRベースブランチ diff → 19件 +375%
SwiftUI Review 直近コミット → 11件 PRベースブランチ diff → 13件 +18%
CI Review PRベースブランチ diff → 19件 master diff → 23件 ※
Refactoring develop diff → 8件 PRベースブランチ diff → 9件 +12%

※ CI Reviewは件数こそ増えたが、広すぎるスコープ（123ファイル）で分析が浅くなり、PRベースブランチ diffで見つかった3件を見逃していた。

スコープの影響はスキルによって大きく異なる

スキル スコープ感度 理由
Simplify 極めて高い 3並列エージェントがクロスファイルの重複・非効率を検出する設計。スコープが広いほどパターンが見つかる
SwiftUI Review 低い チェックリスト型のため、項目の枠内で動作。スコープ拡大の恩恵は限定的
Refactoring 低い 手順書型のため各ファイルを個別に検査。クロスファイルの検出が構造的に弱い

最適なスコープはPRのベースブランチ diff です。 広すぎると分析が浅くなり（「森を見て木を見ず」）、狭すぎるとクロスファイルのパターンを見逃します。

検証3：モデル（Opus vs Sonnet）は品質に影響するか？

Opusの結果をプロンプト型で整理する

まず、統一条件（PRベースブランチ diff × Opus）の結果をプロンプト型ごとに並べると、明確な傾向が見えます。

プロンプト型 スキル 合計 must
観点列挙型（自由度高） CI Review 19 3
並列エージェント型 Simplify 19 3
チェックリスト型 SwiftUI Review 13 4
手順書型 General Review 9 1
超詳細手順書型 Refactoring 9 0

Opus × 自由度の高いプロンプト = 高パフォーマンス。Opus × 手順書型 = 低パフォーマンス。 プロンプトの自由度が高いほどOpusの検出力が上がる傾向がはっきり出ています。

では、手順書型はモデルを変えれば改善するのでしょうか？

対照実験：Refactoringでモデルだけを変更

同一スコープでRefactoringのモデルだけを変えて比較しました。

モデル must should その他 合計
Sonnet 3 5 3 11
Opus 0 4 4 8

Sonnetに変えるだけで+37%、mustが0→3に。 手順書型プロンプトはSonnetとの相性が良いことが分かりました。

Sonnet Opus
強み 機械的チェック（強制アンラップ、マジックナンバー） 設計・アーキテクチャ（テスト不足、Disposable管理）
弱み 手順外の発見がない 機械的チェックをスキップする傾向

Sonnetは1,212行の手順に忠実に従い、一つ一つ機械的に検査します。Opusは手順を「参考」として扱い、自身の判断で取捨選択してしまいます。

スコープを揃えてもモデルの影響は残る

Refactoringのスコープを適正化（develop → PRベースブランチ）しても、Opusのmust=0は解消しませんでした。

条件 must 合計
develop × Sonnet 3 11
PRベースブランチ × Opus 0 9
develop × Opus 0 8

スコープの適正化で+12%の改善はありましたが、mustレベルの機械的チェックはモデルが主要因です。

結論：モデルとプロンプト型の相性マトリクス

Opus Sonnet
観点列挙型（短い・自由度高） ◎ 自由に深く分析 △ 自由度を活かしきれない
並列エージェント型 ◎ 各エージェントが自律的に動く ○ 良好
手順書型（長い・手順詳細） △ 手順を取捨選択してしまう ◎ 手順に忠実に網羅実行
チェックリスト型 ○ 良好 ○ 良好

Opusは「自由に分析せよ」で力を発揮する。Sonnetは「この手順に従え」で確実に動く。 Refactoringが当初からSonnet指定だったのは、手順書型との相性から合理的な設計でした。

寄与度のまとめ

3つの検証を総合し、レビュー品質への寄与度を以下のように推定しました。

要因 寄与度 根拠
diffスコープ 約35% Simplifyで+375%。ただしSwiftUI Reviewは+18%、Refactoringは+12%とスキルにより差がある
プロンプトのレビュー観点 約30% 同一条件でCI Review（19件）とGeneral Review（9件）に2倍以上の差
プロンプトの構造 約20% Simplifyの3並列エージェント構造がiOS観点なしでも19件を達成。構造が量を生む
モデル選択 約15% RefactoringでSonnet→Opusに変更すると-27%。手順書型との相性がある

4つの要因が複合的に作用しており、どれか1つだけでは説明できません。

レビュー信頼性の向上：false positiveセクション

検出件数とは別の軸で、レビュー結果への信頼性を大きく向上させる手法がありました。Simplifyが出力する「対象外とした指摘（false positive）」セクションです。

実際の出力例

| 検討した指摘 | 対象外と判断した理由 |
|------------|---------------------|
| インスタンスの4重生成 | 依存構築の重複修正時に統合される。独立した問題ではない |
| 二重購読 | 共有演算子で保護されているため実害なし |
| モデルへの型適合追加 | UIフレームワークでの使用に必要な適切な追加 |

なぜ重要か

通常のレビュー結果は「指摘した項目」だけで構成されます。読み手は「あの定番パターン、チェックしたのか？」という疑問を抱きますが、答えがありません。

false positiveセクションがあることで：

  1. 見落としではないことが明確になる — レビュアー（AI）が検討した証跡が残る
  2. 判断理由が記録される — 「なぜ指摘しなかったか」が根拠付きで共有される
  3. レビュー結果全体の信頼性が向上する — 指摘された項目も「精査の上で出している」と読める

これはAIレビューに限らず、人間のコードレビューにも有効な考え方です。各スキルのプロンプトに以下の一文を追加するだけで実現できます。

レビュー結果の末尾に「対象外とした指摘（false positive）」セクションを設け、
検討したが指摘しないと判断した項目とその判断理由を表形式で出力すること。

推奨されるスキル構成

最強の3スキル構成

スキル モデル 役割
CI Review相当 Opus ランタイムバグ・スレッド安全性・機能欠落の深い分析
Simplify Opus 効率性・コード再利用・クロスファイルパターン + false positive分析
Refactoring相当 Sonnet 機械的安全性チェック（強制アンラップ、マジックナンバー）の確実な実行

この3つで発見の性質がほぼ重複しないため、最大の網羅性が得られます。

1つだけ使うなら

  • バグの深刻度を重視 → ドメイン特化の観点列挙型（CI Review相当）
  • コード品質・効率性を重視 → Simplify（Claude Code標準）

スキル設計のガイドライン

新しいレビュースキルを作る際は、以下を考慮いただくと良いかと思います。

  • Opusで使うなら: 観点を列挙して自由に分析させる。手順は最小限に
  • Sonnetで使うなら: 詳細な手順とチェックリストを書く。網羅性が向上する
  • クロスファイル検出が必要なら: 並列エージェント構造を検討する
  • 信頼性を高めたいなら: false positiveセクションの出力を指示する
  • スコープは: PRのベースブランチ diff をデフォルトにする

まとめ

Claude Codeの5つのレビュースキルを同一PRに対して計10回実行し、3つの変数を個別に制御した結果、以下の原則が明確になりました。

原則 要約
プロンプト設計が最大要因 同じスコープ・モデルでも最大2倍以上の差。ただし長さ≠品質
ドメイン特化 vs 並列構造 ドメイン知識は発見の「質」を、並列構造は発見の「量」を生む
スコープはPRベースブランチが最適 広すぎると分析が浅く、狭すぎるとパターンを見逃す
モデルとプロンプト構造に相性がある Opusは自由度の高いプロンプトで、Sonnetは詳細な手順書で力を発揮する
false positive分析で信頼性向上 「指摘しなかった理由」の明示がレビュー全体の信頼性を上げる

最も意外だったのは、初期条件で最下位（4件）だったSimplifyが、適切なスコープを与えるだけで1位タイ（19件）に浮上した点です。スキルの良し悪しは固定的なものではなく、条件次第で大きく変わります。

また、44行のプロンプトと1,212行のプロンプトの優劣は、モデルとの組み合わせで逆転するという発見は、「プロンプトは短い方が良い」という単純な法則への反例です。

唯一の正解はありませんが、本記事がAIコードレビューのプロンプト設計を検討される際の参考になれば幸いです。

参考

テコテックの採用活動について

テコテックでは新卒採用、中途採用共に積極的に募集をしています。 採用サイトにて会社の雰囲気や福利厚生、募集内容をご確認いただけます。 ご興味を持っていただけましたら是非ご覧ください。 tecotec.co.jp