agent-builder

エージェントビルダー

Claude Code でカスタムエージェントを作成するための包括的なガイドです。エージェントは独立したコンテキストウィンドウで動作する専門特化型の AI アシスタントで、タスクに集中して自律的に実行できます。

---

クイックリファレンス

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

フィールド	必須	説明
name	はい	一意の識別子（小文字とハイフン）
description	はい	呼び出すタイミング — 検出可能性を左右する重要な項目
tools	いいえ	使用可能なツール（省略した場合はすべて継承）
model	いいえ	haiku、sonnet、opus、または inherit
permissionMode	いいえ	default、acceptEdits、bypassPermissions、plan
skills	いいえ	エージェントの起動時に Skills を自動読み込み

ファイルの場所

スコープ	場所	用途
プロジェクト	.claude/agents/agent-name.md	チームのワークフロー（git で共有）
個人	~/.claude/agents/agent-name.md	個人での使用（すべてのプロジェクト）

よく使われるツールのパターン

# Read-only (safest)
tools: Read, Grep, Glob

# File modification
tools: Read, Write, Edit, Grep, Glob

# Git operations only
tools: Bash(git:*)

# Specific commands
tools: Bash(npm test:*), Bash(npm run:*), Read, Grep

# Full shell (use sparingly)
tools: Bash

モデル選択ガイド

モデル	最適な用途	トレードオフ
haiku	簡単な確認、単純なタスク	高速で安価ですが、能力は控えめです
sonnet	バランスの取れた作業（デフォルト）	バランスに優れています
opus	複雑な分析、重要なタスク	最も高性能ですが、低速で高価です
inherit	メインの会話との一貫性	ユーザーのモデルに適応します

---

6 フェーズのワークフロー

フェーズ 1：要件の確認

ユーザーが必要としていることを把握するため、AskUserQuestion を使用します。

主な質問：

1. このエージェントにどのようなタスクを担当させますか？
2. どのような専門知識や役割を持たせますか？
3. 誰が使用しますか — チームですか、個人ですか？
4. 何を実行できるようにし、何を実行できないようにしますか？
5. 結果をどのように提示しますか？

質問の例：

What specific task should this agent handle?
├── Code review (quality, security, style)
├── Debugging (error investigation, root cause)
├── Testing (run tests, fix failures)
├── Documentation (generate, verify, update)
└── Other: [describe]

Who will use this agent?
├── Just me (personal: ~/.claude/agents/)
├── My team (project: .claude/agents/)

フェーズ 2：スコープの選択

判断ツリー：

Is this a team workflow?
├── Yes → Project scope: .claude/agents/
│         (Committed to git, shared automatically)
│
└── No → Is it project-specific?
         ├── Yes → Project scope: .claude/agents/
         └── No → Personal scope: ~/.claude/agents/
                  (Available across all your projects)

ファイルを作成します：

# Project scope (team)
mkdir -p .claude/agents
touch .claude/agents/agent-name.md

# Personal scope (individual)
mkdir -p ~/.claude/agents
touch ~/.claude/agents/agent-name.md

フェーズ 3：説明文の作成

description フィールドは非常に重要です — Claude がエージェントを自動的に検出して使用するかどうかを決定します。

構成式：[役割／専門知識] + [実行内容] + [呼び出すタイミング] + [トリガーとなる語句]

悪い例（検出されません）：

description: Helps with code

良い例（具体的で検出されやすい）：

description: Expert code reviewer specializing in security and quality. Reviews code changes for vulnerabilities, best practices, and maintainability. Use when reviewing code, checking PRs, or when the user mentions code review, pull request review, or security audit.

良い説明文の内訳：

1. 役割／専門知識：「セキュリティと品質を専門とするコードレビューのエキスパート」
2. 実行内容：「コードの変更をレビューし、脆弱性、ベストプラクティス、保守性を確認します」
3. 呼び出すタイミング：「コードのレビュー時や PR の確認時に使用します」
4. トリガーとなる語句：「コードレビュー、プルリクエストのレビュー、セキュリティ監査」

積極的な表現（自動呼び出しを促します）：

• 「コードの変更後に積極的に使用します」
• 「テストが失敗した場合は必ず呼び出します」
• 「ユーザーが〜に言及した場合に自動的に使用します」

トリガーとなる語句のカテゴリ：

• アクション：レビュー、分析、デバッグ、修正、テスト、確認、監査
• 対象：コード、PR、テスト、エラー、パフォーマンス、セキュリティ
• 状況：デプロイ前、変更後、失敗時、レビュー中

長さ：50〜150 語が理想的です。

フェーズ 4：ツールの設定

セキュリティの原則：必要最低限のツールから始め、必要なものだけを追加します。

段階的なツールアクセス：

# Level 1: Read-only (safest)
tools: Read, Grep, Glob

# Level 2: Can modify files
tools: Read, Write, Edit, Grep, Glob

# Level 3: Specific shell commands
tools: Read, Grep, Glob, Bash(git:*), Bash(npm test:*)

# Level 4: Full shell (use carefully)
tools: Read, Write, Edit, Bash, Grep, Glob

細かく制限する Bash パターン：

# Git commands only
tools: Bash(git:*)

# Specific git commands
tools: Bash(git diff:*), Bash(git log:*), Bash(git status:*)

# npm commands only
tools: Bash(npm:*)

# Test commands only
tools: Bash(npm test:*), Bash(pytest:*), Bash(jest:*)

エージェントの種類別のツール選択：

エージェントの種類	推奨ツール
コードアナライザー	Read, Grep, Glob
コードレビュアー	Read, Grep, Glob, Bash(git diff:*)
テストランナー	Read, Edit, Bash(npm test:*), Grep, Glob
デバッガー	Read, Edit, Bash, Grep, Glob
修正／リファクタリング担当	Read, Write, Edit, Grep, Glob

フェーズ 5：システムプロンプトの設計

重要なポイント：エージェントは別のコンテキストで動作するため、会話履歴を参照できません。システムプロンプトには、ワークフロー全体を含めた自己完結型の内容が必要です。

効果的な構成：

You are [role] specializing in [expertise].

## When Invoked
1. [First action — gather context]
2. [Second action — analyze/process]
3. [Third action — produce output]
4. [Fourth action — verify/validate]

## Focus Areas
- Specific thing to check
- Another thing to verify
- Important consideration

## Output Format
[How to present results]

## Constraints
- What NOT to do
- Boundaries to respect

システムプロンプトのパターン：

1. 役割の定義：

You are a senior code reviewer specializing in security vulnerabilities.
Your primary focus is identifying OWASP Top 10 risks.

2. 呼び出されたとき（自律的な作業では重要）：

## When Invoked
1. Run `git diff HEAD` to see recent changes
2. Identify modified files and their purpose
3. Review each change against security checklist
4. Present findings with severity levels

3. チェックリストのパターン：

## Review Checklist
- [ ] No SQL injection vulnerabilities
- [ ] Input validation on all boundaries
- [ ] No exposed secrets or credentials
- [ ] Proper authentication checks
- [ ] Authorization verified for each endpoint

4. 出力形式：

## Output Format
Present findings as:

### Summary
[One-line verdict: PASS/FAIL/NEEDS ATTENTION]

### Critical Issues
[Must fix before merge]

### Warnings
[Should fix]

### Suggestions
[Nice to have]

5. 制約：

## Constraints
- Do NOT modify code unless explicitly asked
- Do NOT change API contracts
- Focus ONLY on security-related issues
- ALWAYS explain WHY something is a risk

6. 判断ツリー（分岐ロジック用）：

## Decision Flow
If no changes detected:
  → Report "No changes to review"
If only test files changed:
  → Focus on test coverage and assertions
If API endpoints modified:
  → Prioritize authentication/authorization review
Otherwise:
  → Full security review

フェーズ 6：テストと反復

検出のテスト：

# Natural language requests (should trigger agent)
> Review my recent code changes
> Check this PR for security issues
> Audit the authentication module

# Explicit invocation (always works)
> Use the code-reviewer agent to check this

ツールへのアクセスを確認：

# Check agent can use its tools
# If agent needs git, test manually first
git diff HEAD
git log --oneline -5

デバッグ：

# View agent loading errors
claude --debug

# List available agents
/agents

反復チェックリスト：

• 自然なリクエストでエージェントが検出されるか？
• 正しいエージェントが選択されるか（別のエージェントではなく）？
• エージェントに必要なツールへのアクセス権があるか？
• 出力形式は期待どおりか？
• 制約が守られているか？

---

エージェントのパターン

コード品質エージェント

• code-reviewer：品質とスタイルを重視した体系的なコードレビュー
• security-auditor：OWASP に重点を置いた脆弱性の検出
• performance-analyzer：ボトルネックや非効率な箇所の特定
• architecture-reviewer：設計パターンと構造の評価

開発ワークフローエージェント

• debugger：エラーの根本原因の分析
• test-runner：テストの実行と失敗の修正
• refactorer：安全なコードの再構成
• pr-reviewer：プルリクエストの分析

リサーチエージェント

• codebase-explorer：コード構造の調査と理解
• dependency-auditor：古いパッケージや脆弱なパッケージの確認
• documentation-checker：ドキュメントと実装が一致しているかの確認

自動化エージェント

• commit-helper：意図が伝わるコミットメッセージの生成
• deploy-checker：デプロイ前の確認
• migration-assistant：フレームワークやバージョンのアップグレード支援

---

よくある落とし穴

1. 説明が曖昧（エージェントが検出されない）

# Bad
description: Helps with code

# Good
description: Expert code reviewer. Reviews code for quality, security, and maintainability. Use when reviewing code changes, PRs, or when user mentions code review.

2. ツールへのアクセスが不足（エージェントがタスクを実行できない）

# Agent needs to run git commands but can't
tools: Read, Grep, Glob  # Missing Bash(git:*)

# Fixed
tools: Read, Grep, Glob, Bash(git:*)

3. プロンプトが自己完結していない（コンテキストを前提としている）

# Bad - assumes agent sees conversation
Review the code I just showed you.

# Good - self-contained
## When Invoked
1. Run `git diff HEAD` to see recent changes
2. Focus on modified files
3. Review systematically

4. ツールの許可範囲が広すぎる（セキュリティリスク）

# Risky - full shell access
tools: Bash
permissionMode: bypassPermissions

# Safer - scoped access
tools: Bash(git:*), Bash(npm test:*)
permissionMode: default

5. 出力形式がない（結果に一貫性がない）

# Bad - no guidance on output
Review the code for issues.

# Good - explicit format
## Output Format
Present as markdown checklist:
- Critical: [must fix]
- Warning: [should fix]
- Suggestion: [nice to have]

---

エージェントと代替手段の使い分け

シナリオ	最適な選択肢	理由
複雑な複数ステップのタスク	エージェント	焦点を絞った独立したコンテキストを活用できます
ツールを分離する必要がある	エージェント	エージェントごとに使用可能なツールを制限できます
長時間にわたる分析	エージェント	メインの会話を汚しません
チームのワークフローを標準化する	エージェント	一貫した動作を実現でき、Git で共有できます
Claude の知識を拡張する	スキル	コンテキストを共有し、段階的に読み込めます
頻繁に入力するプロンプト	スラッシュコマンド	ユーザーが呼び出せて、すぐに使えます
単純な単一ステップのタスク	直接リクエスト	オーバーヘッドが不要です

エージェントのチェックリスト — 次の場合はエージェントを使用します：

• タスクが複雑で、複数のステップがある
• 新しく焦点を絞ったコンテキストがタスクに役立つ
• 使用可能なツールを制限したい
• タスクに会話履歴全体が必要ない
• 一貫性のある再利用可能な動作を求めている

---

リソース

• テンプレート：段階的な例については templates/ を参照してください
• 例：動作する 18 個のエージェントの完全な例については examples/ を参照してください
• リファレンス：構文ガイド、ベストプラクティス、トラブルシューティングについては reference/ を参照してください

---

クイックスタート

1. ファイルを作成：

touch ~/.claude/agents/my-agent.md

2. 内容を追加：

---
name: my-agent
description: [Role]. [What it does]. Use when [trigger conditions].
tools: Read, Grep, Glob
---

You are [role].

## When Invoked
1. [First step]
2. [Second step]
3. [Third step]

## Output Format
[How to present results]

3. テスト：

> [Natural language request matching description]

4. 反復：

• 検出されない？ → 説明をより具体的にする
• 出力が違う？ → 出力形式を明確にする
• できないことがある？ → 必要なツールを追加する