Claude Codeの設定 - サブエージェントのソースを表示

== 概要 ==
Claude Codeのサブエージェント機能は、特定のタスクに特化したAIアシスタントを作成し、親エージェントと子エージェントに分けて推論させることにより、<br>
効率的な開発ワークフローを構築する機能である。<br>
<br>
サブエージェントは以下に示す特徴を持つ。<br>
* 独立したコンテキストウィンドウ (各エージェントが200kトークン) を持つ
* カスタムシステムプロンプトによる専門化
* 特定のツールへのアクセス制限
* 独立した権限管理
* 異なるモデルの使用 (Opus、Sonnet、Haiku等)
<br>
サブエージェントを使用することにより、以下に示すメリットが得られる。<br>
* コンテキストの保持
*: 探索と実装を分離し、メインの会話を汚さない
* 制約の強制
*: サブエージェントが使用できるツールを制限することで安全性を向上
* 設定の再利用
*: ユーザレベルのサブエージェントをプロジェクト間で共有
* 行動の特殊化
*: 特定ドメインに焦点を当てたシステムプロンプト
* コストの制御
*: 高速で安価なモデル (Haiku) へのタスクルーティング
<br>
[[ファイル:Claude Code Settings Subagents Structure 1.png|フレームなし|中央|653x500px]]
<br><br>

== サブエージェントの基本構造 ==
サブエージェントは、YAMLフロントマターを持つMarkdownファイルとして定義される。<br>
<br>
==== サブエージェント定義の基本要素 ====
* name
*: サブエージェントの識別子
*: これは、kebab-caseに自動変換される。
* description
*: いつこのサブエージェントを使用すべきかを記述する。
*: これは、親エージェントがこれを読んで判断する。
* tools
*: サブエージェントが使用できるツールのリスト
*: <code>Read</code>
*: <code>Write</code>
*: <code>Edit</code>
*: <code>Bash</code>
*: <code>Grep</code>
*: <code>Glob</code>
*: その他
* model
*: 使用するモデル
*: <code>inherit</code>
*: <code>claude-sonnet-4-5-20250929</code>
*: <code>claude-haiku-4-5-20251001</code>
*: その他
* システムプロンプト
*: サブエージェントの役割、手順、チェックリスト等を記述
<br>
==== サブエージェント定義ファイルの配置場所 ====
* プロジェクトレベル
*: <code>.claude/agents/</code> (チーム全体で共有)
* ユーザレベル
*: <code>~/.claude/agents/</code> (全プロジェクトで使用可能)
<br><br>

== サブエージェントの作成手順 ==
==== ステップ 1 : Claude Codeのバージョン確認 ====
サブエージェント機能を使用するには、Claude Code 1.0.60以降が必要である。<br>
 claude --version
<br>
最新バージョンでない場合は更新する。<br>
 claude update
<br>
==== ステップ 2 : サブエージェント作成コマンドの実行 ====
Claude Codeセッションを開始して、サブエージェント作成コマンドを実行する。<br>
 /agents
<br>
このコマンドを実行すると、以下に示す選択肢が表示される。<br>
* Create new agent
* Edit existing agent
* Delete agent
* List all agents
<br>
[Create new agent]を選択し、スコープを選択する。<br>
* Project-level
*: プロジェクト固有のサブエージェント
* User-level
*: 全プロジェクトで使用可能なサブエージェント
<br>
初めての場合は、プロジェクトレベルを選択することを推奨する。<br>
<br>
==== ステップ 3 : サブエージェントの生成方法を選択 ====
サブエージェントの生成方法を選択する。<br>
* Generate with Claude
*: Claudeが自動生成
* Create manually
*: 手動作成
<br>
[Generate with Claude]を選択すると、Claudeがプロジェクトのコンテキストを使用して最適なサブエージェントを生成する。<br>
<br>
==== ステップ 4 : サブエージェントの役割を説明 ====
Claudeに対して、作成するサブエージェントの役割と責任を説明する。<br>
<br>
 # 説明例 :
 
 コードの品質、セキュリティ、保守性をチェックする専門のコードレビューアーを作成したい。
 このエージェントは、コード変更後に自動的に呼び出され、重要な問題、警告、改善提案を優先順位付けして報告する必要がある。
</pre>
<br>
==== ステップ 5 : 生成されたサブエージェントの確認と編集 ====
Claudeがサブエージェント定義を生成した後、生成されたMarkdownファイルを開いて確認する。<br>
<br>
 # 生成されたファイルの例 :
 
 .claude/agents/code-reviewer.md
<br>
ファイルの内容を確認し、必要に応じて編集する。<br>
<br>
==== ステップ 6 : サブエージェントのテスト ====
サブエージェントが正しく動作するかテストする。<br>
<br>
 # 自動呼び出しのテスト :
 
 このコードをレビューしてください: @src/auth.js
<br>
 # 明示的な呼び出しのテスト :
 
 code-reviewerエージェントを使用して、認証モジュールをチェックしてください
<br><br>

== サブエージェントの定義例 ==
==== コードレビュー専門エージェント ====
コードの品質とセキュリティをチェックするサブエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .claude/agents/code-reviewer.md
<br>
 <syntaxhighlight lang="md">
 ---
 name: code-reviewer
 description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
 tools: Read, Grep, Glob, Bash
 model: inherit
 ---
 
 あなたはコード品質とセキュリティの高い基準を保証するシニアコードレビューアーです。
 
 呼び出されたとき:
 1. git diffを実行して最近の変更を確認する
 2. 変更されたファイルに焦点を当てる
 3. 即座にレビューを開始する
 
 レビューチェックリスト:
 - コードが明確で読みやすいか
 - 関数と変数が適切に命名されているか
 - 重複したコードがないか
 - 適切なエラーハンドリングがあるか
 - シークレットやAPIキーが露出していないか
 - 入力検証が実装されているか
 - 適切なテストカバレッジがあるか
 - パフォーマンスの考慮がされているか
 
 フィードバックを優先順位で整理して提供:
 - 重要な問題 (必ず修正すべき)
 - 警告 (修正すべき)
 - 提案 (改善を検討)
 </syntaxhighlight>
<br>
==== デバッグ専門エージェント ====
エラーとバグの診断と修正を行うサブエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .claude/agents/debugger.md
<br>
 <syntaxhighlight lang="md">
 ---
 name: debugger
 description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
 tools: Read, Edit, Bash, Grep, Glob
 model: claude-haiku-4-5-20251001
 ---
 
 あなたは根本原因分析を専門とするエキスパートデバッガーです。
 
 呼び出されたとき:
 1. エラーメッセージとスタックトレースをキャプチャ
 2. 再現手順を特定
 3. 障害箇所を分離
 4. 最小限の修正を実装
 5. 解決策が機能することを検証
 
 デバッグプロセス:
 - エラーメッセージとログを分析
 - 最近のコード変更を確認
 - 仮説を形成しテスト
 - 戦略的にデバッグログを追加
 - 変数の状態を検査
 
 各問題に対して以下を提供:
 - 根本原因の説明
 - 診断を裏付ける証拠
 - 具体的なコード修正
 - テストアプローチ
 - 予防に関する推奨事項
 </syntaxhighlight>
<br>
==== アーキテクチャレビュー専門エージェント ====
システム設計とアーキテクチャの評価を行うサブエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .claude/agents/architect-reviewer.md
<br>
 <syntaxhighlight lang="md">
 ---
 name: architect-reviewer
 description: Architecture and design review specialist. Use when designing new features or making significant structural changes.
 tools: Read, Grep, Glob
 model: claude-sonnet-4-5-20250929
 ---
 
 あなたはソフトウェアアーキテクチャとデザインパターンの専門家です。
 
 呼び出されたとき:
 1. 既存のアーキテクチャパターンを調査
 2. 提案された変更の影響を評価
 3. スケーラビリティと保守性を考慮
 4. ベストプラクティスとの整合性を確認
 
 評価観点:
 - システム全体の一貫性
 - モジュール間の依存関係
 - スケーラビリティの考慮
 - 保守性とテスタビリティ
 - セキュリティアーキテクチャ
 - パフォーマンスへの影響
 
 提供する内容:
 - アーキテクチャ上の懸念事項
 - 代替アプローチの提案
 - トレードオフの分析
 - 実装の推奨事項
 </syntaxhighlight>
<br>
==== FPGA / Verilog専門エージェント ====
Verilog HDLとFPGA設計のレビューを行うサブエージェントの定義例を以下に示す。<br>
<br>
* ファイル名の例
*: .claude/agents/verilog-reviewer.md
<br>
 <syntaxhighlight lang="md">
 ---
 name: verilog-reviewer
 description: Verilog/FPGA design review specialist. Use when reviewing or creating Verilog code, or working on FPGA designs.
 tools: Read, Grep, Glob
 model: claude-sonnet-4-5-20250929
 ---
 
 あなたはVerilogとFPGA設計の専門家です。
 
 呼び出されたとき:
 1. Verilogコードの文法と構造を確認
 2. 合成可能性を評価
 3. タイミング制約を検証
 4. リソース使用効率を分析
 
 レビュー観点:
 - タイミング制約の妥当性
 - リソース使用効率 (LUT、FF、BRAM、DSP)
 - クロックドメインクロッシングの安全性
 - 合成可能なコーディングスタイル
 - テストベンチの網羅性
 - 状態機械の設計
 - パイプライン設計の最適化
 
 指摘内容:
 - 致命的な問題 (合成不可、タイミング違反等)
 - 警告 (リソース使用効率、可読性等)
 - 最適化提案 (パフォーマンス改善等)
 </syntaxhighlight>
<br><br>

== サブエージェントの呼び出し方法 ==
==== 自動呼び出し ====
親エージェントは、各サブエージェントの description</code> フィールドを読んで、現在のタスクに適したサブエージェントを自動的に選択する。<br>
<br>
 # 自動呼び出しの例 :
 
 このコードをレビューしてください: @src/auth.js
<br>
上記のようなリクエストを行うと、親エージェントは自動的にcode-reviewerサブエージェントを呼び出す。<br>
<br>
==== 明示的な呼び出し ====
プロンプトの中でサブエージェントの名前を指定することで、確実にそのサブエージェントを使用できる。<br>
<br>
 # 明示的な呼び出しの例 1 :
 
 code-reviewerエージェントを使用して、認証モジュールをチェックしてください
<br>
 # 明示的な呼び出しの例 2 :
 
 debuggerエージェントを使用して、このエラーを修正してください: @logs/error.log
<br>
==== サブエージェントの状態確認 ====
現在利用可能なサブエージェントを確認する。<br>
 /agents
<br>
このコマンドにより、以下に示す情報が表示される。<br>
* サブエージェント名
* スコープ (project または user)
* 説明
* 使用可能なツール
* 使用するモデル
<br><br>

== サブエージェント間の連携パターン ==
==== 順次実行パターン ====
複数のサブエージェントを順次実行し、段階的にタスクを完了するパターンである。<br>
<br>
実行フローの例を以下に示す。<br>
# ユーザがタスクを親エージェントに依頼
# 親エージェントがarchitect-reviewerを呼び出して設計を評価する。
# 設計が承認されたら、implementerサブエージェントが実装を行う。
# 実装が完了したら、code-reviewerサブエージェントが品質をチェックする。
# 問題が見つかった場合、debuggerサブエージェントが修正を行う。
# 全てのチェックが通過したら、結果を親エージェントに返す。
<br>
==== 並列実行パターン ====
複数のサブエージェントを並列に実行し、効率的に複数のタスクを処理するパターンである。<br>
<br>
 # 使用例 :
 
 以下のタスクを並列で実行してください。
 
 1. Web Documentation Agentを使用して、公式ドキュメントを検索
 2. Stack Overflow Agentを使用して、類似の問題と解決策を検索
 3. Codebase Explorer Agentを使用して、既存のパターンを検索
<br>
==== Hooks による自動連携 ====
Claude Code Hooksを使用することにより、サブエージェントの実行完了時に次のアクションを自動的にトリガーできる。<br>
<br>
Hooksは、<u>.claude/hooks/</u> ディレクトリにJSON形式で定義される。<br>
<br>
基本的なHook定義の例を以下に示す。<br>
 <syntaxhighlight lang="json">
 {
   "type": "SubagentStop",
   "command": "echo '次のステップ: code-reviewerエージェントを実行してください'"
 }
 </syntaxhighlight>
<br>
Hooksを設定するには、以下に示すコマンドを実行する。<br>
このコマンドにより、Hooks設定を管理できる。<br>
 /hooks
<br><br>

== コンテキストウィンドウの管理 ==
==== 独立したコンテキストウィンドウ ====
各サブエージェントは独立した200kトークンのコンテキストウィンドウを持つ。<br>
これにより、以下に示す利点が得られる。<br>
* 子エージェントが大量のドキュメントを読み込んでも、親エージェントのコンテキストを消費しない
* 各エージェントが独立して作業できるため、並列処理が可能
* メインの会話が常にクリーンな状態を保てる
<br>
==== コンテキストの受け渡し ====
子エージェントは、作業が完了すると要約された結果だけを親エージェントに返す。<br>
<br>
コンテキスト受け渡しの流れ:<br>
# 親エージェントがタスクの概要と必要な情報を子エージェントに渡す
# 子エージェントが独立したコンテキストウィンドウ内で作業を実行
# 子エージェントが要約された結果を親エージェントに返す
# 親エージェントが結果を統合してユーザに提示
<br>
この仕組みにより、メインのコンテキストウィンドウは常にクリーンに保たれ、本来のタスクに集中できる。<br>
<br>
==== コンテキスト管理のベストプラクティス ====
* サブエージェントのシステムプロンプトには、必要な文脈情報をすべて含める
* サブエージェントには状態の記憶がないため、各呼び出しは独立している
* 長時間の調査タスクは、専用のリサーチエージェントに委譲する
* 実装タスクと調査タスクを分離し、それぞれ専用のサブエージェントに割り当てる
<br><br>

== サブエージェントのカスタマイズ ==
==== ツールの制限 ====
サブエージェントに対して、使用できるツールを制限することで、安全性を向上できる。<br>
<br>
<center>
{| class="wikitable"
|+ 利用可能なツール一覧
! ツール名 !! 機能 !! 使用推奨エージェント
|-
| Read || ファイルの読み取り || 全てのサブエージェント
|-
| Write || 新規ファイルの作成 || 実装エージェント、ドキュメント生成エージェント
|-
| Edit || 既存ファイルの編集 || 実装エージェント、バグ修正エージェント
|-
| Bash || シェルコマンドの実行 || デバッグエージェント、テストエージェント
|-
| Grep || ファイル内容の検索 || 調査エージェント、レビューエージェント
|-
| Glob || ファイルパターンマッチング || 調査エージェント、リファクタリングエージェント
|}
</center>
<br>
ツール制限の例:<br>
* コードレビューアー: Read、Grep、Glob、Bash (git diff用) のみ
*: コードを変更できないため、誤ってコードを修正するリスクがない
<br>
* デバッガ: Read、Edit、Bash、Grep、Glob
*: バグを修正するため、Editツールが必要
<br>
* リサーチエージェント: Read、Grep、Glob のみ
*: 調査のみを行い、コードを変更しない
<br>
==== モデルの選択 ====
サブエージェントごとに異なるモデルを使用することで、コストと性能のバランスを最適化できる。<br>
<br>
<center>
{| class="wikitable"
|+ モデル選択のガイドライン
! タスクタイプ !! 推奨モデル !! 理由
|-
| 簡単なバグ修正、コード補完 || claude-haiku-4-5-20251001 || 高速で低コスト
|-
| コードレビュー、実装 || claude-sonnet-4-5-20250929 || バランスの取れた性能
|-
| アーキテクチャ設計、複雑な問題 || claude-opus-4-20250514 || 最高の推論能力
|-
| 親エージェントと同じモデルを使用 || inherit || デフォルト設定
|}
</center>
<br>
モデル指定の例を以下に示す。<br>
 <syntaxhighlight lang="md">
 ---
 name: quick-fixer
 description: Quick bug fixes and simple code changes
 tools: Read, Edit, Bash
 model: claude-haiku-4-5-20251001
 ---
 </syntaxhighlight>
<br>
==== システムプロンプトのカスタマイズ ====
サブエージェントのシステムプロンプトには、プロジェクト固有のルール、コーディング規約、使用している技術スタックの情報等を含めることができる。<br>
<br>
カスタマイズ項目の例:<br>
* プロジェクト固有のコーディング規約
* 使用しているフレームワークとライブラリ
* チェックリストと評価基準
* 出力フォーマットの指定
* コンテキスト探索の手順
<br>
カスタマイズ例を以下に示す。<br>
 <syntaxhighlight lang="md">
 ---
 name: react-component-reviewer
 description: React component code review specialist
 tools: Read, Grep, Glob
 model: claude-sonnet-4-5-20250929
 ---
 
 あなたはReactコンポーネントのコードレビュー専門家です。
 
 プロジェクト環境:
 - React 18.2 + TypeScript 5.0
 - 状態管理: Zustand
 - スタイリング: Tailwind CSS
 - テスト: Jest + React Testing Library
 
 レビュー基準:
 - 関数コンポーネントとHooksを使用
 - propsの型定義を必須とする
 - useEffectの依存配列を正確に指定
 - カスタムHooksで再利用性を高める
 - コンポーネントは200行以内に抑える
 
 出力フォーマット:
 1. 重要な問題 (型エラー、パフォーマンス問題等)
 2. 警告 (ベストプラクティス違反等)
 3. 提案 (リファクタリング案等)
 </syntaxhighlight>
<br><br>

== 使用例 ==
==== 新機能の実装フロー ====
新機能を実装する場合のサブエージェント活用フローを以下に示す。<br>
<br>
===== ステップ 1 : 要件の明確化 =====
ユーザが親エージェントに新機能の実装を依頼する。<br>
<br>
 # 例 :
 
 ユーザ認証機能を追加したい。JWTトークンを使用した実装をお願いします。
<br>
===== ステップ 2 : アーキテクチャレビュー =====
親エージェントがarchitect-reviewerサブエージェントを自動的に呼び出し、既存のコードベースとの整合性を確認する。<br>
<br>
architect-reviewerの実行内容:<br>
* 既存の認証パターンを調査
* プロジェクトの技術スタックを確認
* セキュリティ要件を評価
* 設計の承認または代替案の提示
<br>
===== ステップ 3 : 実装 =====
設計が承認されたら、implementerサブエージェントが実際のコード実装を行う。<br>
<br>
implementerの実行内容:<br>
* 認証ミドルウェアの作成
* JWTトークン生成・検証ロジックの実装
* ユーザ登録・ログインエンドポイントの作成
* テストコードの作成
<br>
===== ステップ 4 : コードレビュー =====
実装が完了すると、code-reviewerサブエージェントが自動的に呼び出され、コード品質をチェックする。<br>
<br>
code-reviewerの実行内容:<br>
* コードの可読性を確認
* セキュリティ脆弱性をチェック
* エラーハンドリングを検証
* テストカバレッジを評価
<br>
===== ステップ 5 : バグ修正 (必要に応じて) =====
問題が見つかった場合、debuggerサブエージェントが呼び出され、問題を修正する。<br>
<br>
debuggerの実行内容:<br>
* 問題の根本原因を特定
* 最小限の修正を実装
* 修正の検証
<br>
===== ステップ 6 : 結果の統合 =====
全てのチェックが通過すると、最終的な結果が親エージェントに返され、ユーザーに報告される。<br>
<br>
==== 大規模リファクタリング ====
75個のファイルで使用されている関数を非推奨にして、新しい関数に置き換える場合の例を以下に示す。<br>
<br>
===== 実行手順 =====
# 親エージェントがgrepを使用して、全ての使用箇所を特定する。
# 各ファイルに対して専用のサブエージェントをスピンアップする。
# 各サブエージェントが小さく安全なコンテキストで置換を実行する。
# 親エージェントが全ての変更を集約してレビューする。
<br>
このパターンのメリット:<br>
* 各ファイルの変更が独立したコンテキストで実行される。
* 並列処理により高速化
* エラーが発生しても他のファイルに影響しない。
<br>
==== ドキュメント生成 ====
大規模で未ドキュメント化されたモジュールのドキュメントを生成する場合の例を以下に示す。<br>
<br>
===== 実行手順 =====
# 親エージェントが全ての関数、クラス、ファイルをリスト化
# 各項目に対してサブエージェントをスピンアップ
# 各サブエージェントがコードを分析し、包括的なコメントまたはダイアグラムを作成
# 最終的なサブエージェントが全てを統合してREADME.mdファイルにまとめる
<br>
このパターンのメリット:<br>
* 大量のコードを分析してもメインのコンテキストが汚れない。
* 各コンポーネントの詳細な分析が可能
* 最終的な統合により一貫性のあるドキュメントが生成される。
<br>
==== インシデント対応分析 ====
3つのマイクロサービスにまたがる障害を理解する場合の例を以下に示す。<br>
<br>
===== 実行手順 =====
# 各サービスに対して専用のサブエージェントを使用
# 各サブエージェントが並列でログを分析
# 各サブエージェントが重要なイベントのタイムラインを抽出
# 親エージェントが全てのタイムラインを統合して根本原因を特定
<br>
このパターンのメリット:<br>
* 並列処理により高速な分析
* 各サービスの詳細な分析が可能
* 複数のサービスにまたがる問題の全体像を把握
<br><br>

== サブエージェントの設計原則 ==
==== 単一責任の原則 ====
各サブエージェントには1つの明確な目標、入力、出力、ハンドオフルールを与える。<br>
<br>
 # 良い例 :
 
 description: Use after a spec exists; produce an ADR and guardrails
<br>
 # 悪い例 :
 
 description: Help with coding tasks
<br>
==== アクション指向の説明 ====
descriptionフィールドはアクション指向の表現を使用する。<br>
<br>
 # 良い例 :
 
 - "Use immediately after writing or modifying code"
 - "Use proactively when encountering any issues"
 - "Use when designing new features or making significant structural changes"
<br>
 # 悪い例 :
 - "A code reviewer"
 - "Helps with debugging"
 - "Architecture expert"
<br>
==== ツールのスコープ設定 ====
各エージェントに必要なツールのみを与える。<br>
<br>
* PM & Architect
*: Read、Grep、Glob (読み取り専用)
* Implementer
*: Read、Write、Edit、Bash (実装とテスト用)
* Release
*: 必要最小限のツールのみ
<br>
ツールを省略すると、全てのツールへのアクセスが暗黙的に許可されるため、意図的に制限することが重要である。<br>
<br>
==== 適切な数のサブエージェント ====
サブエージェントは多くても3から4個程度に抑えることを推奨する。<br>
<br>
* あまり多くのサブエージェントを作成すると、管理が複雑になる。
* どのエージェントを使用すべきか判断が難しくなる。
* 親エージェントの判断負荷が増加する。
<br><br>

== コンテキスト管理のベストプラクティス ==
==== 自己完結型のプロンプト ====
サブエージェントには状態の記憶がないため、システムプロンプトには必要な文脈情報を全て含める。<br>
<br>
含めるべき情報は以下の通りである。<br>
* プロジェクトの技術スタック
* コーディング規約
* ファイル構造
* チェックリスト
* 出力フォーマット
<br>
==== コンテキスト探索の最適化 ====
サブエージェントが呼び出された時に探索するファイルを限定することで、パフォーマンスを向上できる。<br>
<br>
探索最適化の例を以下に示す。<br>
 <syntaxhighlight lang="md">
 呼び出されたとき、まず以下を確認:
 - `lib/*/repo.ex` - データベース設定
 - `priv/repo/migrations/` - 既存のマイグレーションパターン
 - `lib/*/schemas/` - 現在のスキーマ定義
 
 パフォーマンス注意事項:
 - 初期のコンテキスト収集を制限
 - 特定のgrepパターンを使用
 - 関連するファイルに焦点を当てる
 </syntaxhighlight>
<br>
==== Definition of Doneの設定 ====
各サブエージェントのプロンプトに簡潔な完了定義を含める。<br>
<br>
 # 例 :
 
 完了条件:
 - 全てのテストがパス
 - コードレビューで承認
 - ドキュメントが更新済み
 - DONE状態を設定して変更をサマリー
<br><br>

== バージョン管理との統合 ==
==== Gitワークフローの推奨 ====
サブエージェントをバージョン管理と併用することを強く推奨する。<br>
<br>
# 各重要な変更の後にコミットするようClaudeに依頼する。
# ブランチを作成して機能ごとに分離する。
# Pull Requestの作成を自動化する。
<br>
 # 例 :
 
 新しいブランチ 'feature-xyz' を作成して、これらの変更をコミットしてください。
<br>
==== 設定ファイルのバージョン管理 ====
プロジェクトレベルのサブエージェント定義は、バージョン管理システムに含めることを推奨する。<br>
<br>
バージョン管理に含めるファイル:<br>
* .claude/CLAUDE.md
*: プロジェクトメモリ
* .claude/agents/*.md
*: サブエージェント定義
* .claude/hooks/*.json
*: Hooks設定
* .claude/settings.json
*: プロジェクト設定
<br>
バージョン管理から除外するファイル:<br>
* .claude/settings.local.json
*: 個人設定
* .claude/cache/
*: キャッシュデータ
<br>
.gitignoreの例:<br>
 <syntaxhighlight lang="sh">
 # Claude Code local settings
 
 .claude/settings.local.json
 .claude/cache/
 </syntaxhighlight>
<br><br>

== パフォーマンス最適化 ==
==== ファイルパスの具体的な指定 ====
具体的なファイルパスを提供することで、Claudeがより効率的に作業できる。<br>
<br>
 # 良い例 :
 
 @src/auth/middleware.js のセキュリティ脆弱性をチェックしてください
<br>
 # 悪い例 :
 
 認証コードをチェックしてください
<br>
==== 並列実行の活用 ====
複数のClaude Codeインスタンスを並行実行することで、効率を向上できる。<br>
<br>
並列実行の例:<br>
* ターミナル1
*: フロントエンドの開発
* ターミナル2
*: バックエンドAPIの開発
* ターミナル3
*: テストの実行とデバッグ
<br>
==== コンテキストのコンパクション ====
定期的にコンテキストをコンパクション (圧縮) することにより、トークン消費を抑制できる。<br>
<br>
コンパクションのタイミング:<br>
* 機能が完成した後
* バグが修正された後
* 新しいタスクを開始する前
<br>
 # コンパクションの実行 :
 
 /compact
<br>
 # 焦点を指定したコンパクション :
 
 /compact focus on authentication logic
<br><br>

== トラブルシューティング ==
==== サブエージェントが動作しない場合 ====
===== 設定ファイルの確認 =====
サブエージェントの定義ファイルが正しい場所に配置されているか確認する。<br>
<br>
* プロジェクトレベル
*: .claude/agents/
* ユーザレベル
*: ~/.claude/agents/
<br>
===== YAMLフロントマターの確認 =====
YAMLフロントマターが正しく記述されているか確認する。<br>
<br>
* 必須フィールド<br>
** name
** description
** tools
*: <br>
* 確認コマンド
*: /agents
<br>
このコマンドで全てのサブエージェントがリスト表示される。<br>
定義したサブエージェントが表示されない場合、YAMLフロントマターに問題がある可能性がある。<br>
<br>
===== Claude Codeセッションの再起動 =====
サブエージェント定義を変更した後、Claude Codeセッションを再起動する。<br>
<br>
# <code>/exit</code> または [Ctrl] + [D]キーでセッションを終了する。
# <code>claude</code> コマンドで再起動する。
<br>
===== システムの健全性確認 =====
システムの健全性を診断する。<br>
このコマンドにより、インストールタイプとバージョンが表示され、問題がないか確認できる。<br>
 /doctor
<br>
==== サブエージェントが期待通りに動作しない場合 ====
===== descriptionフィールドの見直し =====
descriptionフィールドが明確で具体的であるか確認する。<br>
<br>
親エージェントはdescriptionを読んで判断するため、以下を含める必要がある。<br>
* いつ使用すべきか
* 何をするエージェントか
* どのような状況で呼び出すべきか
<br>
===== ツール制限の確認 =====
サブエージェントに必要なツールが含まれているか確認する。<br>
<br>
* バグを修正するエージェントにはEditツールが必要
* コマンドを実行するエージェントにはBashツールが必要
* ファイルを読むエージェントにはReadツールが必要
<br>
===== システムプロンプトの見直し =====
システムプロンプトに必要な文脈情報が含まれているか確認する。<br>
<br>
サブエージェントには状態の記憶がないため、各呼び出しは独立している。<br>
必要な情報は全てシステムプロンプトに含める必要がある。<br>
<br>
==== Hooksが動作しない場合 ====
===== JSON構文の確認 =====
Hooks設定ファイルのJSON構文が正しいか確認する。<br>
<br>
 # 確認コマンド :
 jq . .claude/hooks/subagent-stop.json
<br>
このコマンドでJSON構文エラーが表示される。<br>
<br>
===== Hooksの再読み込み =====
設定を変更した後、Claude Codeの設定を再読み込みする。<br>
<br>
# <code>/config</code> コマンドで設定インターフェースを開く。
# 変更を確認して適用する。
# セッションを再起動する。
<br>
===== Hook出力の確認 =====
Hook出力が表示されない場合、STDOUT (標準出力) に出力されているか確認する。<br>
<br>
<code>/dev/tty</code> ではなく、STDOUTに出力する必要がある。<br>
<br>
===== SubagentStopとStopの両方を登録 =====
Hooksが読み込まれない場合、SubagentStopとStopの両方を登録する。<br>
<br>
トップレベルオブジェクトを1つ保持し、変更を確認して適用することで、ランタイムがHooksを再読み込みする。<br>
<br><br>

== 参考リンク ==
* [https://code.claude.com/docs/en/sub-agents Claude Code公式ドキュメント - Subagents]
* [https://www.pubnub.com/blog/best-practices-for-claude-code-sub-agents/ PubNub - Best practices for Claude Code subagents]
* [https://github.com/VoltAgent/awesome-claude-code-subagents VoltAgent - Awesome Claude Code Subagents]
* [https://shipyard.build/blog/claude-code-subagents-guide/ Shipyard - Claude Code Subagents Quickstart]
* [https://platform.claude.com/docs/en/agent-sdk/subagents Anthropic - Subagents in the SDK]
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Claude Code,Subagents,AI,Anthropic,Development,Programming,SUSE,Linux
|description={{PAGENAME}} - Claude Codeのサブエージェント機能に関する手順
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]