AIコーディング支援ツールの進化により、開発速度は劇的に向上しました。しかし同時に、PRの数が急増し、レビュー負荷が逆に増大するという新しい課題が生まれています。手作業でレビューしていては、実装速度の向上に追いつけません。
SKILL.mdを中核に据えたコードレビューエージェントの設計パターンを順番にご紹介します。単なる自動化ではなく、チーム固有の設計思想やプロジェクトルールを反映した、本当に役に立つレビューエージェントの作り方です。
AI時代に増大するコードレビュー負荷
従来のソフトウェア開発では、実装と同程度の工数がレビューに費やされてきましました。しかし、GitHub Copilot、Claude Code、その他のAI支援ツールが普及すると、実装速度は5倍、10倍と跳ね上がります。
一方、既存のコードレビューツール（GitHub Copilot Review、GitLab Duo等）には根本的な限界があります。
- プロジェクト固有ルール への対応がない — クラス命名規約、責務分割の哲学、チーム特有の型安全性の考え方などを理解できない
- 設計思想の判断ができない — 「なぜそのアーキテクチャなのか」という文脈を読み取れない
- チーム知識が蓄積されない — 同じ指摘を何度も繰り返す
こうした課題を解決するために、SKILL.mdを活用したコードレビューエージェントを設計することで、プロジェクト固有の知識を明示的に管理し、スケーラブルなレビューを実現できます。
SKILL.md駆動のアーキテクチャ設計
SKILL.mdは、Cowork（Anthropic公式CLI）の標準形式で、チーム固有の作業手順や判断基準をMarkdownで記述する仕組みです。これをコードレビューエージェントに適用すると、以下のような利点が得られます。
フォルダ構成例
.github/
├── instructions/
│ ├── CODE_REVIEW_PRINCIPLES.md ← チーム全体の設計原則
│ ├── NAMING_CONVENTIONS.md ← 命名規約
│ └── ARCHITECTURE_RULES.md ← アーキテクチャルール
├── skills/
│ └── code-review/
│ ├── SKILL.md ← コードレビューエージェントの手順書
│ ├── good-review.md ← 良い指摘例のテンプレート
│ └── bad-review.md ← 避けるべき指摘パターン
└── agents/
└── code-reviewer.agent.md ← エージェント定義（ワークフロー）
なぜSKILL.mdを中核にするのか
- 可読性 — Markdownで記述するため、非技術者でも理解しやすい
- バージョン管理 — Gitで履歴管理でき、変更理由を記録できる
- チーム共有 — ドキュメント化することで、新しいメンバーのオンボーディングが容易
- 再利用性 — 同じガイドを複数のエージェント（PRレビュー、デザインレビュー、セキュリティレビュー等）で活用可能
9段階のレビューステップを定義する
実践的なコードレビューエージェントは、以下の9段階のステップで構成されます。各ステップで特定の責務に専念することで、精度と信頼性を高めます。
Step 1: 差分検出
入力: PR情報（ファイルパス、追加・削除・変更行数）
処理: git diff を取得し、重要な変更を抽出
出力: 変更対象ファイルのリスト
Step 2: ルール読込
処理: .github/instructions/CODE_REVIEW_PRINCIPLES.md 等を読み込む
目的: このPRのコンテキスト（プロジェクト目標・既知の制約）を確認
Step 3-4: 差分レビューとバグ検出
Step 3: 実装内容の確認
- ロジックの妥当性
- エッジケース対応
- 型安全性
Step 4: バグ検出
- null参照の可能性
- リソースリーク
- 競合状態
Step 5-6: ファイル整合性チェックと影響範囲分析
Step 5: ファイル整合性
- インポート/エクスポートの一貫性
- 循環依存の検出
Step 6: 影響範囲分析
- 他のモジュールへの波及効果
- テストカバレッジの確認
Step 7-9: 要件適合性確認から レポート出力
Step 7: 要件適合性
- PRの説明とコードが一致しているか
- テストが仕様を網羅しているか
Step 8: 品質検証
- パフォーマンスへの影響
- セキュリティ上の懸念
Step 9: レポート出力
- 指摘を整理し、PRコメントで報告
- 重大度レベル（HIGH/MEDIUM/LOW）を明記
重要な制約: 読み取り専用
コードレビューエージェントは、提案のみを行い、自動的にコミットしてはいけません。 理由は以下の通りです。
- 人間の判断が入らず、誤った修正が本番環境に影響する可能性
- チームメンバーのスキル成長機会を損なう
- コード所有者の決定権を奪う
品質ガイドの設計
指摘の質を保つため、「良い指摘」と「悪い指摘」の事例を明示的に定義します。
good-review.md の例
## 良い指摘の構造
1. **問題の説明** — 何が問題なのか、簡潔に
2. **影響** — 放置するとどんなバグが起きるのか
3. **根拠** — なぜそう判断したのか（チーム規約・設計原則を参照）
4. **修正案** — 代替実装を具体的に示す
## 例: 型安全性の指摘
**問題**: `productId` が `string | number` のまま関数に渡されている
**影響**: データベースクエリ時にSQLインジェクションの余地が生じるほか、
型チェックが不完全なため、実行時エラーが発生する可能性
**根拠**: ARCHITECTURE_RULES.md #3 「すべての外部入力は明示的に型変換すること」
**修正案**:
```typescript
const productId = parseProductId(req.query.id);
function parseProductId(input: unknown): ProductId {
if (typeof input !== 'string') throw new Error('Invalid product ID');
return new ProductId(input);
}
### bad-review.md の例
避けるべき指摘（チーム受け入れを損なう）
❌ 個人的好み 「私はこのコード書き方が嫌いです」
❌ 模糊とした指摘 「このロジック複雑では？」→ 何が複雑なのか特定できない
❌ 実行不可能な指摘 「パフォーマンスが悪い」（測定データなし）
❌ スコープ外の指摘 このPRと無関係な部分の改善を指摘
✅ 具体的な根拠 「ARCHITECTURE_RULES.md #7 により、...」
✅ 測定可能な指摘 「このクエリは N+1 問題を引き起こします。 現在のデータ件数では 500ms → 5s に劣化します」
## カスタム命令で組織の知識を注入する
SKILL.mdのカスタム命令セクションに、プロジェクト固有のチェック項目を列挙します。
```markdown
## カスタムチェック項目
### クラス設計
- [ ] クラス名は **名詞** のみ（動詞を含まない）
- ✅ `UserRepository`, `PaymentProcessor`
- ❌ `UserHandler`, `ProcessPayment`
- [ ] 1クラス＝1責務（SOLID原則）
- チェック: 責務が2個以上ないか、PR説明で明示されているか
- [ ] publicメソッドは 1-3個 に限定
- インターフェースが複雑だと、利用者が使い方を誤りやすい
### 型安全性
- [ ] `any` 型は使用禁止（やむを得ない場合は `@ts-ignore` コメント必須）
- [ ] nullish coalescing (`??`) と optional chaining (`?.`) を活用
- [ ] 外部API呼び出しは必ず結果を型チェック
### テスト
- [ ] ロジック変更は「新規テスト」または「既存テスト修正」を伴うか確認
- [ ] 複雑な分岐（if/switch が3段以上ネストしている部分）はテスト対象か確認
### ドキュメント
- [ ] public APIはJSDocコメント必須（パラメータ型、戻り値、例外を記載）
- [ ] 非自明な実装はコメントで意図を説明
これらのチェック項目を、AIエージェントのシステムプロンプトに組み込むことで、チーム固有の判断基準で自動レビューが実行されます。
全体を振り返ってと発展の方向性
SKILL.mdを駆動源としたコードレビューエージェントは、AI時代のスケーラブルなレビュー基盤です。プロジェクトの知識を明示的に管理することで、以下が実現できます。
- 一貫性 — 同じ判断基準で全PRを評価
- チーム受け入れ — ルールが透明で異議唱えやすい
- 継続的改善 — 指摘パターンをSKILL.mdに記録して、次のレビューに反映
次のステップは、このエージェントをCI/CDパイプラインに統合し、PRが作成された時点で自動的にレビューが実行される環境を構築することです。その際の重大度レベルの定義、偽陽性への対処、人間とAIの役割分担については、後編の「プロダクション品質ガイド」で詳しく解説します。