Agent Development

Claude Code プラグイン向けのエージェント開発

概要

エージェントは、複雑な複数段階のタスクを独立して処理する自律型のサブプロセスです。エージェントの構造、起動条件、システムプロンプトの設計を理解すると、強力な自律機能を作成できます。

主な概念：

• エージェントは自律的な作業向け、コマンドはユーザーが開始するアクション向けです
• YAML フロントマターを含む Markdown ファイル形式です
• description フィールドの例を使って起動します
• システムプロンプトでエージェントの動作を定義します
• モデルと色をカスタマイズできます

エージェントファイルの構造

完全な形式

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

フロントマターのフィールド

name（必須）

名前空間の設定と呼び出しに使用するエージェント識別子です。

形式： 小文字、数字、ハイフンのみ
長さ： 3～50 文字
パターン： 英数字で始まり、英数字で終わる必要があります

適切な例：

• code-reviewer
• test-generator
• api-docs-writer
• security-analyzer

不適切な例：

• helper（汎用的すぎます）
• -agent-（ハイフンで始まり、ハイフンで終わっています）
• my_agent（アンダースコアは使用できません）
• ag（短すぎます。3 文字未満です）

description（必須）

Claude がこのエージェントを起動するタイミングを定義します。最も重要なフィールドです。

含める必要があるもの：

1. 起動条件（「次の場合にこのエージェントを使用してください...」）
2. 使用方法を示す複数の <example> ブロック
3. 各例のコンテキスト、ユーザーリクエスト、アシスタントの応答
4. エージェントが起動する理由を説明する <commentary>

形式：

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

ベストプラクティス：

• 具体例を 2～4 個含めます
• 先回り型と応答型の起動を示します
• 同じ意図を異なる表現で示します
• commentary で理由を説明します
• エージェントを使用すべきでない状況を明確にします

model（必須）

エージェントが使用するモデルです。

選択肢：

• inherit - 親と同じモデルを使用します（推奨）
• sonnet - Claude Sonnet（バランス型）
• opus - Claude Opus（最も高性能、高コスト）
• haiku - Claude Haiku（高速、低コスト）

推奨： 特定のモデル機能が必要な場合を除き、inherit を使用します。

color（必須）

UI でエージェントを視覚的に識別する色です。

選択肢： blue、cyan、green、yellow、magenta、red

ガイドライン：

• 同じプラグイン内の異なるエージェントには、見分けやすい色を選びます
• 類似したタイプのエージェントには、一貫した色を使用します
• Blue/cyan：分析、レビュー
• Green：成功を重視するタスク
• Yellow：注意、検証
• Red：重大、セキュリティ
• Magenta：創造、生成

tools（任意）

エージェントが使用できるツールを制限します。

形式： ツール名の配列

tools: ["Read", "Write", "Grep", "Bash"]

デフォルト： 省略した場合、エージェントはすべてのツールを使用できます

ベストプラクティス： 必要最小限のツールに制限します（最小権限の原則）

一般的なツールセット：

• 読み取り専用の分析：["Read", "Grep", "Glob"]
• コード生成：["Read", "Write", "Grep"]
• テスト：["Read", "Bash", "Grep"]
• フルアクセス：フィールドを省略するか、["*"] を使用します

システムプロンプトの設計

Markdown 本文がエージェントのシステムプロンプトになります。エージェントに直接語りかける二人称で記述します。

構成

標準テンプレート：

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

ベストプラクティス

✅ 推奨事項：

• 二人称で記述します（「あなたは...です」「あなたは...します」）
• 責任範囲を具体的にします
• 手順を段階ごとに示します
• 出力形式を定義します
• 品質基準を含めます
• エッジケースに対応します
• 10,000 文字以内に収めます

❌ 避けること：

• 一人称で記述する（「私は...です」「私は...します」）
• 曖昧または汎用的な内容にする
• 手順を省略する
• 出力形式を未定義のままにする
• 品質に関する指針を省略する
• エラーケースを無視する

エージェントの作成

方法 1：AI を活用した生成

次のプロンプトパターンを使用します（Claude Code から抽出）：

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

その後、フロントマターを付けてエージェントファイル形式に変換します。

完全なテンプレートについては、examples/agent-creation-prompt.md を参照してください。

方法 2：手動作成

1. エージェント識別子を決めます（3～50 文字、小文字、ハイフン）
2. 例を含む description を記述します
3. モデルを選択します（通常は inherit）
4. 視覚的に識別するための色を選びます
5. ツールを定義します（アクセスを制限する場合）
6. 上記の構成に従ってシステムプロンプトを記述します
7. agents/agent-name.md として保存します

検証ルール

識別子の検証

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

ルール：

• 3～50文字
• 小文字、数字、ハイフンのみ
• 英数字で始まり、英数字で終わること
• アンダースコア、スペース、特殊文字は使用不可

説明の検証

長さ： 10～5,000文字
必須項目： トリガー条件と例
推奨： 例を2～4個含め、200～1,000文字

システムプロンプトの検証

長さ： 20～10,000文字
推奨： 500～3,000文字
構成： 明確な責任、プロセス、出力形式

エージェントの構成

プラグインのエージェントディレクトリ

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

agents/ 内のすべての .md ファイルが自動的に検出されます。

名前空間

エージェントには自動的に名前空間が付与されます：

• 単一のプラグイン：agent-name
• サブディレクトリがある場合：plugin:subdir:agent-name

エージェントのテスト

トリガーのテスト

エージェントが正しくトリガーされることを確認するため、テストシナリオを作成します：

1. 具体的なトリガー例を含むエージェントを作成する
2. テストでは例に似た表現を使う
3. Claude がエージェントを読み込むことを確認する
4. エージェントが期待される機能を提供することを確認する

システムプロンプトのテスト

システムプロンプトが完成していることを確認します：

1. エージェントに一般的なタスクを与える
2. プロセスの手順に従うことを確認する
3. 出力形式が正しいことを確認する
4. プロンプトに記載されたエッジケースをテストする
5. 品質基準が満たされていることを確認する

クイックリファレンス

最小限のエージェント

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

フロントマターのフィールド一覧

フィールド	必須	形式	例
name	はい	小文字とハイフン	code-reviewer
description	はい	テキスト＋例	Use when... ...
model	はい	inherit/sonnet/opus/haiku	inherit
color	はい	色名	blue
tools	いいえ	ツール名の配列	["Read", "Grep"]

ベストプラクティス

推奨事項：

• ✅ 説明に具体的な例を2～4個含める
• ✅ 具体的なトリガー条件を書く
• ✅ 特別な必要性がない限り、モデルには inherit を使う
• ✅ 適切なツールを選ぶ（最小権限）
• ✅ 明確で構造化されたシステムプロンプトを書く
• ✅ エージェントのトリガーを十分にテストする

禁止事項：

• ❌ 例を含めずに一般的な説明を使う
• ❌ トリガー条件を省略する
• ❌ すべてのエージェントに同じ色を設定する
• ❌ 不要なツールアクセスを許可する
• ❌ 曖昧なシステムプロンプトを書く
• ❌ テストを省略する

追加リソース

リファレンスファイル

詳細なガイダンスについては、以下を参照してください：

• references/system-prompt-design.md - システムプロンプトのパターンを網羅したガイド
• references/triggering-examples.md - 例の形式とベストプラクティス
• references/agent-creation-system-prompt.md - Claude Code が使用する正確なプロンプト

サンプルファイル

examples/ に実用的なサンプルがあります：

• agent-creation-prompt.md - AI 支援によるエージェント生成テンプレート
• complete-agent-examples.md - さまざまなユースケースに対応したエージェントの完全な例

ユーティリティスクリプト

scripts/ 内の開発ツール：

• validate-agent.sh - エージェントファイルの構造を検証する
• test-agent-trigger.sh - エージェントが正しくトリガーされるかテストする

実装ワークフロー

プラグイン用のエージェントを作成するには：

1. エージェントの目的とトリガー条件を定義する
2. 作成方法（AI 支援または手動）を選ぶ
3. agents/agent-name.md ファイルを作成する
4. 必須フィールドをすべて含むフロントマターを書く
5. ベストプラクティスに従ってシステムプロンプトを書く
6. 説明にトリガー例を2～4個含める
7. scripts/validate-agent.sh で検証する
8. 実際のシナリオでトリガーをテストする
9. プラグインの README にエージェントを記載する

自律的に動作できるよう、明確なトリガー条件と包括的なシステムプロンプトを重視してください。