【結論】再利用するSubagentはMarkdownファイルで作成する
Claude CodeのSubagentは、親エージェントから独立したコンテキストで調査や実装を担当し、最終結果だけを返す仕組みです。
プロジェクト固有の定義は「.claude/agents/」へ保存し、name、description、tools、modelをYAMLフロントマターで指定します。
同じ役割を繰り返し使うなら、毎回長い英語プロンプトを書くより定義ファイルへ固定した方が再現性が高まります。
mkdir -p .claude/agents
cat > .claude/agents/test-investigator.md <<'EOF'
---
name: test-investigator
description: テスト失敗の原因を調査し、修正前に根拠を報告する
tools: Read, Grep, Glob, Bash
model: inherit
---
テストを再現し、失敗箇所、原因、最小修正案を返してください。
明示的な依頼がない限りファイルは編集しません。
EOF具体的な手順・設定方法
-
定義ファイルを作成したらClaude Codeを起動します。
nameはディレクトリ全体で重複させず、descriptionには「いつ使うか」を書きます。
claude -
手動で確実に使わせたい場合は、プロンプト内でエージェント名を指定します。
メインスレッド自体をその役割で起動したい場合は「--agent」を利用できます。
claude --agent test-investigator
実践プロンプト / 活用テクニック
Subagentへ探索、親へ判断と統合を担当させると、長い検索ログで主会話が汚れません。
test-investigatorを使用して、npm testで失敗するテストを調査してください。
失敗を再現し、関連ファイルだけを読んでください。
返却内容は「再現手順」「根本原因」「影響範囲」「最小修正案」「追加すべき回帰テスト」の順にしてください。
この段階ではファイルを変更しないでください。注意点・よくあるエラーと対処法
-
「英語で指示した方が必ず高精度」という仕様はありません。
日本語でも、目的、制約、出力形式、変更可否を具体化すれば安定します。
-
Bashを許可したSubagentはコマンドを実行できます。
破壊的操作を避けるため、レビュー専用ならRead、Grep、Globだけに絞ってください。