agent-development

Claude Code 向けエージェント開発

適切な委任、ツールアクセス、プロンプト設計により、Claude Code 向けの効果的なカスタムエージェントを構築します。

エージェントの説明パターン

説明フィールドによって、Claude がタスクを自動的に委任するかどうかが決まります。

強いトリガーパターン

---
name: agent-name
description: |
  [Role] specialist. MUST BE USED when [specific triggers].
  Use PROACTIVELY for [task category].
  Keywords: [trigger words]
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

弱い説明と強い説明

弱い（自動委任されない）	強い（自動委任される）
「問題がないかスクリーンショットを分析します」	「ビジュアル QA のスペシャリストです。スクリーンショットの分析時には必ず使用してください。ビジュアル QA では積極的に使用してください。」
「Playwright スクリプトを実行します」	「Playwright のスペシャリストです。Playwright スクリプトの実行時には必ず使用してください。ブラウザー自動化では積極的に使用してください。」

主なフレーズ：

• 「〜のときには必ず使用してください」
• 「〜には積極的に使用してください」
• トリガーとなるキーワードを含める

委任の仕組み

1. 明示的：Task tool subagent_type: "agent-name" — 常に機能します
2. 自動：Claude がタスクとエージェントの説明を照合します — 強い表現が必要です

エージェントを作成または変更した後は、セッションの再起動が必要です。

ツールアクセスの原則

エージェントに Bash が不要なら、Bash を与えないでください。

エージェントの必要な作業	与えるツール	与えないツール
ファイルの作成のみ	Read、Write、Edit、Glob、Grep	Bash
スクリプト／CLI の実行	Read、Write、Edit、Glob、Grep、Bash	—
読み取り／監査のみ	Read、Glob、Grep	Write、Edit、Bash

理由：モデルは Write ツールではなく、cat > file << 'EOF' のヒアドキュメントをデフォルトで使用します。Bash コマンドごとに承認が必要となり、エージェントの実行ごとに何十回ものプロンプトが発生します。

許可リストのパターン

Bash を制限する代わりに、.claude/settings.json で安全なコマンドを許可リストに登録します。

{
  "permissions": {
    "allow": [
      "Write", "Edit", "WebFetch(domain:*)",
      "Bash(cd *)", "Bash(cp *)", "Bash(mkdir *)", "Bash(ls *)",
      "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(grep *)",
      "Bash(diff *)", "Bash(mv *)", "Bash(touch *)", "Bash(file *)"
    ]
  }
}

モデルの選択（品質優先）

問題を回避するために品質を落とすのではなく、根本原因を修正してください。

モデル	用途
Opus	クリエイティブな作業（ページ構築、デザイン、コンテンツ）— 品質が重要な場合
Sonnet	ほとんどのエージェント — コンテンツ、コード、調査（デフォルト）
Haiku	品質が重要でないスクリプト実行にのみ使用

メモリー制限

根本原因の修正（必須）

~/.bashrc または ~/.zshrc に追加します。

export NODE_OPTIONS="--max-old-space-size=16384"

Node.js のヒープを 4GB から 16GB に増やします。

並列実行の制限（修正後も適用）

エージェントの種類	最大並列数	備考
あらゆるエージェント	2～3	コンテキストが蓄積するため、まとめて実行してから一時停止します
負荷の高いクリエイティブ作業（Opus）	1～2	より多くのメモリーを使用します

復旧

1. source ~/.bashrc を実行するか、ターミナルを再起動します
2. NODE_OPTIONS="--max-old-space-size=16384" claude
3. どのファイルが存在するか確認し、そこから続行します

サブエージェントとリモート API

リモート API 呼び出しよりも、常に Task サブエージェントを優先してください。

項目	リモート API 呼び出し	Task サブエージェント
ツールアクセス	なし	フル（Read、Grep、Write、Bash）
ファイルの読み取り	すべての内容をプロンプトに渡す必要があります	ファイルを段階的に読み取れます
相互参照	単一のコンテキストウィンドウ	複数のドキュメントを横断して推論できます
判断の質	一般的な提案	根拠を伴う具体的な判断
出力の質	通常約100行	具体的な内容を含む600行以上

// ❌ WRONG - Remote API call
const response = await fetch('https://api.anthropic.com/v1/messages', {...})

// ✅ CORRECT - Use Task tool
// Invoke Task with subagent_type: "general-purpose"

命令形より宣言形

ツールの使い方ではなく、達成する内容を記述します。

誤り（命令形）

### Check for placeholders
```bash
grep -r "PLACEHOLDER:" build/*.html

### Right (Declarative)

```markdown
### Check for placeholders
Search all HTML files in build/ for:
- PLACEHOLDER: comments
- TODO or TBD markers
- Template brackets like [Client Name]

Any match = incomplete content.

含める内容

含める	省く
タスクの目標とコンテキスト	明示的な Bash／ツールのコマンド
入力ファイルのパス	「X ツールを使って…」
出力ファイルのパスと形式	ツール呼び出しの手順
成功／失敗の基準	シェルのパイプライン構文
ブロック条件の確認（前提条件）	細かく管理されたワークフロー
品質チェックリスト

自己文書化の原則

「コンテキストを共有されていないエージェントでも、振る舞いを独自に再現できる必要があります。」

改善点はすべてエージェントのプロンプトに記述し、暗黙の知識のままにしてはいけません。

何をエンコードするか

発見事項	記録する場所
バグ修正パターン	エージェントの「Corrections」または「Common Issues」セクション
品質要件	エージェントの「Quality Checklist」セクション
ファイルパスの規約	エージェントの「Output」セクション
ツールの使用パターン	エージェントの「Process」セクション
ブロッキングとなる前提条件	エージェントの「Blocking Check」セクション

テスト: 新しいエージェントは成功するか?

エージェントの改善を完了する前に:

1. コンテキストがまったくない状態でエージェントのプロンプトを読む
2. 自問する: 新しいセッションがこれに従って同じ品質を生み出せるか?
3. できない場合: 不足している指示、パターン、参照を追加する

アンチパターン

アンチパターン	失敗する理由
「先ほど話し合ったとおり...」	事前のコンテキストは存在しない
開発中に読んだファイルに依存する	エージェントが同じファイルを読むとは限らない
エラーから得た知識を前提とする	エージェントはあなたのデバッグを見ることができない
「ホームページと同じように」	エージェントはホームページを構築していない

柔軟性と硬直性

仕様のレベルはタスクの種類に合わせます。柔軟なエージェントを過剰に指定すると、もろくなります。

タスクの種類	仕様レベル	例
機械的/反復的	高 (厳格な手順)	バージョンチェッカー、ファイルコピー
判断ベース	低 (ガイドライン)	ドキュメント監査、コードレビュー
創造的	最小限 (目標のみ)	コンテンツライター、ブレインストーマー

過剰に指定している兆候

• エージェントがテンプレートのセクションを「N/A」で埋める
• エージェントが無関係な場合でもすべてのフェーズを完了しようとする
• スコアリングシステムが無意味な数値を生成する
• スコープが想定と一致しない場合にエージェントが失敗する
• 単純なタスクに対して長いエージェント (150 行超)

柔軟なエージェントのガイドライン

すべきこと:

• 正確な手順ではなく、何を探すかを記述する
• 厳格なテンプレートではなく、出力の例を提供する
• スコープ制御を含める (「30 項目を超える場合はユーザーに確認する」)
• 逃げ道を用意する (「不明な場合はレビュー用にフラグを立てる」)
• 判断タスクでは 100 行未満に抑える

すべきでないこと:

• テンプレートのすべてのセクションを埋めることを要求する
• 精巧な重み付きスコアリングシステムを作成する
• 考えられるすべてのチェックを網羅的に列挙する
• 確認せずにスコープを想定する

例: ドキュメント監査

過剰に指定した例 (悪い):

## Phase 1: Discovery
Execute Glob for all .md files...

## Phase 6: Generate Report
| Category | Weight | Score | Weighted |
|----------|--------|-------|----------|
| Links    | 20%    | X/100 | X        |

適切なサイズ (良い):

## What to Check
- TODOs, broken links, stale versions

## Output Format
List issues by severity. Include file:line and fix.

## Scope Control
If >30 files, ask user which to focus on.

---

エージェントプロンプトの構造

効果的なエージェントプロンプトには次が含まれます:

## Your Role
[What the agent does]

## Blocking Check
[Prerequisites that must exist]

## Input
[What files to read]

## Process
[Step-by-step with encoded learnings]

## Output
[Exact file paths and formats]

## Quality Checklist
[Verification steps including learned gotchas]

## Common Issues
[Patterns discovered during development]

パイプラインエージェント

番号付きのパイプライン (例: HTML-01 → HTML-05 → HTML-11) に新しいエージェントを挿入する場合:

更新が必要なもの	内容
新しいエージェント	「Workflow Position」図 + 「Next」フィールド
先行エージェント	その「Next」フィールドを新しいエージェントを指すようにする

よくあるバグ: 先行エージェントが依然として古い次のエージェントを指しているため、新しいエージェントが「孤立」する。

検証:

grep -n "Next:.*→\|Then.*runs next" .claude/agents/*.md

最適な領域

最適なユースケース: 反復的だが判断を要するタスク。

例: 70 個のスキルを手動で監査するのは退屈です。しかし、各監査には知性が必要です (ドキュメントを確認し、バージョンを比較し、何を修正するかを判断する)。明確な指示を持つ並列エージェントに最適です。

適していないもの:

• 単純なタスク (ただ実行すればよい)
• 高度に創造的なタスク (人の指示が必要)
• ファイル間の連携が必要なタスク (エージェントは独立して動作する)

効果的なプロンプトテンプレート

For each [item]:
1. Read [source file]
2. Verify with [external check - npm view, API call, etc.]
3. Check [authoritative source]
4. Score/evaluate
5. FIX issues found ← Critical instruction

重要な要素:

• 「FIX issues found」 - これがないと、エージェントは報告するだけです。これがあると、行動に移します。
• 正確なファイルパス - 曖昧さを防ぎます
• 出力形式テンプレート - 一貫性があり解析可能なレポートを保証します
• バッチサイズ約 5 項目 - 効率的に作業できる量で、失敗が連鎖しない程度

ワークフローパターン

1. ME: Launch 2-3 parallel agents with identical prompt, different item lists
2. AGENTS: Work in parallel (read → verify → check → edit → report)
3. AGENTS: Return structured reports (score, status, fixes applied, files modified)
4. ME: Review changes (git status, spot-check diffs)
5. ME: Commit in batches with meaningful changelog
6. ME: Push and update progress tracking

エージェントがコミットしない理由: 人間によるレビュー、バッチ処理、クリーンなコミット履歴を可能にします。

このパターンに適したタスクの特徴

適しているもの：

• 多くの項目で同じ手順を繰り返す
• 各項目で判断が必要（単なる変換ではない）
• 項目同士が独立している（項目間に依存関係がない）
• 明確な成功基準がある（スコア、合否など）
• 照合できる信頼性の高い情報源がある

適していないもの：

• 項目同士が互いの結果に依存する
• 創造的・主観的な判断が必要
• 単一の複雑なタスク（通常のエージェントを使用）
• 作業の途中で人間の入力が必要

クイックリファレンス

エージェントのフロントマターのテンプレート

---
name: my-agent
description: |
  [Role] specialist. MUST BE USED when [triggers].
  Use PROACTIVELY for [task category].
  Keywords: [trigger words]
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

Bash の承認要求が頻発する問題を解決する

1. 不要であれば、ツールから Bash を削除する
2. 重要な指示を最初に配置する（フロントマターの直後）
3. .claude/settings.json で許可リストを使用する

メモリクラッシュからの復旧

export NODE_OPTIONS="--max-old-space-size=16384"
source ~/.bashrc && claude