Agents スペック設計 — サブエージェントの定義と活用
読了 10分 ＋ 実践 30分
エージェント（Agents）を設計すると、Claude Code は「汎用 AI」ではなく「特定の責務を持つ専門家チーム」として機能するようになります。このページでは、エージェントファイルのフォーマット・description の書き方・ツール制限・model 選択を、このプロジェクトの shared/agents/ の実例を参照しながら学びます。
エージェントとは何か
Section titled “エージェントとは何か”エージェント（Agent）とは、Claude SDK の Agent ツールで起動される、独立した会話コンテキストを持つサブプロセスです。エージェントはメインの会話とは切り離された「独立したサブ会話」として動作し、指定されたツールのみを使って特定のタスクを完遂します。
エージェントを活用する主な理由は2つあります。第一に、責務の分離です。ドキュメント作成・コードレビュー・i18n 同期といった異なるタスクを、それぞれ専門のエージェントに委任できます。第二に、ツールの制限です。エージェントごとに使用可能なツールを限定することで、意図しない副作用を防げます。
Commands・Skills・Agents の三角形
Section titled “Commands・Skills・Agents の三角形”ハーネスの三つの主要コンポーネントは、それぞれ異なる役割を持ちます。
| 観点 | Commands | Skills | Agents |
|---|---|---|---|
| トリガー | ユーザーが /command と入力 | ユーザーまたは Claude | Claude SDK の Agent ツールで起動 |
| 役割 | 決まった作業を実行する手順書 | 動作を変更する指示書 | 特化した専門家として機能 |
| ツール | Claude のデフォルトツール | Claude のデフォルトツール | 指定したツールのみ |
| 文脈 | メイン会話内 | メイン会話内 | 独立したサブ会話 |
| ファイル場所 | shared/commands/ | shared/skills/ | shared/agents/ |
エージェントは三者の中で最も独立性が高く、最も強い権限制御ができます。
エージェントファイルのフォーマット
Section titled “エージェントファイルのフォーマット”エージェントファイルは frontmatter とボディで構成されます。
frontmatter の構造
Section titled “frontmatter の構造”---
name: エージェント名
description: エージェントの説明（何をするか、いつ使うか）
tools: Read, Edit, Write, Bash, Glob, Grep
model: sonnet
---各フィールドの意味は次のとおりです。
name: エージェントを識別する ID。ファイル名（.mdを除く）と一致させますdescription: Claude がどのエージェントを起動すべきか判断するために読む説明文。最も重要なフィールドですtools: このエージェントが使用できるツールの一覧。記載したツールのみ使用可能で、未記載のツールはブロックされますmodel: 使用するモデル。sonnet・opus・haikuから選択します
ボディの構造
Section titled “ボディの構造”frontmatter の後に、エージェントへの指示をそのまま Markdown で書きます。
---
name: docs-content
description: ドキュメント記事（src/content/docs/）の作成・更新・構造整合性を担当する。docs ページを追加・編集する際に積極的に使う。
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
---
AI Learning Playground のドキュメント専門エージェントです。
## 役割
- `src/content/docs/` 配下の英語・日本語ドキュメントを作成・更新する
- frontmatter の整合性を維持する
## 手順
1. CLAUDE.md と SKILL.md を確認する
2. 対象ファイルを特定する
3. 日本語ページを先に作成・更新する
## ルール
- 個人の経験談・感情表現を使用しない
- 日本語がソース・オブ・トゥルースこのプロジェクトの shared/agents/docs-content.md がこの形式の実例です。
description の重要性
Section titled “description の重要性”description は Claude が「どのエージェントを起動すべきか」を判断するために読む唯一のフィールドです。description の品質がエージェント選択の精度を直接左右します。
効果的な description の書き方
Section titled “効果的な description の書き方”description には「何をするか」に加えて、「いつ使う」を明示することが重要です。
# 良い例: 「いつ使う」が明確
description: ドキュメント記事（src/content/docs/）の作成・更新・構造整合性を担当する。docs ページを追加・編集する際に積極的に使う。
# 改善の余地あり: 「いつ使う」が不明確
description: ドキュメントを書くエージェント。「いつ使わない」条件も description に含めると、誤った起動をさらに防げます。
description: セキュリティレビューを担当する。コード変更後に PR のセキュリティチェックを行う際に積極的に使う。ドキュメント作成・コードの新規実装には使わない。ベストプラクティス
Section titled “ベストプラクティス”1エージェント1責務
Section titled “1エージェント1責務”「何でもできる汎用エージェント」より、特化した専門エージェントの集合体を設計します。このプロジェクトでは次のように責務を分離しています。
| エージェント | 担当領域 |
|---|---|
docs-content | ドキュメント記事の作成・更新 |
blog-content | ブログ記事の作成・更新 |
i18n-sync | 日英の i18n 同期 |
pr-review | PR のコードレビュー |
test-verify | テスト・検証 |
code-implementation | コード実装 |
ツールは最小限に
Section titled “ツールは最小限に”エージェントに必要以上のツールを与えません。
# 良い例: 読み取り専用の操作のみ必要なエージェント
tools: Read, Glob, Grep
# 避けるべき例: 実際には使わない Write・Bash を含める
tools: Read, Edit, Write, Glob, Grep, Bashツールを絞ることで、エージェントが意図しないファイルを書き換えるリスクを排除できます。
model は用途に合わせる
Section titled “model は用途に合わせる”| モデル | 適したケース |
|---|---|
haiku | 高速・大量処理。テキスト分類・単純な変換 |
sonnet | バランス型。ほとんどの開発タスク |
opus | 複雑な判断・アーキテクチャ設計・難しいバグの解析 |
重い判断が不要なエージェントに opus を使うと、コストと応答時間が不必要に増加します。
shared/agents/ に置いてシムリンク
Section titled “shared/agents/ に置いてシムリンク”エージェントファイルは shared/agents/ に置きます。.claude/agents/ はこのディレクトリへのシムリンクなので、shared/agents/ を編集するだけで Claude Code ツールに即座に反映されます。
Step 1: 既存エージェントの一覧を確認する
Section titled “Step 1: 既存エージェントの一覧を確認する”ls shared/agents/出力例：
blog-content.md
code-implementation.md
docs-content.md
i18n-sync.md
pr-review.md
test-verify.md✅ 確認: 複数のエージェントファイルが表示されれば、エージェント層が正しく配置されています。
Step 2: エージェントスペックの構造を確認する
Section titled “Step 2: エージェントスペックの構造を確認する”cat shared/agents/docs-content.mdfrontmatter の name・description・tools・model と、ボディの「役割」「手順」「ルール」セクションを確認します。
✅ 確認:
tools: Read, Edit, Write, Glob, Grep, Bashのような記述が frontmatter に含まれていれば、ツール制限が正しく定義されています。
Step 3: 新しいエージェント shared/agents/security-review.md を作成する
Section titled “Step 3: 新しいエージェント shared/agents/security-review.md を作成する”セキュリティレビュー専門のエージェントを新規作成します。
shared/agents/security-review.md の内容：
---
name: security-review
description: セキュリティレビューを担当する。コード変更後に PR のセキュリティチェックを行う際に積極的に使う。OWASP Top 10、認証・認可の問題、シークレットの漏洩リスクを中心にチェックする。
tools: Read, Glob, Grep, Bash
model: sonnet
---
セキュリティレビュー専門エージェントです。
## 役割
- 変更されたコードのセキュリティリスクを評価する
- OWASP Top 10 に基づいて脆弱性を確認する
- シークレットの漏洩リスクを検出する
## 手順
1. 変更されたファイルを確認する
2. セキュリティリスクをチェックする
3. 問題点と推奨修正を報告する
## ルール
- 実際のシークレットを出力しない
- 問題がない場合でもその旨を明示する✅ 確認:
cat shared/agents/security-review.mdを実行して内容が表示されれば作成成功です。
Step 4: エージェントが起動されることを確認する
Section titled “Step 4: エージェントが起動されることを確認する”Claude Code のセッションで次のように依頼します。
セキュリティレビューを実行してClaude が security-review エージェントを選択して起動し、ファイルの読み取りとセキュリティチェックを実行することを確認します。
✅ 確認: Claude の応答に「security-review エージェントを起動します」または同等の記述が含まれれば、description に基づく自動選択が機能しています。
- エージェントは独立したサブ会話として動作し、指定ツールのみを使って特定タスクを実行する
descriptionは Claude がエージェント選択を判断する唯一の手がかり。「いつ使う」「いつ使わない」を含めることで選択精度が上がるtoolsは必要最小限に絞り、意図しない副作用を防ぐmodelは用途に応じて選択する（haiku / sonnet / opus）- エージェントファイルは
shared/agents/に置く。.claude/agents/のシムリンクが自動で反映する
次のステップ
Section titled “次のステップ”- Hooks 実装 — ツール実行前後にシェルコマンドを挟むフック設定を学ぶ
- ハーネスのテストと検証 — エージェントが意図通りに機能するかを体系的に検証する方法へ進む
よくある質問
Section titled “よくある質問”Q: エージェントとスキルはどちらを使うべきですか？
A: タスクを「独立したプロセスとして委任したい」場合はエージェント、「同じ会話の中で Claude の振る舞いを変えたい」場合はスキルを使います。エージェントはツールを制限できるため、副作用を厳密に管理したいタスクに適しています。
Q: エージェントは自動的に選ばれますか、手動で指定することもできますか？
A: Claude SDK の実装によって異なりますが、description フィールドを適切に書くことで Claude が自動的に適切なエージェントを選択します。特定のエージェントを確実に起動させたい場合は、ユーザーが「〇〇エージェントを使って」と明示的に指定することもできます。
Q: 一つのタスクに複数のエージェントを連携させることはできますか？
A: できます。たとえば「i18n-sync エージェントで翻訳を同期し、その後 pr-review エージェントでレビューする」という連携が可能です。ただし、エージェント間でデータを受け渡す仕組みは Claude SDK の実装に依存するため、連携パターンを設計する前に SDK のドキュメントを確認することを推奨します。
Q: tools フィールドを省略するとどうなりますか？
A: ツール制限が適用されず、Claude のデフォルトツールがすべて使用可能になります。セキュリティや副作用の観点から、エージェントには明示的に tools を指定することを推奨します。
このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]
- Anthropic, Claude Code documentation
- Anthropic, Claude API documentation