長期プロジェクトをClaude Codeで進めていると、こんな場面ってありませんか？
Claude Code: 「Phase 2の作成が終了しました。動作確認をしていただいたうえで、次に Phase 3 へ進むかご判断ください。」
このとき、
– 本当に要件を満たせているか？
– 抜け漏れはないか？
– 次のPhaseに進んでいいのか？
を毎回手動で確認するのは、地味に疲れます。特に本業の合間に開発を進めている人にとって、判断疲れは大敵です。
これ、**Subagent（サブエージェント）で自動化できます。**
この記事では、Claude Codeで「Phase完了報告 → 自動チェックリスト生成 → 検証 → レポート出力」を実現する方法を、仕組みの理解から実際のファイル作成までまとめます。
—
## そもそもSubagentとSkill、どう違う？
Claude Codeで似たような拡張機能として「Subagent」と「Skill」がありますが、用途が違います。
### Subagentが向いているケース
– **特定の発話パターン**に反応して起動させたい
– 専門タスクとして**独立したコンテキスト**で動かしたい
– 複数ステップを**自律的に実行**させたい
### Skillが向いているケース
– 自然な発話で**Claude側が判断して起動**させたい
– **プロジェクト横断**で使い回したい
– フォーマットや参照ドキュメントが**固定化**できる
今回やりたいのは「Phase完了報告」という特定の発話パターンに反応させることなので、**Subagentが正解**です。
—
## 仕組み：なぜ自動起動するのか
ここが一番気になるポイントだと思います。
Claude Codeは、ユーザーとのやり取りの中で**常に「この発話に対して、使えるサブエージェントはないか？」をチェック**しています。
その判断材料が、Subagentファイルの先頭に書く **`description` フィールド**です。
name: phase-validator
description: Phaseの完了報告を受けて、自動でチェックリスト作成・検証・
レポート出力を行う専門エージェント。「Phase Xの作成が終了しました」
「次のPhaseへ進むかご判断ください」などの発話を検知した際に必ず起動する。
Claude Codeは内部的にこう判断します：
1. 「`Phase 2が終了しました` という発話が出た」
2. 登録されているサブエージェント一覧を確認
3. `phase-validator` のdescriptionに**まさにその発話パターン**が書かれている
4. このタスクは `phase-validator` に委譲すべき
つまり、**descriptionは「私を呼ぶべきタイミングはこれです」という申告書**として機能しているわけです。
### descriptionに書くべき3要素
効果的なdescriptionには次の3つを盛り込みます：
1. **何をするエージェントか**（役割）
2. **どんな発話・状況で起動すべきか**（トリガー条件）
3. **具体的なキーワード例**（パターンマッチの手がかり）
「必ず起動する」のような**断定的な表現**を使うと、Claude Codeの判断に強い後押しがかかります。
—
## 100%確実ではない、だから保険をかける
仕組み上、Claude Codeの「判断」に依存するので、100%自動起動を保証するものではありません。
そこで保険として、プロジェクトルートの `CLAUDE.md` に**プロジェクト全体のルール**として明記しておきます：
“`markdown
## エージェント運用ルール
– Phase完了報告時（「Phase Xが終了しました」「次のPhaseへ進むかご判断ください」など）は、
必ず phase-validator subagent を起動してチェックリストを生成すること
– レポートが ⚠️ または ❌ の場合、ユーザーの判断を仰ぐまで次Phaseの作業に着手しないこと
“`
これで **description + CLAUDE.md の二重の発動条件**になり、確実性が上がります。
—
## 実際の動作フロー
設計したエージェントの動きはこうなります：
“`
Claude Code: “Phase 2の作成が終了しました”
↓ (Claude本体が検知 → phase-validatorに自動委譲)
phase-validator subagent:
1. ハンドオーバードキュメントからPhase 2の要件を読み込む
2. git logや差分から実装内容を把握
3. 要件 vs 実装でチェックリストを生成
4. 各項目を実際に検証（ファイル存在、テスト実行、DB確認など)
5. 結果をMarkdownで .claude/phase-reports/ に保存
6. 合格 / 要修正 / 進行不可 の判定を返す
“`
ユーザーは何もしなくていい。報告を受けて自動でチェックが走る、というのが理想形です。
—
## ファイル構成と配置場所
Subagentは、プロジェクトルートに以下のように配置します：
“`
プロジェクトルート/
├── .claude/
│ ├── agents/
│ │ ├── code-reviewer.md
│ │ └── phase-validator.md ← 今回作るファイル
│ └── phase-reports/ ← レポート出力先
└── CLAUDE.md
“`
`.claude/agents/` フォルダが無ければ作成。Claude Codeは起動時にこのフォルダを走査して、登録されているサブエージェントを把握します。
—
## Subagentファイルの中身
`phase-validator.md` の構成はこんな感じです：
### フロントマター（YAML）
“`yaml
—
name: phase-validator
description: （前述のトリガー条件を含む申告書）
tools: Read, Glob, Grep, Bash, Write
—
“`
`tools` で使用可能なツールを限定できます。今回は以下が必要：
– `Read` / `Glob` / `Grep`：ドキュメントと実装の確認
– `Bash`：git logやテスト実行
– `Write`：レポート出力
### 本文の構成
本文には**手順書**を書きます：
1. **Step 1: Phase要件の把握** – ハンドオーバードキュメントを読む
2. **Step 2: 実装内容の把握** – git diffと主要ファイルの確認
3. **Step 3: チェックリスト生成** – 観点別に項目作成
4. **Step 4: 自動検証の実行** – 機械的にチェック可能なものは実行
5. **Step 5: レポート出力** – Markdownで保存
そして最後に**重要な原則**を書きます：
– 勝手に次のPhaseへ進む判断をしない
– 推測せず、不明点はユーザーに確認する
– 該当しない項目はスキップして、判断疲れを起こさせない
– 修正対応の優先順位を明示する（必須／推奨／任意）
—
## 環境固有のハマりどころ対策
Windows環境で日本語ユーザー名を使っている場合の対策も、エージェント側に組み込んでおくと安心です：
– ASCIIパスを使う：出力先パスに日本語を含めない
– エンコーディング配慮：`chcp 65001` 前提でターミナル出力を扱う
こうした環境固有の制約をエージェントに教え込んでおくと、毎回同じ問題でつまずかなくて済みます。
—
## まとめ
Claude CodeのSubagentで「Phase完了チェック」を自動化するポイントは3つ：
1. descriptionにトリガー発話を具体的に書く – Claude Codeが「このタスクは私の出番だ」と気づける手がかりを与える
2. CLAUDE.mdに保険のルールを書く – description単独より、プロジェクト全体のルールと併用すると堅い
3. 手順を構造化して原則を明示する – 自律的に動いてもらうには、判断基準まで含めて言語化する
長期プロジェクトを進めるとき、Claudeに「実装させる」だけでなく「自分の仕事をチェックさせる」レイヤーを足すと、品質と速度の両方が上がります。
特にPhase制で進める業務システム開発のように、段階ごとの品質ゲートが重要なプロジェクトでは、このパターンは強力です。
—
## おまけ：Skillと併用する発展形
今回はSubagent単体の話でしたが、将来的には：
– **Subagent**：Phase完了報告に反応して起動
– **Skill**：レポートのフォーマットやチェック観点のテンプレートを提供
という役割分担も可能です。Subagent内から「このフォーマットで出力して」とSkillを参照させることで、複数プロジェクトで一貫したレポートが作れます。
ただ、まずはSubagent単体で動かしてみて、運用しながら必要に応じて拡張していくのがおすすめです。
コメント