agent-development

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

概要

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

主な概念：

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

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

完全な形式

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

## When to invoke

[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]

**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. 典型的な起動シナリオの短い概要文
3. 詳細な実例が記載された、エージェント本文内の「起動するタイミング」セクションへの案内

形式：

Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.

ベストプラクティス：

• 概要文では、2～4 個の起動シナリオを挙げます
• プロアクティブ（アシスタント自身が呼び出す）とリアクティブ（ユーザーが要求する）の両方の起動方法を含めます
• 同じ意図を表すさまざまな言い回しを含めます
• エージェントを使用しない状況を明確にします
• 詳細なシナリオは本文の「起動するタイミング」に、説明文の箇条書きとして記載します

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
   - A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
  "systemPrompt": "You are..."
}

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

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

方法 2: 手動作成

1. エージェントの識別子を選択する（3〜50 文字、小文字、ハイフン）
2. 例を含む説明を書く
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 文字 必須: 起動条件と例 推奨: 200〜1,000 文字、2〜4 個の例

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

長さ: 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 [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
color: blue
---

You are an agent that [does X].

## When to invoke

- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]

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

Output: [What to provide]

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

Field	Required	Format	Example
name	Yes	lowercase-hyphens	code-reviewer
description	Yes	Prose triggers	Use when... Typical triggers include...
model	Yes	inherit/sonnet/opus/haiku	inherit
color	Yes	Color name	blue
tools	No	Array of tool names	["Read", "Grep"]

ベストプラクティス

DO:

• ✅ 説明文の中で 2〜4 個の起動シナリオを文章として挙げる
• ✅ 詳細な具体的シナリオは、本文の "When to invoke" セクションに箇条書きの文章として記述する
• ✅ 具体的な起動条件を書く
• ✅ 特別な理由がない限り、モデルには inherit を使う
• ✅ 適切なツールを選ぶ（最小権限の原則）
• ✅ 明確で構造化されたシステムプロンプトを書く
• ✅ エージェントの起動を十分にテストする

DON'T:

• ❌ 起動シナリオのない汎用的な説明を使う
• ❌ 起動条件を省略する
• ❌ すべてのエージェントに同じ色を割り当てる
• ❌ 不要なツールへのアクセス権を与える
• ❌ 曖昧なシステムプロンプトを書く
• ❌ テストを省略する

追加リソース

リファレンスファイル

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

• 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 個の起動シナリオを挙げ、本文の "When to invoke" セクションで詳述する
7. scripts/validate-agent.sh で検証する
8. 実際のシナリオで起動をテストする
9. プラグインの README にエージェントを文書化する

自律的な動作のために、明確な起動条件と包括的なシステムプロンプトに重点を置いてください。