Claude Code Subagents 再入門 ~cc-sddの実装で学んだこと~

Claude CodeのSubagentsを再入門。Subagentsが独自のコンテキストウィンドウを利用するために起きるコンテキスト損失という落とし穴を軸に、READ系の適材適所、Write系の設計注意、エージェント数の最小化と明確なdescription、巨大文脈のファイル委任、Taskツールのログ読解まで。cc-sdd 2.0のSubagents版実装で培った実戦知見を共有する。

Transcript

1. Claude Code Subagents 再入門
 ~cc-sdd Subagents版の実装で学んだこと~
 Gota (@gota_bara)
 
 2025/10/17 : Claude Code Meetup Tokyo 

2. 自己紹介
 Gota (@gota_bara) 所属 データアナリスト & エージェントエンジニア やってること ⼩売向けデータプロダクト / AIエージェント開発 / データ整備 興味 AI × 体験 / ⾳声AI / DSPy / 🏕(夏以外) / アニメ 仕様駆動開発ツール「cc-sdd」 1.5kも⾒えてきた！ 2
3. • Brownfield開発に対応するた めのcommandsを⽤意 仕様駆動開発ツール cc-sdd2.0 alpha
 6エージェント対応 • Claude Code / Codex / Gemini CLI / Cursor / Github Copilot / Qwen Code • Claude CodeはSubagentsも 対応 テンプレート機能 (独⾃) • 各仕様書をチームのワークフ ローのテンプレートに置き換 え可能！ 既存開発対応 • 調査フェーズを含めたDesign Docs作成が可能 • 設計と実装のフィードバックループを回せる！ 要求定義 詳細設計 タスク分解 実装 (TDD) Steering Specs (Kiro⽅式) ‧cc-sddのGithub: https://github.com/gotalab/cc-sdd 3
4. 今日はcc-sddの話はしません！

5. Claude Code Subagents使ってますか？

6. Subagents とは？ 公式ドキュメントは神！まず全部目を通すべし 
 サブエージェントは、Claude Codeがタスクを委任できる事前設定されたAIパー ソナリティです。各サブエージェントは： • 特定の⽬的と専⾨分野を持つ • メインの会話とは独⽴した独⾃のコンテキストウィンドウを使⽤する • 使⽤を許可された特定のツールで設定できる • その動作を導くカスタムシステムプロンプトを含む Claude Codeがサブエ ージェントの専⾨分野に⼀致するタスクに遭遇すると、そ のタスクを専⾨のサブエージェントに委任でき、サブエージェントは独⽴して作 業し結果を返します。 引⽤: https://docs.claude.com/ja/docs/claude-code/sub-agents 6
7. Subagentsのトラップ
 メインの会話とは独⽴した独⾃のコンテキストウィンドウを使⽤する メインエージェント サブエージェント Task()ツール で委任 完了 実⾏結果が 返ってくる 会話の流れ @subagent or ⾃律選択 毎回新しいセッションで起動 7
8. Subagentsのトラップ
 • サブエージェント委任の際に毎回コンテキスト断裂が起こる • コンテキストが引き継がれないことを前提にメインエージェントとサブエー ジェントの両⽅の⼊出⼒を設計する必要がある メインエージェント サブエージェント 完了 会話の流れ 独⽴したコンテキスト サブエージェントに委任するタ スクに必要⼗分なコンテキスト を委任する メインエージェントが今後の判 断に必要⼗分なコンテキストを 返す必要がある オーケストレータ 8
9. Subagentsに委任すべきタスクは何か？
 1. メインエージェントのコンテキストを汚染させたくないタスク ◦ エラーログ解析...プロセスじゃなく結果をくれ！ ◦ Research系全般...良く分からんドキュメントは不要 2. 並列で⾏いたい検索タスク ◦ コンテキスト検索...Explore agentがデフォルトで追加！ ◦ Web検索/ドキュメント検索... 3. コンテキストを引き継ぐべきではないタスク ◦ レビュー ◦ 検証 トークン消費の⼤きいRead系タスクはSubagentsと⾮常に相性が良い！ 9
10. 書き込み系タスクのSubagents化は慎重に行う
 コンテキスト損失がモロに品質に影響する 1. Write(ファイル書き込み)系タスクはコンテキスト損失がない⽅が良いのでメ インエージェントにやらせるのが向いている。Subagents化するなら必要な コンテキストを全て渡すような設計にする 2. 書き込み系タスクをSubagentsで担保しようとすると、重複したコンテキス ト読み込みを⾏う必要があり、無駄なトークン消費が増えるので注意 10
11. Subagentsが自律的に動かないときのTips
 最初は公式ドキュメントから: https://docs.claude.com/ja/docs/claude-code/sub-agents
12. Tips1. 設定するサブエージェントを最小限にする
 • Claude Code起動時にSubagentsのnameとdescriptionが読み込まれるた め、MCPサーバーと同じく無駄なトークン消費が発⽣する 126個のSubagentsを設定すると+15kのトーク ン数を消費 12
13. Tips2. descriptionはSubagentsを一意になるよう明確に！
 • Subagentsを⼀意に特定できるようなdescriptionを記載する (Claude Skills もここは同様) .claude/agents配下に作成されたXX.md Subagentsのメタデータが読み込まれる 13
14. Tips3. 馬鹿みたいにでかいコンテキストはファイルで委任
 • 全部のコンテキストをテキストで送るとトークンエラーになりがち • タスク委任時で必要なコンテキストはファイルで授受することで、メイン エージェントのコンテキスト汚染も防げる cc-sddの /spec-requirements コマンドのSubagents への委任もファイルで委任する 14
15. Tips99. Taskツールのログを見に行く
 • ~/.claude/projects/配下の各プロジェクト内にあるjsonlを解読する！ • “isSidechain”: falseとtrue間にTaskで委任されたコンテキストと出⼒がある 15
16. まとめ
 • Subagentsはコンテキスト汚染防⽌でREAD系タスクでの利⽤ならスムーズ！ • cc-sdd Subagents版も使ってね！ cc-sddのGithub 質問等あればお気軽に連絡ください！ 
 X: @gota_bara
 16