Claude Codeを8つのサブエージェント構成で使う方法 — CLAUDE.md設定と品質ゲート

Posted at 2026-03-27

やりたいこと

1人開発では「設計→実装→テスト→セキュリティ確認」を全部自分でやる必要がある。しかしコンテキストが混在しがちで、「コードを書きながら設計の穴に気づく」「テストを書きながらセキュリティを後回しにする」といった問題が起きやすい。

Claude Codeで役割を分離した複数のサブエージェント構成を定義すると、レビュー観点を明確に分けたまま、一人でPDCAサイクルを回せるようになる。

この記事ではCLAUDE.mdへのサブエージェント定義方法と、品質ゲートの設け方を解説する。

解決策: CLAUDE.mdにサブエージェントを定義する

Claude Codeは.claude/CLAUDE.mdを会話の先頭に自動で読み込む。ここにマネージャー・エージェントの役割と委任ルールを記述することで、「今どのロールとして動くか」を明示できる。

プロジェクトルート/
└── .claude/
    ├── CLAUDE.md          ← エージェント定義と委任ルール
    └── rules/
        ├── quality-gates.md   ← 品質ゲート定義
        └── review-rubrics.md  ← 評価ルーブリック

CLAUDE.mdの書き方

サブエージェント一覧の定義

# Role: Manager/Orchestrator
私はマネージャーです。実装は直接行わず、専門エージェントに委任します。

## Available Subagents
| Agent     | Role               | When to Use                          |
|-----------|--------------------|--------------------------------------|
| architect | System design      | Architecture, API contracts, DB schema |
| executor  | Implementation     | Writing code, fixing bugs, tests     |
| evaluator | Testing/stats      | Test execution, benchmarks, coverage |
| auditor   | Security review    | Code audit, vulnerability, compliance |
| risk-manager | Risk assessment | Dependencies, failure modes          |

## Delegation Rules
# 1. メイン会話でコードを直接書かない — executor に委任
# 2. デプロイ前に必ず auditor レビューを通す
# 3. 標準チェーン: architect → executor → evaluator → auditor
# 4. 独立したタスクは並行実行（architect と risk-manager など）

各エージェントの責任範囲を明記する

## Executor (実装担当)
### Responsibilities
- 設計仕様に基づくコード実装
- ユニットテストの同時作成
- バグ修正（根本原因分析付き）

### Constraints
# 設計から逸脱する場合は必ずフラグを立てて報告する
# 新規関数には最低1つのテストを追加する
# 既存コードのスタイルに必ず合わせる

## Auditor (セキュリティ監査担当)
### Responsibilities
- SQLインジェクション・XSSなどの脆弱性検出
- APIキーのハードコードチェック
- 依存パッケージの既知脆弱性確認

品質ゲートの定義方法

rules/quality-gates.md に段階的なゲートを定義することで、各フェーズの完了基準が明確になる。

# Quality Gates

## G1: Design Review (Architect → Executor への引き渡し条件)
# 全項目チェック済みのときのみ実装フェーズに進む
- [ ] 全エンドポイントにHTTPメソッド・パス・説明がある
- [ ] リクエスト/レスポンスのスキーマが定義されている
- [ ] DBスキーマに主キーと外部キー制約が定義されている
- [ ] 未解決のアーキテクチャ上の疑問がゼロである

## G2: Implementation Review (Executor → Evaluator への引き渡し条件)
- [ ] 計画されたファイルが全て作成・変更されている
- [ ] 新規関数にユニットテストが書かれている
- [ ] コードが既存のプロジェクト規約に従っている
- [ ] 未解決のTODO/FIXMEがコード中にない

## G3: Test Verification (Evaluator → Auditor への引き渡し条件)
- [ ] ユニットテストのカバレッジが70%以上
- [ ] 統合テストが全てパス
- [ ] API p95応答時間が500ms未満
- [ ] DBクエリが100ms未満

## G4: Security Clearance (Auditor → デプロイへの引き渡し条件)
- [ ] CRITICALの指摘がゼロ
- [ ] HIGHの指摘が全て修正済み（またはManagerが明示的に受容）
- [ ] シークレット・PIIの露出がゼロ
- [ ] 依存パッケージの脆弱性確認済み

ポイント: ゲートは順番通りに適用する（G1→G2→G3→G4）。前のゲートを通過していなければ次のフェーズに進まない。

実際のレビュー結果の例

設計レビュー（G1）を適用した際の実例を示す。

Architectのレビュー前後の比較

### G1実施前の状況
- API設計書に14エンドポイントを定義
- エラーレスポンスのスキーマが未定義
- DBスキーマのインデックス戦略が空白
- 非機能要件（パフォーマンス閾値）が不在

### G1の指摘（HIGH）
1. [HIGH] /api/v1/query の400/401/500エラースキーマが未定義
2. [HIGH] voicelog テーブルに user_id インデックスがない
   → クエリパターンを考えると全件スキャンになる
3. [HIGH] STT API のタイムアウト値が未定義
   → Executorが実装時に任意の値を使うリスクがある
4. [HIGH] DBコネクションプールのサイズが非機能要件に未記載

### 修正後
- エラースキーマをOpenAPI形式で全エンドポイントに追記
- CREATE INDEX idx_voicelog_user_id ON voice_log(user_id) を追加
- タイムアウト値をconfig.pyに定数定義してAPI設計書にも明記
- DBプールサイズをnon-functional-requirements.mdに追記

設計レビューでHIGH指摘が4件出た。これをG1で塞いだことで、実装フェーズでの手戻りがゼロだった。

Executorのセルフレビューチェックリスト（9項目）

review-rubrics.md にExecutorが実装完了前に自己確認する9項目を定義する。

## Executor: セルフレビュー必須項目
# 実装完了を報告する前に以下を全て確認すること

- [ ] 全public関数にtype hintsがある
- [ ] 全public関数にdocstringがある
- [ ] エラーハンドリング: try-exceptは具体的な例外をキャッチ（bare exceptなし）
- [ ] ログ: 適切なレベル（DEBUG/INFO/WARNING/ERROR）を使い分けている
- [ ] 金額計算: integerのみ使用（floatなし）
- [ ] 日付処理: タイムゾーンを明示している（naive datetimeなし）
- [ ] SQLクエリ: パラメータバインディングを使用（文字列結合なし）
- [ ] 入力バリデーション: 全外部入力にバリデーションがある
- [ ] テスト: 新規関数1つにつき最低1テストがある

実装後の報告フォーマットにこのチェックリストの結果を含めることで、「チェックしたかどうか」が会話ログに残る。

効果: 設計レビューで潰せた問題の具体例

フェーズ	問題	G1なしの場合	G1ありの場合
設計→実装	エラーハンドリングの仕様が曖昧	実装者が独自判断で実装 → 後でリファクタ	設計書に明記してから実装
設計→実装	インデックスが未定義	本番でスロークエリ発生 → 緊急対応	実装時にDDLに含める
実装→テスト	タイムアウト値が任意定数	テストが環境依存で不安定	config経由で差し替え可能な設計に
実装→デプロイ	APIキーがコードにハードコード	本番リポジトリにシークレット混入	G4で検出・修正

1人開発でも「設計・実装・テスト・監査」の観点を分けることで、「後で気づいて直す」コストが減る。

まとめ

CLAUDE.md にサブエージェントの役割と委任ルールを定義する
rules/quality-gates.md に各フェーズの完了基準をチェックリスト形式で書く
rules/review-rubrics.md にExecutorのセルフレビュー9項目を書く
ゲートは順番通りに適用する（G1→G2→G3→G4）

設定ファイルに書いてしまえば、以降の会話でClaude Codeは自動的にその役割を意識して動く。1人でも観点を分けた開発プロセスを持てる。

全体像はnoteに → 1人開発でも品質は担保できる — Claude Codeに「8つの役割」を与えてチーム開発のプロセスを回した話

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up