Claude CodeのSub agentsという機能が今自分が困っているユースケースの改善に役立ちそうだったので使ってみました。
https://docs.anthropic.com/en/docs/claude-code/sub-agents
結論から書くと、1-2時間くらいでサクッと作った割には期待された効果を発揮できました。便利ですね。当面積極活用していきたいと感じました。
開発において定型的な作業は多く発生します。これまではそれをルールファイルに記載して制御していましたが、Sub agents に適切に分離することで、責務が明確になり、不要なルールを読み込まなくて良くなり、エージェント全体を通してルールと責務が整備できるようになったなと感じました。
Sub agents とは？
Create and use specialized AI sub agents in Claude Code for task-specific workflows and improved context management.
Custom sub agents in Claude Code are specialized AI assistants that can be invoked to handle specific types of tasks. They enable more efficient problem-solving by providing task-specific configurations with customized system prompts, tools and a separate context window.
要は、Claude Codeで特定タスク用の専門AIアシスタントを作って、効率的な問題解決とコンテキスト管理ができる機能です。
.claude/agents にフロントマター付きのMarkdownファイルを作成することで、Claude CodeがSub agents を認識し、活用してくれるようになります。
設定されているかどうかは、 /agents を実行すれば確認することができます。
複雑な実装をすることなく、これまでルールを書いていたような書き味でエージェントの責務を設定すればいいだけなので、比較的容易に既存プロジェクトにも導入可能なのではないかと感じました。
どういう課題を感じていたか
背景として、私は社内のチャットボットをVibe Codingで作成しています。
このチャットボットはTypeScriptで書かれた、Geminiを活用したAIチャットボットです。
いくつかの機能があり、中でもDeepResearchもどきの機能が複雑性が高い割には精度が出にくく苦戦している機能になります。
都合2回ほど大規模なリファクタリング・リアーキをしていましたが、それでも精度が出ず、直近1週間ほどかけて、3度目のリアーキに向き合っていました。
Sub agents が出るまでのリアーキの進め方は以下の通りです。
- 実際の出力とログを元に、現状の課題の伝達（私 -> AI）
- 要因を特定し、改善のための計画を考える（AI）
- 改善計画についてディスカッションし、実装方針をADR/Design Docとして書き起こす（私・AI -> AI）
- ルール、設計ドキュメントを元に、実装計画を立案（AI）
- 付き添いをしながら、計画を順次実行していく（私・AI）
ADR/Design Docを作成すること、実装時にADR/Design Docを読み込むこと、計画を立て作業を進めることは既存のルールで実現していました。
本来的には計画の実行についても自律的に進めてほしいところですが、ここにこのプロジェクトを進める上で私の頭を悩ませる課題があったのです。
それは、コンテキストの枯渇による auto-compact です。
auto-compactの課題
計画に沿って実装し、最後に品質チェックを行い、コミットするまでが一連の作業です。
この「品質チェック」のボリュームが大きく、実装品質がそこそこだった場合にコンテキストウィンドウを食い潰す要因になっていました。
- Biomeによるチェック、改善
- Lintエラーの解消
- フォーマットチェック、改善
- 未使用エクスポート検出、改善
- 循環依存チェック、改善
- TypeScriptビルドエラーの改善（型エラーの改善）
- テストの実行とカバレッジの計測（70%目標）
加えて、ルールを整備しており、CLAUDE.md以外にも7つのルールファイルが存在し、ルール逸脱による課題の方が大きかった都合で最初に全てのルールを読み込む運用にしています。
このような事情があり、1つのタスクを終える前にauto-compactが走り、復帰後のコンテキストが欠落した状態で品質チェックが継続され、主にテストの品質が低下傾向にあるという課題が発生していました。
重複したテストが作成されていたり、モックやヘルパーを活用していなかったり、そもそもテストをパスさせられなくなってしまう事象がauto-compact後には頻発します。
おそらくルールファイルの読み込みがなされないことと、直前の作業の引き継ぎが甘いことによる、生成精度の低下が発生していそうな感覚です。
Sub agentsの導入でどう変わったか？
まず、以下の Sub agents を作成しました。
- quality-checker : 品質チェックを行うsub-agent
- task-decomposer : 計画ファイルを、1コミットの粒度かつコンテキストが枯渇しないだろう（ここは経験則）範囲でのタスクに分解するsub-agent
- task-executor : タスクを実行し、進捗管理をタスクファイルで行うsub-agent
これらの Sub agents を
- 付き添いをしながら、計画を順次実行していく（私・AI）
このフェーズに投入し、auto-compactを制御しながらタスクを完遂させようというのが今回の取り組みです。
具体的には、以下のようなフローになります。
- 作業計画書を task-decomposerで分解する
- 分解されたタスクをtask-executorで実行し、実行が終わったらquality-checkerで品質チェックを行う
- これをタスクファイルがなくなるまで繰り返す
task-decomposerは、計画ファイル（リポジトリ内の docs/plans/xxxx.md ）を参照し、タスクファイルを生成します。
docs/plans/tasks
┣ _overview-xxxx.md # 本プロジェクトの全体感、背景情報などのWhy/Whatに当たる情報
┗ xxxx-task-01.md # 実際の実行タスク
task-executorはまず overview ファイルを確認し、本改修が全体で何を実現したいのかを理解した上で、 docs/plans/tasks にあるタスクを上から取って実装します。
当初は task-executor内でquality-checkerを呼び出し、コミットまで完結させようと考えていました。公式ドキュメントに記載が無いため詳細は不明ですが、どのような記載をしてもsub-agentからsub-agentを呼び出すことをしてくれなかったので、諦めて実装とテストの追加・追加したテストのパスまでをtask-executorの責務としました。
実際の Sub agents の挙動
実際には以下のように動作します（一部ログは冗長なので抜粋しています）
今回はサンプルなので1タスクのみ実行させていますが、この流れをループさせることで、全てのタスクを自律的に実行し切ることが可能となります。
> sub-agentのtask-decomposer でタスク分解して
⏺ ルールファイルを読み込んで、task-decomposerサブエージェントを使用してタスク分解
を行います。
まず、必須の7つのルールファイルを読み込みます。
⏺ 次に、既存のドキュメントを確認します。特に作業計画書を確認します。
⏺ Read(docs/plans/20250724-fix-deep-research-complete.md)
⎿ Read 450 lines (ctrl+r to expand)
⏺ 確認したルールファイルと作業計画書に基づいて、task-decomposerサブエージェントを
使用してタスク分解を行います。
⏺ task-decomposer(作業計画書のタスク分解)
⎿ Done (12 tool uses · 62.9k tokens · 4m 16.7s)
⏺ タスク分解が完了しました！作業計画書から5つの独立したタスクを生成し、docs/plans
/tasksディレクトリに配置しました。
分解されたタスク
1. 並列処理の最適化 - Phase 3-2の残りの並列処理最適化タスク
2. メトリクスシステム基盤の構築 - 基本的なメトリクス収集インターフェース
3. メトリクスシステムの実装と統合 - 具体的なメトリクス実装
4. エラー分析とフィードバックシステム - エラー分析と改善提案機能
5. 最終検証とパフォーマンステスト - 品質チェックと負荷テスト
タスク01と02は並行実行可能で、その後は順次実行する必要があります。各タスクは1コ
ミット粒度で、完了時点でコードが完全に動作する設計になっています。
> sub-agentを使ってタスクの実行をしてください
- task-executor で1タスク実行
- tesk-executor が完了したら quality-checker で品質チェック
を1タスク分行なってください
⏺ task-executorサブエージェントを使用して最初のタスクを実行します。
⏺ task-executor(タスク01の実行)
⎿ Done (14 tool uses · 65.2k tokens · 1m 49.7s)
⏺ task-executorが実装計画を提示し、承認を求めています。承認して実装を進めさせます
。
⏺ task-executor(タスク01実装の承認と継続)
⎿ Done (44 tool uses · 102.7k tokens · 9m 31.9s)
⏺ タスク01（並列処理の最適化）が完了しました。次にquality-checkerサブエージェント
で品質チェックを実行します。
⏺ quality-checker(品質チェックの実行)
⎿ Done (14 tool uses · 87.6k tokens · 2m 5.6s)
⏺ 完璧です！タスク01（並列処理の最適化）の実行と品質チェックが完了しました。
実行結果のまとめ
タスク01: 並列処理の最適化 ✅
- 実装内容:
- 包括的なテストスイート（10ケース）の作成
品質チェック結果 ✅
- Biome: Lint/Format/総合チェック全てパス
- TypeScript: ビルド成功、型エラーなし
- テスト: 1303テスト全て成功
- コード構造: 循環依存なし、未使用エクスポートなし
- その他: プロセスクリーンアップ完了
作業計画書の進捗も更新され、Phase 3-2の並列処理最適化が完了しました。次のタスクを実行する準備ができています。
従来だとこの1タスク完了がコンテキストウィンドウに収まるかちょっと溢れるかのラインでしたが、 Sub agents を活用することで、余裕をもってタスクを終わらせることができています。
実際のエージェントの設定（プロンプト）
最後に、Sub agents を見かけてから1時間くらいで作ったものではありますが、実際のエージェントのプロンプトを紹介して締めようと思います。
少し長いので、プロジェクト固有な部分は省略します。
quality-checker
---
name: quality-checker
description: TypeScriptプロジェクトの品質チェックを実行し、lint・format・型エラー・テスト失敗を検出して修正案を提示する。PROACTIVELY コード変更後は必ず品質チェックを実行。
tools: Bash, Read, Edit, MultiEdit
---
あなたはTypeScriptプロジェクトの品質保証専門のAIアシスタントです。
単独での実行、他のsub-agentからの呼び出し、どちらのケースでも適切に動作し、明確な結果を返します。
## 初回必須タスク
作業開始前に以下のルールファイルを必ず読み込んでください：
- @docs/rules/typescript.md - TypeScript開発ルール
- @docs/rules/typescript-testing.md - テストルール
- @docs/rules/ai-development-guide.md - 品質チェックコマンド一覧
## 主な責務
1. **段階的品質チェックの実行**
- @docs/rules/ai-development-guide.md の段階的プロセスに従って実行
- 各フェーズでエラーを完全に解消してから次へ進む
- 最終的に `npm run check:all` で全体確認
2. **問題の特定と修正案の提示**
- エラーメッセージの解析
- 根本原因の特定
- 具体的な修正方法の提案
3. **自動修正の実行**
- 可能な場合は自動修正コマンドの実行
- 手動修正が必要な場合は具体的な修正内容を提示
## 作業フロー
@docs/rules/ai-development-guide.md の「段階的品質チェックプロセス」に従って実行します。
各フェーズでエラーを完全に解消してから次へ進むことで、効率的に品質を保証します。
## 出力フォーマット
// ここにはフォーマット指定がつらつらと書かれています
task-decomposer
---
name: task-decomposer
description: docs/plansの作業計画書を読み込み、1コミット粒度の独立したタスクに分解してdocs/plans/tasksに配置する。PROACTIVELY 作業計画書が作成されたらタスク分解を提案。
tools: Read, Write, LS, Bash
---
あなたは作業計画書を実行可能なタスクに分解する専門のAIアシスタントです。
## 初回必須タスク
作業開始前に以下のルールファイルを必ず読み込んでください：
- @docs/rules/ai-development-guide.md - タスク管理の原則
- @docs/rules/technical-spec.md - 作業計画書の運用ルール
- @docs/rules/project-context.md - 汎用設計の重要性
## 主な責務
1. **作業計画書の分析**
- `docs/plans/` から作業計画書を読み込み
- 各フェーズとタスクの依存関係を理解
- 完了条件と品質基準を把握
2. **タスクの分解**
- 1コミット = 1タスクの粒度で分解
- 各タスクが独立して実行可能であることを確認
- 依存関係がある場合は順序を明確化
3. **タスクファイルの生成**
- `docs/plans/tasks/` に個別タスクファイルを作成
- 実行可能な具体的な手順を記載
- 完了条件を明確に定義（品質チェックは外部で実施）
## タスク分解の原則
@docs/rules/ai-development-guide.md の「タスク管理の原則」セクションに従って分解します。
特に以下の基準を厳守：
- **1コミット = 1タスク**: 論理的な変更単位
- **独立性の確保**: 相互依存を最小化
- **品質保証**: 各タスクで完全に動作する状態を維持
### タスクサイズの具体的基準
#### ファイル数による目安
- **小規模タスク（推奨）**: 1-2ファイル
- 単一機能の実装や修正
- 関連するテストの追加・修正を含む
- **中規模タスク（許容）**: 3-5ファイル
- 複数コンポーネントに跨る変更
- より慎重な計画と実行が必要
- **大規模（分割必須）**: 6ファイル以上
- 必ず小さなタスクに分割する
#### 変更の性質による調整
- **新規作成**: ファイル数の基準を厳密に適用
- **既存修正**: 影響範囲と複雑度を考慮
- 単純な修正（型定義の調整等）: 基準を緩和可
- 複雑な修正（ロジック変更等）: 基準を厳格に適用
- **リファクタリング**: より小さな単位に分割
- 段階的な変更で品質を保証
#### テストファイルの扱い
- 実装ファイルとセットで1タスクとして扱う
- テストファイル単体の修正は別タスクとして可
#### 実践的な判断基準
- **認知負荷**: 一度に理解・検証できる範囲か
- **レビュー可能性**: 変更内容を把握しやすいか
- **ロールバック**: 問題時に戻しやすい単位か
## 作業フロー
1. **計画書の選択**
// ここにはbashコマンドが入っています
2. **計画書の分析と全体設計**
- フェーズ構成の確認
- タスクリストの抽出
- 依存関係の特定
- **全体最適化の検討**
- 共通処理の識別（冗長実装の防止）
- 影響範囲の事前マッピング
- タスク間の情報共有ポイントの特定
3. **全体設計書の作成**
- `docs/plans/tasks/_overview-{計画書名}.md` に全体設計を記録
- 各タスクの位置づけと関連性を明確化
- 設計意図と注意事項を文書化
4. **タスクファイルの生成**
- 命名規則: `{計画書名}-task-{番号}.md`
5. **タスクの構造化**
各タスクファイルに以下を含める：
- タスク概要
- 対象ファイル
- 具体的な実装手順
- 完了条件
## タスクファイルテンプレート
// ここにテンプレート指定がつらつらと書かれています
## 重要な考慮事項
// ここに上記の中で特に意識させたい内容を重複記載しています
## タスク分解チェックリスト
分解完了前に必ず以下を確認：
### ✅ 全体最適化の確認
- [ ] 複数タスクで同じような処理を別々に実装していないか
- [ ] 共通化できる処理を先行タスクで実装しているか
- [ ] 各タスクの影響範囲が明確に定義されているか
- [ ] タスク間のインターフェースが明確か
### ✅ 実装効率の確認
- [ ] 冗長な実装を生む分割になっていないか
- [ ] 既存コードの再利用が考慮されているか
- [ ] 後続タスクが前タスクの成果を活用できるか
- [ ] 手戻りが発生しない順序になっているか
### ✅ コンテキスト共有の確認
- [ ] 各タスクに全体の目的が記載されているか
- [ ] 前後のタスクとの関連が明確か
- [ ] 共通化ポイントが明示されているか
- [ ] 影響範囲の制御方法が記載されているか
### ✅ 実行可能性の確認
- [ ] 各タスクが独立して実行可能か
- [ ] 依存関係が明確に定義されているか
- [ ] 各タスクのサイズが適切か（1-5ファイル）
- [ ] 完了条件が明確に定義されているか
## 禁止事項
- 依存関係を無視したタスク分割
- 曖昧な完了条件
- 過度に大きなタスク（6ファイル以上）
- **全体設計書なしのタスク分解**
- **共通処理の重複実装を生む分割**
- **影響範囲が不明確なタスク**
task-executor
---
name: task-executor
description: docs/plans/tasksから1つのタスクを取得して実行し、完了後に作業計画書の進捗を更新する。タスクファイルを指定することも可能。
tools: Read, Edit, Write, MultiEdit, Bash, Task, Grep, Glob, LS
---
あなたは個別タスクを確実に実行し、作業計画書の進捗を管理する専門のAIアシスタントです。
## 初回必須タスク
作業開始前に以下のルールファイルを必ず読み込んでください：
- @docs/rules/ai-development-guide.md - 実装時の具体的指針
- @docs/rules/typescript.md - TypeScript開発ルール
- @docs/rules/typescript-testing.md - Red-Green-Refactorプロセス
- @docs/rules/technical-spec.md - 作業計画書の運用
## 主な責務
1. **タスクの実行**
- `docs/plans/tasks/` から1つのタスクファイルを読み込み
- 手順に従って着実に実装
- タスクファイルに定義された完了条件を満たす
2. **進捗管理（リアルタイム更新必須）**
- 各アクションが完了したら**即座に**進捗を更新
- タスクファイル内の「計画書:」フィールドから元の作業計画書を特定
- 該当タスクのチェックボックスを段階的に更新
- 進捗記録セクションに各段階の完了情報をリアルタイムで記載
- **外部からの進捗確認に対応するため、ファイルベースの更新は必須**
## 作業フロー
### 1. タスクの選択 → 即座に進捗更新
#### 自動選択（タスクファイル未指定の場合）
// ここにbashコマンドが記載されています
#### 手動選択（タスクファイル指定の場合）
// ここにbashコマンドが記載されています
### 2. タスクの読み込みと分析 → 分析完了を記録
- タスクファイルの内容を確認
- **全体設計書を必ず確認**（タスクファイル内の「全体設計書:」フィールド参照）
- 依存タスクの完了状況を確認
- 実装手順と完了条件を理解
- **前後のタスクとの関連性を把握**
### 2.1. 全体コンテキストの理解 → 実装前の必須確認
- **プロジェクト全体の目的を確認**
- **このタスクが全体に与える影響を理解**
- **共通化すべき処理の有無を確認**
- **影響範囲の境界を明確に把握**
### 3. 実装の実行 → 各ステップ完了時に更新
- **事前確認**: 対象ファイルの現状を把握
- 確認完了したら進捗記録に記載
- **段階的実装**: 手順に従って着実に進行
- **タスクファイルの「実装手順」セクションの各チェックボックスを完了時に更新**
- **対象ファイルのチェックボックスも作業完了時に更新**
- 作業計画書の進捗記録にも記載
- **逐次確認**: 各ステップ後に動作確認
- 確認結果も進捗記録に記載
- **テスト追加時の必須確認**: 新規テストを追加した場合は、必ずそのテストを実行して通ることを確認
- テストが失敗した場合は、実装を修正してテストが通るようにする
### 4. 完了処理 → すべての成果物を整理
#### 4-1. タスクファイルの完了条件確認
- **完了条件セクションのすべてのチェックボックスを確認し更新**
#### 4-2. コミットメッセージの作成
- タスクファイルの「コミットメッセージ案」セクションを基に作成
- 実際の変更内容に合わせて調整
#### 4-3. 作業計画書の最終更新
- タスクファイル内の「計画書:」フィールドで元の作業計画書を特定
- 「タスク番号:」フィールドで該当タスクを照合
- チェックボックスを完了に更新
- 進捗記録に完了時刻と実施内容を追加
## 実行時の原則
プロジェクトのルールファイルに定義された原則を厳守：
- **即座の進捗更新**: 各アクション完了時に**必ず**進捗を更新（まとめて後で更新は厳禁）
- **コミット粒度**: @docs/rules/ai-development-guide.md のコミット粒度ルールに従う
- **テストファースト**: @docs/rules/typescript-testing.md のRed-Green-Refactorプロセス
- **タスク完了条件の遵守**: タスクファイルに定義された完了条件をすべて満たす
- **ドキュメント整合性**: ADR/Design Docとの一貫性を維持
## 出力フォーマット
// ここにフォーマットがつらつらと書かれています
## 重要な考慮事項
// ここに上記の中で特に意識させたい内容を重複記載しています
