「テストを書く時間がない」「毎回同じ指示を打つのが地味に面倒」、そんな悩みを抱えていませんか？ Claude Codeのサブエージェント機能を使えば、単体テストの作成から実行、失敗時の自動修正までを一気通貫で自動化できます。この記事では、実際に手を動かして構築できるレベルまで、設定ファイルの書き方からコミット時のフック連携まで具体的に解説します。
この記事でわかること
- サブエージェントを使って単体テストの作成〜実行を自動化する方法がわかる
- test-runner専用サブエージェントの設定ファイルの書き方が理解できる
- コミット時に自動でテストが走る仕組みを実践できるようになる
- サブエージェントとメインセッションの役割分担が理解できる
結論：.claude/agents/にtest-runner系サブエージェントを作り、Hooksでコミットと連携すれば単体テストはほぼ自動化できます
結論から言うと、単体テストの作成と実行を自動化する一番の近道は、専用のサブエージェントを.claude/agents/（またはユーザー単位なら~/.claude/agents/）にMarkdownファイルとして定義し、コミット時やファイル保存時に自動起動するフックと組み合わせることです。これだけで「テストを書く→実行する→失敗を直す→再実行する」というサイクルをClaude Codeに任せられるようになります。
なぜこれが効くのか、もう一歩深掘りします。単体テストの自動化がうまくいかない一番の原因は、メインの会話コンテキストが「実装の話」と「テストの話」で混ざり合ってしまうことだと私は感じています。長時間の開発セッションでは、会話履歴やログがどんどん積み重なり、Claudeが序盤の重要な指示を忘れてしまうことがあります。サブエージェントは独立したコンテキストウィンドウで動くため、テストに関する調査・実行・分析はメイン会話を汚さずに完結します。さらにフックで起動タイミングを固定してしまえば、「テストを書いて」と毎回頼む手間そのものがなくなります。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
サブエージェントで単体テスト作成〜実行を自動化する完全手順
ここからは実際の構築手順を、順番に見ていきます。
手順1：test-automation専用のサブエージェントを作成する
まずは/agentsコマンドを使って対話形式で作成するか、.claude/agents/test-automation-specialist.mdを直接手書きします。
会話形式でサブエージェントを作成する例
Step1: /agents コマンドを実行
> /agents
これでサブエージェント管理画面が起動し、「新規作成」を選べます。
あなた:
単体テストを自動生成・実行してくれるサブエージェントを作りたいです。
対象はTypeScriptのプロジェクトで、Jestを使っています。
関数を渡したら、正常系・異常系・境界値のテストケースを
考えて実装してほしいです。
Claude:
了解しました。以下の内容でサブエージェントを作成しますか？
- 名前: test-writer
- 説明: TypeScript/Jestの単体テストを自動生成するエージェント
- ツール: Read, Write, Edit, Bash(jestの実行用)
- システムプロンプト:
「あなたはテスト駆動開発の担当者です。
渡された関数に対して、正常系・異常系・境界値を
網羅したJestのテストコードを生成してください。
生成後は実際にテストを実行し、失敗した場合は
原因を分析して修正案を提示してください。」
この内容でよろしいですか？
Step3: 微調整を会話で加える
あなた:
カバレッジも出力してほしいので、実行時は
--coverage オプションをつけてください。
あと、モックが必要な場合はjest.mock()を使う方針にして。
Claude:
承知しました。システムプロンプトに以下を追記します。
「テスト実行時は必ず `jest --coverage` を使用し、
カバレッジレポートを確認すること。
外部依存(API呼び出し・DB接続等)がある場合は
jest.mock()でモック化してからテストを書くこと。」
これで保存しますね。
Step4: 生成されるファイル
会話の内容がそのまま .claude/agents/test-writer.md に反映されます。
---
name: test-writer
description: TypeScript/Jestの単体テストを自動生成するエージェント
tools: Read, Write, Edit, Bash
---
あなたはテスト駆動開発のエキスパートです。
渡された関数に対して、正常系・異常系・境界値を
網羅したJestのテストコードを生成してください。
テスト実行時は必ず `jest --coverage` を使用し、
カバレッジレポートを確認すること。
外部依存がある場合は jest.mock() でモック化してから
テストを書くこと。
生成後は実際にテストを実行し、失敗した場合は
原因を分析して修正案を提示してください。
.claude/agents/test-automation-specialist.mdを直接手書きする方法
| 項目 | 内容 |
|---|---|
name |
一意な識別子（例：test-automation-specialist） |
description |
Claudeが自動委譲すべきタイミングを具体的に書く |
tools |
Read, Grep, Glob, Bash など必要最小限に絞る |
model |
用途に応じてsonnet/haikuを選択 |
---
name: test-automation-specialist
description: >
コミット内容に変更があった場合、必ず使用する。
影響を受けるテストの特定、実行、失敗原因の分析、修正、再検証までを担当する。
tools: Read, Grep, Glob, Bash
model: sonnet
---
あなたはテスト自動化の専門家です。以下の手順で進めてください。
1. 変更分析：git diffの内容を確認し、影響を受けるテストファイルを特定する
2. テスト実行：関連するすべてのテストを実行する
3. 結果分析：失敗したテストがあれば原因を詳細に分析する
4. 修正実施：テストの意図を保持しながら、適切に修正する
5. 再検証：修正後のテストを再実行し、成功を確認する
❌ descriptionを「テストする」のように短く書いてしまうと、Claudeが自動で呼び出してくれないケースが多いです。
✅「〜の変更があったときに必ず使う」のように、トリガー条件を一文目に明記するのが◎です。
手順2：コミット時に自動起動するフックを設定する
.claude/settings.json（またはプロジェクト単位の設定ファイル）に、コミットをトリガーとするフックを追加します。これにより、コミット前後で自動的にtest-automation-specialistが起動し、テストの実行から修正までを自律的に行ってくれます。
フック経由でBashツールを許可すると、意図しないコマンドが実行されるリスクがあります。テスト実行に必要な最小限のコマンドだけを許可するように、権限設定を必ず確認してください。
手順3：テストコード生成をTDDサイクルに乗せる
テストの新規作成では、いきなり実装を頼むのではなく、Red→Green→Refactorのサイクルでサブエージェントに依頼すると精度が上がります。
以下の要件を満たすショッピングカート機能のテストを先に書いて：
商品を追加できる
同じ商品は数量が増える
商品を削除できる
合計金額を計算できる
このように要件を先にテストとして固めてから実装を依頼する流れにすると、境界値やエッジケースまで含めた網羅性の高いテストが生成されやすくなると私は感じています。
サブエージェント運用でさらに深掘りしたいポイント
ここまでで一連の自動化フローは完成ですが、実務で使い込むとさらに工夫できる余地が見えてきます。
役割ごとにサブエージェントを分ける
test-runnerだけでなく、code-reviewerやsecurity-reviewerなど役割ごとに分けておくと、判断がぶれにくくなります。
| サブエージェント | 主な役割 | 権限の目安 |
|---|---|---|
| test-runner | テスト実行・失敗分析・修正 | Read, Grep, Bash |
| code-reviewer | 差分レビュー | Read, Glob, Grep（Write/Edit拒否） |
| security-reviewer | 認証・決済周りの脆弱性チェック | Read, Grep, Bash |
◎ サブエージェントは増やすほど便利になるわけではありません。役割が重なるとどれに任せるべきか判断しづらくなるため、最初はレビュー・テスト・デバッグの3種類に絞るのが実務に乗せやすいと思います。
テスト結果の全文をメイン会話に流さない
テストの実行ログを丸ごとメイン会話に返すと、それだけでコンテキストが埋まってしまいます。サブエージェント側で「失敗したテストだけを抜き出して報告する」ように指示しておくと、メインセッションを圧迫せずに済みます。
半自動化という選択肢も検討する
「全部AIに任せる」のではなく、設計書のレビューは人間が承認し、実装フェーズだけをサブエージェントに任せる「半自動化」の運用も現場では効果的だと言われています。特にチーム独自の命名規則やスタイルは、実装フェーズであえて厳格に指示しないことで、ロジックの精度が落ちにくくなるケースもあるようです。
サブエージェントの結果をそのまま最終結論にしないことが重要です。優先順位や採用判断は、あくまでメイン会話（人間）が行うようにしましょう。
まとめ
- ✅
.claude/agents/にtest-runner系のサブエージェントを定義するのが自動化の第一歩 - ✅ descriptionにトリガー条件を明記すると自動委譲の精度が上がる
- ✅ コミット時フックと組み合わせれば「書く→実行→修正→再検証」が自律的に回る
- ◎ 役割ごとにサブエージェントを分け、権限は必要最小限に絞るのがおすすめ
- ❌ サブエージェントの結果を無条件に採用するのはNG。最終判断は人間が行う
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む