write-agent

Context: ユーザーが単一目的のレビュー担当を求めている user: "コードの変更をチェックするセキュリティレビュー担当エージェントを作成してください" assistant: "これは単一目的のレビュータスクです。読み取り専用ツールを使うサブエージェントを作成します。" 単一の役割（セキュリティレビュー）＋出力タイプが1つ → オーケストレーターではなく、サブエージェントです。 assistant: "write-agent スキルを使って、security-reviewer サブエージェントを作成します。" Context: ユーザーが複数フェーズのワークフローコーディネーターを求めている user: "機能を計画し、実装し、レビューを実行して、品質ゲートを通過するまで反復できるエージェントが必要です" assistant: "これは調整、ディスパッチ、反復を伴う複数フェーズのワークフローです。ワークフローオーケストレーターを作成します。" 複数のフェーズ＋サブエージェントのディスパッチ＋反復 → ワークフローオーケストレーターパターンです。 assistant: "write-agent スキルを使って、ワークフローオーケストレーターを作成します。" Context: ユーザーがリポジトリの規約について質問している（エージェントではない） user: "このリポジトリのコミットメッセージ形式は、どのように記述すればよいですか？" assistant: "これはエージェントの設計ではなく、リポジトリ全体に適用される規約についてです。代わりに CLAUDE.md に追加します。" 常に適用されるリポジトリの制約 → エージェントではなく CLAUDE.md です。write-agent は起動しないでください。 assistant: "コミットメッセージの規約を CLAUDE.md に追加します。" Context: ユーザーが既存のエージェントの更新またはリファクタリングを求めている user: "security-reviewer エージェントを整理してもらえますか？冗長になってきていますし、ルーティングも適切でない気がします。" assistant: "これは既存のエージェントの更新です。意図を保ちながら、明確さとルーティングを改善する必要があります。" 更新／リファクタリングの依頼 → ずれを防ぐため、更新手順を使います。references/updating-existing-agents.md を読み込んでください。 assistant: "write-agent スキルの更新手順を使って、security-reviewer エージェントをリファクタリングします。"

エージェント作成スキル

過度な制約を設けずに、焦点が定まり、安全で、信頼性の高いエージェントを設計します。

重要な原則：トークンと注意力を共有の予算として扱うことです。長い説明よりも、短く情報密度の高いプロンプトと、強力な出力契約を優先します。

---

このスキルでの補助ファイルの使い方

このスキルには、references/ と templates/ に任意の補助資料が含まれています。

• ワークフローの手順に Load: path/to/file.md とある場合は、続行する前にそのファイルを開いてください。
• 判断に迷った場合は、末尾のリファレンス索引から適切な詳細資料を探してください。
• テンプレートはカスタマイズして使うための出発点であり、厳格な形式ではありません。

複雑なエージェント設計の場合： 作業を始める前に、このスキルフォルダー内のすべてのファイルを読むことを検討してください。コンテキストが部分的だと、エージェントに一貫性がなくなったり、パターンを見落としたりする可能性があります。オーケストレーターの設計、既存エージェントの更新、または不慣れなドメインでの作業では、特に有効です。

---

運用原則（エージェントの設計者向け）

エージェントのプロンプトを作成する際は、次の原則に従ってください。

1. 注意力は限られた資源として扱います。 コンテキストの長さに対して、モデルの注意力は O(n²) で増加します。各トークンは、ほかのすべてのトークンと注意力を奪い合います。重要な指示を冒頭に置き、参照資料は必要に応じて読み込む references/ ファイルに移してください。

2. 洗練さより信頼性を優先します。 手順が不安定だったり、間違いやすかったりする場合は、チェックリスト、検証ループ、「Y ではなく X をする」という制約などの安全策を加えてください。モデルが正しい振る舞いを推測することに頼らないでください。

3. 基本となる明確な進め方を1つ用意し、別の選択肢も設けます。 推奨するデフォルトのワークフローを示してください。ほかの方法がある場合は明示しますが、選択肢を増やしすぎないでください。

4. 実行しやすい書き方にします。 「X をしてください。その後、Y をしてください」のように、明確な命令形を使います。具体的な手順や成果物を示さずに、「注意してください」「徹底してください」といった曖昧な注意喚起を使わないでください。

5. 確実性に合わせた表現を使います。 厳守事項には「必ず」「決して〜しない」を使います。例外のある強いデフォルトには「〜するべきです」「〜を優先してください」を使います。提案には「検討してください」「〜してもかまいません」を使います。エージェントは、この確度の調整を解析します。

6. エージェントのプロンプトは単独で機能するものにします。 初めて読む人が、前提となる知識をまったく持たないと想定してください。エージェントが以前の会話や親エージェントの状態から推測することに頼らないでください。特にサブエージェントについては、ほかのエージェントを名前で参照しないでください。それぞれを唯一のエージェントとして記述します（設計上、サブエージェントを調整するオーケストレーターは例外です）。サブエージェントにオーケストレーションのコンテキストが必要な場合は、恒久的なプロンプトに記載せず、親からハンドオフを通じて渡してください。

7. 状況に応じて肯定形と否定形を使い分けます。 通常のガイダンスでは、禁止（「Y をしないでください」）より肯定形（「X をしてください」）のほうが明確な場合が多くあります。ただし、否定形も有効な補完手段です。特に、除外事項、失敗パターン、境界の定義に役立ちます。否定形を使う場合は、具体的に記述し、役立つ場合は対比例を添え、重要な制約はセクションの境界に配置してください。手法の詳細は references/prompt-structure.md を参照してください。

---

このスキルを使うときに作成するもの

「エージェントを作成する」「サブエージェントを書く」「レビュー担当を作る」「オーケストレーターを作る」と依頼された場合は、次のものを作成してください。

1. エージェント概要（簡潔）— 必要に応じて前提条件を含めます。
2. すぐに貼り付けて使えるエージェントファイル（.claude/agents/<name>.md）。
   • サブエージェントの場合：単一の目的を持つ実行担当／レビュー担当。
   • ワークフローオーケストレーターの場合：Task ツールを使ってサブエージェントを起動する、複数フェーズの調整役。
3. 任意の付属成果物（実質的に役立つ場合のみ）：
   • スキル（再利用可能なワークフロー／知識）
   • 出力契約スキル（オーケストレーターによる集約に使う共通スキーマ。例：すべてのレビュー担当が事前に pr-review-output-contract を読み込む）
   • CLAUDE.md／.claude/rules への追加（常時適用する制約）
   • フック（条件付きのツール制御／品質ゲート）

説明は簡潔にしてください。具体的な成果物（ファイル、テンプレート、チェックリスト）を優先してください。

ワークフロー

ワークフロータスクを作成する（最初のアクション）

作業を始める前に、TaskCreate を使って各ステップのタスクを作成し、addBlockedBy で順序を設定してください。各ステップの説明と完了条件は、それぞれのワークフローの記述から導き出してください。

1. エージェント作成：依頼を振り分け、エージェント概要を作成する
2. エージェント作成：仕組みと厳格さを決める
3. エージェント作成：設定を作成し、システムプロンプトを書く
4. エージェント作成：ハンドオフを設計し、安全策を追加する

各タスクは、作業を開始したら in_progress にし、そのステップの完了条件を満たしたら completed にしてください。再開する場合は、まず TaskList を確認し、未完了のタスクのうち最初のものから再開してください。

0) リクエストの種類を特定する

どちらの作業を行うか判断します。

• 作成：エージェントを新規作成する → 以下のステップ 1～8 に進みます
• 更新／リファクタリング：既存のエージェントを更新する → references/updating-existing-agents.md を読み込み、その手順に従います

既存のエージェントを更新／リファクタリングする場合：

重要： 更新作業に進む前に、必ずこのファイルのステップ 0：コンテキストの完全な読み込みを完了してください。具体的には、次のものをすべて読み込みます。

1. write-agent/ フォルダー内のすべてのファイル（SKILL.md ＋すべての references/ ＋すべての templates/ ＋すべての scripts/）
2. 対象のエージェントに関連するすべてのファイル（エージェントファイルと関連ファイル）
3. このエージェントを起動するオーケストレーター（該当する場合）

このステップを省略しないでください。コンテキストの読み込みが不完全だと、更新時にルーティングのずれ、機能の拡大、出力仕様の破綻が発生する主な原因となります。

---

1) エージェントのパターンを選ぶ：サブエージェントとワークフローオーケストレーター

簡易判断基準： エージェントが適切な仕組みなのか（スキルや CLAUDE.md のルールではなく）判断に迷う場合は、まずステップ 3 に進みます。そうでなければ、要件に合う最も軽量なエージェントパターンを選びます。

必要なこと	選択肢	実際の効果
1 つの作業と 1 つの出力（レビュー、実装、診断、要約）	サブエージェント	対象範囲が単純で、検証しやすく、通常は Task ツールを使いません
複数フェーズのワークフロー（調査 → 計画 → 実装 → 評価 → 反復）	ワークフローオーケストレーター	Task ツールが必要です。フェーズを調整し、サブエージェントを割り当て、結果を集約します
複数フェーズのオーケストレーションは不要だが、単一タスクを分離したい	サブエージェント（または context: fork スキル — ⚠️ プラグインでは不安定です。ステップ 3 の注記を参照）	必要がない限り、オーケストレーションのロジックは記述しません

厳守事項： サブエージェントは、別のサブエージェントを起動できません。 そのため、ワークフローオーケストレーターはトップレベルのセッションエージェントとして実行する必要があります（例：claude --agent feature-development …）。Task で起動したサブエージェントとして実行することはできません。

CLI の呼び出しに関する注記： エージェントは claude --agent <name>（対話形式）または claude --agent <name> -p "prompt"（非対話形式）で直接呼び出せます。実行中のセッション内から Claude Code のサブプロセス（反復ループなど）を起動する場合は、env -u CLAUDECODE -u CLAUDE_CODE_ENTRYPOINT claude -p ... のパターンを使用してください。これにより、ネスト実行の制限を回避できます。サブプロセスには必ず --dangerously-skip-permissions を設定してください。複数階層のネストを含む呼び出し方法の詳細は、references/claude-code-mechanics.md を参照してください。

テンプレート：

• サブエージェント：templates/subagent-template.md、templates/subagent-reviewer-template.md、templates/subagent-worker-template.md
• オーケストレーター：templates/workflow-orchestrator-template.md
• 詳細なガイダンス：references/workflow-orchestrators.md

2) エージェントブリーフを作成する（簡潔に）

次の項目を記入します。不足情報が作業を妨げる場合に限り質問し、それ以外は妥当なデフォルトを想定して、その旨を明記します。

• パターン： サブエージェント | ワークフローオーケストレーター
• 達成する目的： どのような成果を安定して実現すべきか？
• 委任のトリガー： Claude にこのエージェントを使わせる条件は何か？
• 入力： どのようなコンテキストやファイルが必要か？ 利用可能だと想定できるものは何か？
• 出力： 形式、対象読者、詳しさはどうするか？
• 品質基準： どのような出力なら「完了」で、どのような場合は「修正が必要」か？
• 制約： 厳守すべきルール（必須／禁止）と、推奨事項
• ツールと権限： 最小限の権限でのツールアクセスと、権限モードの選択
• モデルの選択： コストや速度と、推論の必要性とのバランス
• 失敗時の方針： 質問する場合と、仮定に基づいて進める場合

ワークフローオーケストレーターの場合は、さらにフェーズ、サブエージェントの構成、成果物の方針、品質ゲート、反復の方針も記録します。

オーケストレーターのチェックリスト全体は references/workflow-orchestrators.md を読み込みます。

必要に応じて、references/prompt-structure.md のブリーフテンプレートをコピーして使用します。

デフォルトの出発点： templates/ 内から最も近いテンプレートを選び、エージェントファイルを返す前に、すべての [TODO] を記入します。

明確化の方針（概要の情報を集める際）

この判断表を使って、質問が少なすぎることと多すぎることの両方を防ぎます。

状況	対応
ルーティング（委任のトリガー）、ツールの権限、副作用、互換性に影響する情報が不足している	作成に取りかかる前に、的を絞った質問を1～3個します。
ユーザーが「最善だと思う方法で」と言う、または無関心を示している	具体的な推奨案と1～2個の代替案を提示し、重要な選択について確認します。
詳細が重要度が低く、後から変更できる（文言の例、マイナーなセクション名など）	妥当なデフォルトを使い、必要に応じてユーザーが訂正できるよう、前提を簡潔に示します。

質問の設計（人間からの入力が必要な場合）：

• 明確にラベル付けした選択肢を2～4個提示します（選択疲れを招くため、5個以上は避けます）。
• 推奨する選択肢を最初に置き、「（推奨）」とラベルを付け、1文で理由を説明します。
• 選択肢で実情を網羅できない可能性がある場合は、「その他」を含めます。
• 抽象的な好みではなく、回答によって何が変わるかを軸に質問します。

前提を置いて進める場合は、見つけやすく訂正しやすいように、**前提：**と明記します。

3）エージェント、スキル、常時適用ルールのどれを使うか決める

目的を確実に達成できる、最も軽量な仕組みを選びます。

必要なもの	推奨	理由
常時適用するリポジトリの制約（コマンド、規約、必須事項）	CLAUDE.md / .claude/rules	どこでも適用され、ルーティングも不要です
メインの会話コンテキストで実行する再利用可能な指示	スキル	コンテキストを分離せずに再利用でき、対話中に簡単に呼び出せます
ツールを制限した、特定の役割を担うワーカーまたはレビュー担当	サブエージェント	コンテキストを分離し、最小権限のツールを使用できます
他のエージェントを連携させる複数フェーズのパイプライン	ワークフローオーケストレーター	フェーズの順序、ディスパッチ、集約、反復を定義できます

注：

• サブエージェントは、他のサブエージェントを起動できません。複数段階にわたる専門化が必要な場合、オーケストレーションはトップレベルのエージェント／セッションで行う必要があります。

• 「アウトオブバンド」で実行する再利用可能なワークフローが必要な場合は、以下を推奨します。

  • context: forkを設定したスキル、または
  • セッションエージェントとして呼び出すワークフローオーケストレーターエージェント。

  ⚠️ context: forkは信頼性に欠けます（Issue #16803 — OPEN）。スキルはフォークされずにインラインで実行されることが多く、特にプラグインスキルでは失敗率が95%を超えるという報告があります。確実な分離が必要な場合は、代わりにAgentツール＋スキル読み込みのパターンを使います。general-purposeサブエージェントを起動し、そのプロンプトの先頭に「何かを行う前に、/skill-nameを読み込んでください」と記述します。サブエージェントはSkillツールを使ってスキルを読み込み、分離された環境で実行します。

4）適切な厳密さのレベルを選ぶ（「ゴルディロックスゾーン」）

エージェントのプロンプトは、適切な具体度に設定する必要があります。指針となる具体性を保ちつつ、さまざまな状況に応用できるようにします。

失敗のパターン	症状	例
厳しすぎる	脆弱な列挙になり、想定外の入力で破綻する	「.tsならXを実行、.tsxならYを実行、.jsならZを実行……」
曖昧すぎる	具体的な手掛かりのない抽象的な原則	「役立つ、徹底的な対応をしてください。」
ちょうどよい	汎用性のあるヒューリスティクスと、明確なエスカレーション方針	「スタイルより正確さを優先してください。不確かな場合は質問してください。」

タスクの特性に応じて厳密さを調整します。

• 自由度が高い： ヒューリスティクスと出力要件（レビュー、監査、ブレインストーミング）
• 自由度が中程度： 手順と必須チェック（リファクタリング、移行）
• 自由度が低い： スクリプト／コマンドと厳格な検証ループ（壊れやすい運用）

5) エージェント設定を作成する（フロントマター）

設定する（次に進む前に、各項目が存在することを確認してください）：

• name：安定した、ハイフン区切りの説明的な名前
• description：具体的なトリガーと例。対象が広すぎるルーティングは避けてください
• tools / disallowedTools：最小限の権限
• permissionMode：理由がない限り、デフォルトのままにしてください
• model：haiku/sonnet/opus/inherit（意図を持って選択してください）
• skills：必要なスキルを明示的にプリロードしてください（継承を想定しないでください）

重要：ルーティングでは <example> ブロックを使用します。 <commentary> を含む <example> ブロックを2～4個記述し、委任すべき理由（または委任すべきでない理由）を説明してください。

サブエージェント（推奨されるデフォルト設定）：

• Task ツールは含めないでください（入れ子での起動を防ぐため）。
• 判断や実装に使う分野固有のスキルをプリロードしてください（例：skills: [write-docs]）。
• オーケストレーターが確実に集約できるよう、明確な出力契約を設けてください。

ワークフローオーケストレーター（推奨されるデフォルト設定）：

• Task ツール（およびリポジトリの調査に必要な最小限のツール）を含めてください。
• 起動されたサブエージェントが skills: を継承すると想定しないでください（継承されません）。
• ディスパッチ、集約、反復のパターンについては references/workflow-orchestrators.md を参照してください。

最小限のパターン（コピーして貼り付け、カスタマイズしてください）：

---
name: my-agent
description: Use this agent when <trigger conditions>. Avoid using it when <exclusions>.

<example>
Context: <situation that SHOULD delegate>
user: "<user message>"
assistant: "<assistant response before delegating>"
<commentary>
Why this matches the trigger conditions.
</commentary>
assistant: "I'll use the my-agent agent to…"
</example>

<example>
Context: <near-miss that SHOULD NOT delegate>
user: "<user message>"
assistant: "<assistant response that stays in the main thread>"
<commentary>
Why this is a near-miss / exclusion.
</commentary>
assistant: "<continue without delegating>"
</example>

# Optional:
# tools: Read, Grep
# model: sonnet
# permissionMode: default
---

# My Agent
...

読み込み： サブエージェントの制約、権限モード、スキルの構成パターンについては references/claude-code-mechanics.md を参照してください。

6) システムプロンプトの本文を作成する

正確に実行できるよう、次の構成を使用してください。

1. 役割とミッション（2～4文）— 人格に関する記述を含めます
2. 対象範囲と対象外（意図しない範囲への逸脱を防ぎます）
3. 行動原則（直接的な対応と提案のバランス）
4. ワークフローのチェックリスト（コピーして貼り付けられる形式）
5. ツール使用ポリシー（何を読み、grepし、実行するか。ノイズを抑える方法）
6. 出力契約（見出しを厳密に指定し、冗長さを制限し、根拠を示す）
7. 引き継ぎプロトコル（サブエージェントに渡す内容と、返す内容）
8. 質問とエスカレーション（質問すべき場合と、そのまま進める場合）

「役割とミッション」セクションの作成：

「役割とミッション」では、エージェントのアイデンティティと判断の枠組みを定めます。以下を満たすようにしてください。

• この役割にとっての優れた成果を明示します（単に何をするかだけではありません）
• この役割で最も優れた人間が示す行動を描写します
• 判断の質を損ねる逃げ道を与えないようにします

読み込み： 効果的な人格に関する記述のパターンについては references/personality-and-intent.md を参照してください。

簡単なガイダンス：

• ✅「正確性、セキュリティ、データの完全性など、最も重要な問題を見つけます」
• ✅「表面的な細部の指摘よりも、影響の大きい領域に注力します」（安全な取捨選択です。細かな指摘はアンチパターンです）
• ❌「完璧なコードよりも、動作するコードを優先します」（危険です。「完璧なコード」はアンチパターンではありません）
• ❌「実用的かつ迅速に対応します」（曖昧なため、質の低い作業を正当化しかねません）

オーケストレーター向けの追加事項： ワークフローオーケストレーターを作成する場合は、フェーズ計画、ディスパッチルール、集約ルール、反復ポリシー、成果物の受け渡しに関する明示的なセクションを追加してください。references/workflow-orchestrators.md と references/prompt-structure.md を参照してください。

文体上の制約： 二人称で記述してください（「あなたは…です」「…してください」）。エージェントがファイルを編集することを許可され、期待されている場合を除き、一人称での確約（「私はファイルを編集します…」など）は避けてください。

失敗モードへの対応：

優れたエージェントプロンプトは、何をすべきかを指示するだけではありません。タスクに応じて起こりやすい失敗モードも明示します。これにより、エージェントが自己修正する際の指針が得られます。

読み込み： よくあるLLMの失敗モードの全一覧については references/failure-modes.md を参照してください。

失敗モードは、次のいずれかの方法で含めてください。

• 専用の**「避けるべき失敗モード」**セクションを設ける（明示的で、要点を把握しやすい形式）、または
• 行動原則に織り込む（「Xを行ってください。Yをしてしまう傾向は避けてください。」）

エージェントの文脈に最も関係するものを3～5個選び、すべてを含めないでください。

簡単な選択ガイド：

エージェントの種類	関連性が高い傾向
レビュアー	ニュアンスを単純化する、情報源の権威性、不確かな場合に断定する、重要な点を埋もれさせる
実装者	曖昧さをそのまま突き進む、後続への影響、指示への硬直した対応、意図を決めつける
オーケストレーター	曖昧さをそのまま突き進む、エスカレーションしない、意図を決めつける、直近の情報を過度に重視する

解釈テスト（すべての指示に実施）：

プロンプトを仕上げる前に、各指示が次の4項目を満たしているか確認してください。

1. 2通りに解釈できますか？ — できる場合は、明確化する例、または「YではなくXをする」という制約を追加します。
2. 読み手が持っていない文脈を前提にしていませんか？ — エージェント向けのプロンプトは単独で完結する必要があります。暗黙の前提を明示してください。
3. 別のモデルやインスタンスでも同じように解釈されますか？ — 明示されていない特定の解釈に依存している場合は、それを明確にしてください。
4. 指示の強さは明確ですか？ — 「must」（絶対条件）、「should」（強く推奨される標準）、「consider」（提案）を区別してください。「注意してください」のような曖昧な表現は使わないでください。

大まかに書いて後で直すのではなく、書きながら表現を明確にしてください。

読み込み： プロンプトの各セクションの詳細については、references/prompt-structure.md を読み込んでください。

プロンプト作成技法に関するメモ：

• 少数ショットの例： 適切に選んだ2～3個の例は、それ以上の数の例より効果的です。順序が重要です。最も代表的な例を最後に配置してください（新近性効果）。質の低い例が1つあるだけで、すべての例の効果が損なわれます。
• 肯定的な表現： 運用原則 #7 を参照してください。可能であれば、「不確かなときは回答しない」を「確信がある場合にのみ回答する」のように言い換えます。
• 効果的な否定表現： 否定的な指示は、適切に補強すれば効果を発揮します。対比する例（誤りと正解）を使い、制約を曖昧にせず具体的にし、重要な制約をセクションの区切りに配置してください。注：大文字や太字による強調は役に立ちません。代わりに構造的な手法を使ってください。詳細については、references/prompt-structure.md を参照してください。

7) 双方向のコンテキスト引き継ぎを設計する

サブエージェントは「新しい状態」で開始するため、親チャットの内容を覚えていることを前提にしないでください。

• 親／オーケストレーター → サブエージェント：引き継ぎパケット（目標、制約、対象ファイル、「良い結果」の定義）を渡します。
• サブエージェント → 親／オーケストレーター：報告パケット（要約、調査結果、根拠、次のアクション、未解決の質問）を返します。

オーケストレーターの成果物に関する目安：

• フェーズの出力が小さい（約2～3 KB未満）場合は、次の引き継ぎパケットに含めます。
• フェーズの出力が大きい（計画、調査メモ、多数の調査結果など）場合は、ファイルに書き込み、そのパスを渡します。これにより、トークンの肥大化を防ぎ、再開／分岐のワークフローが可能になります。

エラーの保持： サブエージェントのアクションが失敗した場合は、その失敗したアクションとエラーを引き継ぎコンテキストに残してください。これにより、明示的に「Xをするな」と指示しなくても、エージェントはうまくいかない方法を学び、暗黙的に信念を更新できます。エラーが蓄積した場合は、パターンを要約しても構いませんが、完全に削除しないでください。

読み込み： パケットのテンプレートと反復のパターンについては、references/handoff-protocol.md を読み込んでください。

8) 効果に見合うガードレールを追加する

次のようなガードレールを優先してください。

• 観察可能（チェックリスト、検証、具体的な基準）
• 具体的（「Xを実行してYを報告する」）
• 低コスト（一般的な注意喚起にトークンを浪費しない）

次のようなものは避けてください。

• 巨大で百科事典のようなプロンプト、
• デフォルトがないまま、多数の選択肢を並列に提示すること、
• 手順や出力を示さずに、「注意してください」と曖昧に述べること。

品質基準

エージェントファイルを返す前に、次の点を確認してください。

• フロントマターに name、2～4 個の <example> ブロックを含む description、および想定される tools／disallowedTools が含まれています。
• description が広すぎず狭すぎず、例には少なくとも 1 つの、対象外とすべき類似ケースが含まれています。
• 役割とミッションで、エージェントが何をするかだけでなく、優れた成果とは何かが説明されており、リスクのある逃げ道がありません。
• 失敗モード：文脈に即した 3～5 個の失敗モードに対処しています（専用セクションを設けるか、原則に織り込んでいます）。
• 指示が解釈テストに合格しています。曖昧な表現や、前提とする文脈がなく、必要に応じて「Y ではなく X を実行する」と明記され、指示の強さが明確です。
• プロンプト本文に、ミッション、対象範囲／対象外事項、ワークフロー、ツールポリシー、出力契約、エスカレーションルールが含まれています。
• 引き継ぎと返却パケットの形式が明示されているか、参照先が示されています。

ワークフローオーケストレーターの場合は、さらに次の点を確認してください。

• フェーズ計画、ディスパッチルール、集約ルール、反復ポリシーが含まれています。
• ネスト不可の制約を認識しています（最上位のセッションエージェントとして実行する必要があります）。

設計者によるセルフチェック（提出前）：

• 別の文脈では二通りに解釈される可能性がある指示を書いていませんか？
• エージェントが持っていない文脈を前提にしていませんか？
• 具体的な手順の代わりに、「注意深く」「徹底的に」といった曖昧な表現を使っている箇所はありませんか？
• 指示の強さを取り違えていませんか（「必須」とすべき箇所に「推奨」を使うなど）？

いずれかの答えが「はい」であれば、提出前に修正してください。エージェントの性能不足の多くは、モデルの限界ではなく設計者のミスに起因します。

実装の出力形式

ファイルを出力する際は、次の形式にしてください（パスとコードブロック）。

• path/to/file.md
• （内容をフェンス付きコードブロックに記載）

ファイルの内容でない追加の Markdown の文章を、ファイル内に埋め込まないでください。

---

参考インデックス

このインデックスを使うと、適切な詳細解説をすばやく見つけられます。メインのワークフローでは、Load: の参照先に従ってください。

優先度の凡例：

• P0 = 正確性／信頼性のために必須
• P1 = 品質と一貫性を向上
• P2 = 任意の詳細情報

参考資料

パス	優先度	使用する場面	省略した場合の影響
references/updating-existing-agents.md	P0	既存のエージェントに対する「更新」または「リファクタリング」の依頼	意図のずれ、ルーティングの破損、機能の拡大、下流オーケストレーターの失敗
references/claude-code-mechanics.md	P0	フロントマターの設定、制約・権限・構成の把握、CLI の呼び出しパターン（--agent、-p、--resume）、再帰呼び出しの制限	ルーティングの破損、権限エラー、起動の失敗、再帰呼び出しのブロック
references/prompt-structure.md	P0	システムプロンプトの本文構成、役割とミッション、ツールポリシー、出力契約の作成	手順の漏れ、出力の不統一、エスカレーションの不明確さ
references/failure-modes.md	P1	このエージェントタイプで対策すべき障害モードの選定	エージェントに予測可能な LLM の盲点が現れる
references/personality-and-intent.md	P1	効果的な役割とミッションの記述、逃げ道の回避	曖昧なアイデンティティ、リスクのあるトレードオフの提示
references/workflow-orchestrators.md	P1	複数フェーズのオーケストレーターの設計、ディスパッチ、集約、反復	オーケストレーターに重要な調整パターンが欠ける
references/handoff-protocol.md	P1	ハンドオフパケットの設計、返却パケットの構成、複数フェーズの連鎖	サブエージェントに必要なコンテキストが不足する、または利用できない結果を返す
references/evaluation-and-iteration.md	P1	委任動作の調整、過剰・過少なトリガーのデバッグ	エージェントの調整状態が不適切なままになる
references/procedural-patterns.md	P2	検証ループ、反復ポリシー、エラー処理の作成	エージェントが無限ループに陥る、検証を省略する、または適切に失敗できない
references/designer-failure-modes.md	P2	エージェントの性能不足のデバッグ、提供前のプロンプトレビュー	設計者の誤りをモデルのせいにする

テンプレート

パス	使用する場面
templates/subagent-template.md	汎用サブエージェントの作成を始めるとき
templates/subagent-reviewer-template.md	読み取り専用のレビュー担当（Write/Edit を許可しない）
templates/subagent-worker-template.md	実装に重点を置いたワーカー
templates/workflow-orchestrator-template.md	複数フェーズのオーケストレーター（Task ツールを使用）
templates/skill-fork-template.md	フォークされたサブエージェントのコンテキストで実行するスキル

スクリプト

パス	目的
scripts/validate-agent.sh	エージェントファイルの構造を検証します。name／description の欠落を検出し、<example> ブロックがない場合に警告します