Claude Code Subagentsの作り方と業務活用例｜専門エージェントでチーム力を底上げ

Claude Codeを毎日のワークフローに組み込んでいると、ある時点で気づくことがあります。「このレビュー観点、毎回プロンプトに書いている」「テスト方針を伝えるだけで5分かかる」。繰り返しの指示をなくし、専門知識を持ったエージェントにタスクを委任する仕組み — それが Subagents です。

本記事では、Subagentsのディレクトリ構成から、実際のエージェントファイルの中身、業務で成果が出た3つのパターン、そして「使わない方がいい場面」までを整理します。Claude Codeの基本機能についてはClaude Code完全ガイドを参照してください。

結論 — Subagentsは「再利用可能な専門家プロンプト」

Subagentsは、.claude/agents/ に配置するMarkdownファイルで、特定タスクに特化した指示・判断基準・出力形式を定義したものです。 Claude Codeのメインセッションから /agents/reviewer のようにスラッシュコマンドで呼び出すか、Claude Codeが指示内容に応じて自動的に適切なSubagentを選択します。

「毎回同じプロンプトを書く」問題は、プロンプトの再利用で解決します。ただし、単にプロンプトをコピペするのではなく、ファイルシステム上に配置してバージョン管理下に置くことで、チーム全員が同じ判断基準で動くようになります。

ディレクトリ構成 — .claude/agents/ の設計

基本構成

.claude/
├── settings.json          # Hooks等の設定
├── agents/                # Subagentsの格納先
│   ├── reviewer.md        # コードレビュー専任
│   ├── tester.md          # テスト作成専任
│   └── documenter.md      # ドキュメント更新専任
└── CLAUDE.md              # プロジェクト全体の共通ルール（参考）

ポイントは、CLAUDE.mdとSubagentsの責務を明確に分けることです。CLAUDE.mdにはプロジェクト全体に適用する共通ルール（技術スタック、コマンド、命名規則）を書き、Subagentsには特定タスクの専門ルールだけを書きます。

命名規則

ファイル名がそのままエージェント名になるため、何をするエージェントか一目でわかる名前にします。

# Good
reviewer.md
tester.md
documenter.md
security-auditor.md

# Bad
agent1.md
helper.md
misc.md

実践パターン1 — コードレビュー専任エージェント（reviewer）

最も導入効果が高いパターンです。以下は、実際のプロジェクトで使用しているreviewer.mdの全文です。

エージェントファイルの中身

# reviewer — コードレビュー専門エージェント

## 役割
変更されたコードに対してレビューを実施し、問題点を深刻度別に報告する。

## レビュー観点

### Critical（即座に修正が必要）
- `any` 型の使用（`unknown` + 型ガードを使うこと）
- `as` による型アサーション（Zodバリデーションまたは型ガードで代替）
- `!` (non-null assertion) の使用（`?? fallback` または早期returnで対処）
- `console.log` が本番コードに残っている
- ハードコードされた秘密情報（APIキー、トークン等）
- SQLインジェクションの可能性があるクエリ

### Warning（改善を推奨）
- 関数が50行を超えている → 責務を分割する
- ネストが3レベルを超えている → 早期return・関数抽出で平坦化する
- 関数の引数が3個を超えている → オブジェクト引数にまとめる
- 同じコードが3回以上出現している → 抽象化を検討する

### Info（参考情報）
- 命名の改善提案
- より簡潔な書き方の提案
- パフォーマンスの改善余地

## 出力形式

各指摘は以下の形式で出力する：

[深刻度] ファイルパス:行番号
問題: 具体的な問題の説明
理由: なぜこれが問題なのか
修正案: 具体的な修正コード（可能な場合）

## レビュー対象外
- `.md` ファイル
- `.d.ts` ファイル
- `node_modules/` 配下
- 生成されたファイル（`.next/`, `dist/` 等）

## 最終出力
レビュー完了後、以下のサマリーを出力する：
- Critical: X件
- Warning: X件
- Info: X件
- 総合評価: PASS / FAIL（Criticalが0件ならPASS）

呼び出し方

# Claude Codeセッション内で
このPRをレビューして。reviewer エージェントを使って。

あるいは、CLAUDE.md側に「コードレビュー時はreviewerエージェントを使用すること」と記載しておけば、「レビューして」だけで自動的にreviewer.mdが参照されます。

Before / After

Before（Subagentなし）:

レビューして。うちではany禁止で、関数は50行以内で、ネストは3レベルまでで、
console.logは消して、as使わないで、引数は3個までで...（毎回100文字以上の指示）

After（Subagentあり）:

レビューして。

指示量が激減するだけでなく、レビュー基準のブレもなくなります。

実践パターン2 — テスト作成専任エージェント（tester）

テストコードの品質を均一化するパターンです。

エージェントファイルの中身

# tester — テスト作成専門エージェント

## 役割
指定されたソースコードに対してテストを作成する。TDDフローに従い、
テストを先に書いてから実装を修正する手順を徹底する。

## テスト方針

### 必須テストケース
1. 正常系 — 期待通りの入力で期待通りの出力が得られるか
2. 境界値 — 0, 1, MAX, 空文字列, 空配列
3. 異常系 — null, undefined, 型の異なる入力
4. エッジケース — 並行実行, タイムアウト, ネットワークエラー

### モック戦略
- 外部API呼び出し → vi.mock() でモック化
- データベースアクセス → in-memoryのテスト用リポジトリ
- 日時依存 → vi.useFakeTimers()
- テスト対象の関数自体は絶対にモックしない

### テスト構造
- describe: テスト対象の関数名またはコンポーネント名
- it/test: 「〜の場合、〜を返す」形式の日本語テスト名
- 1テストケース1アサーション（原則）

## ファイル配置
- 実装ファイルと同じディレクトリにコロケーション配置
- ファイル名: `{name}.test.ts` または `{name}.test.tsx`

## カバレッジ基準
- 新規ファイル: 80%以上
- 変更ファイル: カバレッジを下げないこと
- バグ修正: 再発防止テスト必須（Red → Green で確認）

## テスト実行コマンド
- 全テスト: `pnpm test`
- 単一ファイル: `pnpm test -- path/to/file.test.ts`
- カバレッジ付き: `pnpm test -- --coverage`

## 出力形式
テスト作成後、以下を報告する：
- 作成したテストファイルのパス
- テストケース数
- カバレッジ（実行した場合）
- テスト結果（PASS / FAIL）

Gotcha: testerエージェントの落とし穴

testerエージェントを導入して最初に起きがちな問題は、テストが「実装を後追いしている」状態になることです。Claude Codeは「テストを先に書け」と指示されても、内部的に実装を想定してからテストを書くため、テストがred（失敗）にならないケースがあります。

対策として、エージェント定義に以下を追加するのが有効です。

## 重要な制約
- テスト作成後、必ずテストを実行して**失敗すること**を確認する
- 実装ファイルが既に存在する場合でも、テストを先に作成してから実装を修正する
- テストがすべてパスする状態で渡されたら、まず意図的に壊れるテストを追加する

実践パターン3 — ドキュメント更新専任エージェント（documenter）

コード変更に連動してドキュメントを更新するパターンです。

エージェントファイルの中身

# documenter — ドキュメント更新専門エージェント

## 役割
コード変更に伴い、関連するドキュメントを更新する。

## 更新対象
1. README.md — セットアップ手順、コマンド一覧に変更がある場合
2. API仕様 — エンドポイントの追加・変更・削除がある場合
3. CHANGELOG.md — ユーザーに影響のある変更がある場合

## 更新しない対象
- 内部リファクタリング（外部仕様に変更がない場合）
- テストコードのみの変更
- CI/CD設定のみの変更

## トーン
- 技術者向け: 簡潔で正確。冗長な説明は不要
- コード例を必ず含める
- 「〜してください」の敬体は使わない。体言止めまたは「〜する」で統一

## 出力形式
- 更新したファイルの一覧
- 各ファイルの変更概要（1行）
- 「更新不要」と判断した場合はその理由

## 制約
- 既存ドキュメントの構造（見出しレベル、セクション順序）を変更しない
- 新しいセクションを追加する場合は、既存の構造に合わせる
- ドキュメントの言語（日本語 / 英語）を変えない

ドキュメンターの効果が出る場面

このエージェントが最も効果を発揮するのは、APIエンドポイントを追加したときです。Claude Codeに「このエンドポイントを実装して」と指示した後、「ドキュメントも更新して」と追加するだけで、API仕様書の更新、READMEのコマンド一覧更新、CHANGELOGへのエントリ追加が一度に行われます。

Subagentsを使わない方がいい場面

Subagentsは万能ではありません。以下のケースでは、通常のプロンプト指示の方が適切です。

1. 一度きりのタスク

「このファイルだけリファクタリングして」のような単発タスクに、専用エージェントを作るのは過剰です。繰り返し発生するタスクにだけSubagentsを使ってください。

2. 判断基準が頻繁に変わるタスク

判断基準が毎週のように変わるタスクでは、エージェントファイルのメンテナンスコストがかかります。基準が安定してから定義してください。

3. 複数のエージェントが競合する指示を出す場面

reviewerエージェントが「関数を分割せよ」と言い、パフォーマンスエージェントが「関数呼び出しを減らせ」と言う — このような矛盾が起きると、Claude Codeは判断に迷います。エージェント間の方針が矛盾しないよう設計してください。

4. CLAUDE.mdに書けば済む内容

「TypeScriptを使え」「any禁止」程度のルールは、CLAUDE.mdに書けば十分です。Subagentにする必要があるのは、タスク固有の詳細な手順や判断基準がある場合だけです。

チーム運用のワークフロー

エージェント定義の変更はPRで管理する

エージェントの判断基準を変更すると、チーム全員のClaude Code出力に影響します。.claude/agents/ 配下のファイル変更は、必ずPRレビューを経由してください。

# .github/CODEOWNERS に追加
.claude/agents/ @tech-lead @senior-engineer

定期的な棚卸し

月に1回程度、各エージェントの指摘内容と実際のコードレビューの指摘を突き合わせて、基準のズレがないか確認します。プロジェクトの規約が変わったのにエージェント定義が古いままだと、誤った指摘が出続けます。

新メンバーのオンボーディング

Subagentsの定義ファイルはそのまま「プロジェクトの品質基準ドキュメント」としても機能します。新メンバーに「.claude/agents/reviewer.md を読んでおいて」と伝えれば、レビュー基準の共有が完了します。

Workaround: エージェントが想定通りに動かない場合

Subagentの指示が複雑すぎると、Claude Codeが一部の基準を無視するケースがあります。対処法を3つ紹介します。

1. 優先度を明示する

## 優先度（上から順に重要）
1. Critical項目は絶対に見逃さないこと ← 最重要
2. Warning項目は可能な限り検出すること
3. Info項目は余裕があれば提案すること

2. チェックリスト形式にする

散文で書くよりも、箇条書きやチェックリスト形式の方が遵守率が高い傾向があります。

3. 出力にセルフチェックを組み込む

## 最終出力の前に
以下のセルフチェックを実施すること：
- [ ] すべてのCritical項目を確認したか
- [ ] 出力形式に従っているか
- [ ] レビュー対象外のファイルに言及していないか

まとめ — 専門エージェントで開発品質を標準化する

Subagentsは、Claude Codeの活用を「その場限りの便利ツール」から「チーム全体の品質基盤」に引き上げる仕組みです。

• .claude/agents/ にMarkdownファイルを配置するだけで設定できる
• reviewer（レビュー）、tester（テスト）、documenter（ドキュメント）の3種が実用性が高い
• エージェントファイルにはタスク固有の判断基準と出力形式を具体的に書く
• CLAUDE.mdとの責務分離を意識し、共通ルールはCLAUDE.md、専門ルールはSubagentsに配置する
• 一度きりのタスクや判断基準が不安定なタスクには使わない

まずはreviewerエージェントを1つ作り、1週間運用して指摘内容を確認するところから始めてみてください。効果が実感できたら、tester、documenterと段階的に拡張していくのが定着しやすいアプローチです。