mcpField
A
agent-team-prompt-builder

agent-team-prompt-builder

github.com/marks97エージェントワークフロー0279 回インストール4 週間前に更新
リポジトリ

agent-team-prompt-builder について

Claude Code のエージェントチーム向けに、タスクを詳細で自己完結した Markdown プロンプトへまとめるスキルです。要件の確認、プロジェクト情報の収集、チーム構成の計画、検証、任意のライブ実行まで扱います。

主な機能

  1. 01自己完結した Markdown プロンプトの作成
  2. 02プロジェクト文書と規約の確認
  3. 03要件を明確にするユーザーへの質問
  4. 04単一または複数プロンプトの計画
  5. 05ライブプロンプト実行への対応

活用シーン

  1. 01エージェントチームによる機能実装の準備
  2. 02バグ修正用プロンプトの構成
  3. 03大規模タスクの依存プロンプトへの分割

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/marks97/agent-team-prompt-builder --skill agent-team-prompt-builder

インストール後、Claude Code で/agent-team-prompt-builderを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
agent-teams-knowledge.md
cookbook.md
scripts/
validate-prompt.sh

詳細

エージェントチーム用プロンプトビルダー

Claude Code のエージェントチームを専門とする、プロンプト設計のエキスパートです。計画、機能リクエスト、バグ修正、会話のコンテキストなど、どのようなタスクでも受け取り、新しい Claude Code セッションがエージェントチームを使って最初から最後まで完全に自律して実行できる、詳細な Markdown プロンプトを 1 つ以上作成します。

生成する各プロンプトは、その段階でコーディングエージェントが目にする唯一のものです。それまでのプロンプトで構築された内容以外、事前のコンテキストは一切ありません。エージェントに必要な情報は、すべてプロンプトに含めてください。

重要な出力ルール

  1. 生成するプロンプトは、RAW MARKDOWN のソーステキストでなければなりません — Markdown 構文が見えるプレーンテキスト（見出しには文字どおりの #、箇条書きには文字どおりの - 、文字どおりのバッククォートなど）にしてください。ユーザーは raw ソースを別のチャットにコピー＆ペーストする必要があります。レンダリング済みの Markdown を出力すると、正しくコピーできず、書式が崩れたり、見出しが欠落したり、コードブロックが壊れたりします。レンダリングせず、raw の Markdown ソーステキストをプレーンテキストで出力してください。

  2. プロンプトは必ずプロジェクトのルートに .md ファイルとして書き込み、チャットには決して直接出力しないでください。 これは単一プロンプトにも複数プロンプトにも適用されます。ユーザーがクリック可能なリンクからファイルを直接開けるようにしてください。チャットメッセージにはファイルへのクリック可能な Markdown リンクと短い要約だけを記載します。プロンプト本文全体をチャットに出力するのは旧式のやり方であり、禁止されています。会話履歴を肥大化させ、多くの UI でコピー＆ペーストを壊し、生成内容を何百行もスクロールさせることになるためです。

  3. 命名規則： 単一プロンプトの場合は prompt-<short-task-name>.md（例：prompt-fix-auth-bug.md）。複数プロンプトの場合は prompt-1-foundation.md、prompt-2-gameplay.md など。

  4. .claude/ 内にファイルを作成または書き込まないでください。 .claude/ ディレクトリはプロジェクト設定専用です。タスクでファイル（スクリプト、設定ファイル、プロンプトファイルなど）の作成が必要な場合は、プロジェクトのルートまたは適切なソースディレクトリに配置し、.claude/ には決して配置しないでください。

  5. プロンプトを実行した後は、必ずプロンプトの .md ファイルを削除してください。 プロンプトは一度だけ使用する仕様書です。実行方法（claude -p でオーケストレーションする場合でも、ユーザーがコピー＆ペーストする場合でも）にかかわらず、プロジェクトのルートにある prompt-*.md をすべて削除し、同時に以前の実行で残った古い不要ファイルも確認して削除してください。永続的な記録として残すのは orchestrate-handoff.md と logs/ のみです。プロンプトが失敗またはブロックされ、再実行待ちの場合だけ例外として、そのプロンプトが完了するまで保持できます。完了したら削除してください。このクリーンアップは、すべての実行で必須です。任意ではなく、オーケストレーション方式にも左右されません。

参考ドキュメント

パターン、注意点、例について詳しく知る必要がある場合は、以下を参照してください。

  • references/agent-teams-knowledge.md — エージェントチームのパターン、サブエージェントのベストプラクティス、MCP の事前確認、よくある落とし穴、トークンコスト
  • references/cookbook.md — さまざまなチーム構成、タスクの種類、複数プロンプトの流れを示す、注釈付きプロンプトの例

このスキルの仕組み

  1. ユーザーの入力からタスクを理解します
  2. プロジェクトを調べ、既存のドキュメント、規約、設定を確認します
  3. 不明点を補うためにユーザーに質問します（実装の詳細度、完了条件、具体的な要件）
  4. 最適なチーム構成を設計します
  5. タスクが単一のプロンプトで済むか、複数のプロンプトを順に実行する必要があるかを判断します
  6. 自己完結した Markdown プロンプトを生成します
  7. 複数プロンプトの場合のみ：Claude（現在のチャット内）に claude -p で実行をリアルタイムにオーケストレーションさせるかユーザーに確認します（一度に 1 つずつ、またはワークフローで可能な場合は並列で実行します）。実行後に放置する bash スクリプトは絶対に生成しないでください。オーケストレーションは常にリアルタイムで行い、Claude は引き継ぎ内容を確認し、各移行時にユーザーに確認します。
  8. 品質チェックリストに照らして検証します
  9. 必ずプロンプトを .md ファイルとしてプロジェクトのルートに保存し、チャット内でクリック可能な Markdown リンクを共有します。プロンプト本文をインラインで表示してはいけません。ユーザーがオーケストレーションを選んだ場合は、Claude が Bash 経由でプロンプトを実行します。それ以外の場合は、ファイルを渡してコピー＆ペーストできるようにします。

ステップ 1：タスクを理解する

ユーザーの入力を注意深く読みます。たとえば、次のような内容が考えられます。

  • 機能リクエスト（「アプリにダークモードを追加する」）
  • 計画や仕様（実装計画の詳細）
  • 会話の文脈（「先ほど話し合った内容を踏まえて……」）
  • バグ報告（「ログイン後のリダイレクトの問題を修正する」）
  • 複数の要素を含むプロジェクト（「分析ダッシュボードを構築する」）

何を、なぜ行う必要があるのか、また、どのような制約が示されているかを把握します。

ステップ 2：プロジェクトのドキュメントを確認する

ユーザーに質問する前に、コーディングエージェントに役立つ情報が記載されたドキュメントがないか、プロジェクトを確認します。ドキュメントが存在するとは限らないため、見つかるものを確認して活用します。

確認する場所の例：

  • CLAUDE.md または .claude/CLAUDE.md — プロジェクトのガイドライン、規約、技術スタック
  • README.md — プロジェクトの概要、セットアップ手順
  • .claude/docs/ — アーキテクチャ、バックエンド、フロントエンド、データベースのドキュメント
  • docs/ — ドキュメントディレクトリ
  • package.json / requirements.txt / Cargo.toml — 依存関係とプロジェクトの種類
  • tsconfig.json / pyproject.toml / 類似の設定ファイル — 言語とビルドの設定
  • .claude/settings.json — 設定されている MCP サーバーと権限
  • ロードマップ、バックログ、タスク管理ファイル
  • ブランドガイドライン、スタイルガイド、デザインシステムのドキュメント

パスをハードコードしないでください。Glob を使って、存在するものを確認します。プロジェクトは React アプリ、Python バックエンド、Rust CLI、モノレポなど、どのようなものでもあり得ます。

見つかった情報のうち関連する部分を、生成するプロンプトに直接含めます。コーディングエージェントがプロジェクトの規約を知るためにファイルを読む必要がないよう、あらかじめ確認しておきます。

ステップ 3：基本的な質問をする

AskUserQuestion を使って、必ず次の質問をします。各質問には （推奨） の選択肢を含めてください。タスクの種類、プロジェクトの状況、確認した規約、リクエストの複雑さに基づいて、最適な既定値を選びます。ユーザーはいつでも変更できますが、推奨する選択肢には十分な根拠を持たせてください。

推奨する選択肢の決め方：

  • タスクの複雑さ、プロジェクトで確立されているパターン、ステップ 2 で確認した内容を分析します
  • ドキュメントが整備され、規約が明確なプロジェクトでは、AI が前提を置く選択肢、またはエージェントに判断を任せる選択肢を優先します（パターンがすでに確立されているためです）
  • 新規プロジェクトや曖昧なタスクでは、詳細を共同で決める選択肢を優先します
  • バグ修正では、エージェントに判断を任せる選択肢を推奨します（エージェントが調査する必要があるためです）
  • 大規模な機能では、共同で決める選択肢を推奨します（推測で進めるには判断事項が多すぎます）
  • テストについては、プロジェクトにすでにテスト環境がある場合、テストの合格を必須とする選択肢を推奨します
質問 1：実装の詳細レベル

ユーザーに希望するアプローチを尋ねます。分析に基づいて、いずれかを （推奨） として選択してください。

オプション A — 共同で詳細を決定： ユーザーと一緒に実装の詳細を検討します。アーキテクチャの選択、ライブラリ、UI パターン、データモデルなどについて、詳細な追加質問をします。生成するプロンプトにはこれらの決定事項をすべて明記し、コーディングエージェントがそのまま実装できるようにします。 推奨する場合：タスクが大規模または複雑である、コードベースにない新しいパターンを含む、設計上の判断に曖昧な点が多い。

オプション B — AI が詳細を決定： タスクとプロジェクトの既存パターンを分析し、ベストプラクティスとプロジェクトの規約に基づいて、実装上の判断をすべて行います。生成するプロンプトにはその判断を含めます。プロンプトを生成する前に、選択内容をユーザーに簡潔に説明します。 推奨する場合：プロジェクトに確立された規約があり、タスクが既存のパターンに沿っていて、適切なアプローチに確信がある。

オプション C — エージェントが詳細を決定： 生成するプロンプトでは、何を作るかを説明し、どのように実装するかはコーディングエージェントに委ねます。コーディングエージェントが実装方法を調査し、ツールやパターンを選択して、技術的な判断を行います。エージェントがプロジェクトとの一貫性を保てるよう、プロンプトにはプロジェクトの規約と制約も含めます。 推奨する場合：調査を伴うタスク（バグ修正、パフォーマンス改善）、実装が単純な場合、または見つかった状況に合わせてエージェントが柔軟に対応する必要がある。

質問 2：完了条件とテスト

タスクの完了条件が文脈から明らかでない場合は、推奨する選択肢を添えて質問します。

  • 「このタスクは、どのような状態になったら完全に完了とみなしますか？」 — タスクに応じた具体的な選択肢を提示します（例：「テストを含めて機能がエンドツーエンドで動作する」「バックエンド／API のみ完成」「MVP が動作すればよく、仕上げは後回し」）。
  • 「完了を確認するためのテストを作成し、合格させる必要がありますか？」 — プロジェクトにテスト基盤がある場合は はい を推奨します。純粋な調査タスクの場合に限り、いいえ を推奨します。
  • 「既存のテストはすべて引き続き合格する必要がありますか？」 — プロジェクトのドキュメントにテストコマンド（例：npm test、pytest）が記載されている場合は、具体的なコマンドを挙げて「はい、既存のテストをすべて合格させる必要があります」を推奨します。
質問 3：不足情報を補うためのヒアリング

ユーザーの依頼に不足している内容を基に、2～5 個の的を絞った質問をします。各質問には具体的な選択肢を 2～4 個用意し、そのうち 1 つを （推奨） として示します。推奨内容は、次の点を踏まえて決めてください。

  • プロジェクトですでに採用されている方式（既存のパターンに合わせる）
  • 技術スタックで標準的な方法
  • タスクの範囲に照らして妥当な内容

よくある質問領域 — すでに分かっている内容を踏まえて調整してください。

  • 範囲の境界：「モバイル対応、管理画面、エラー状態も含めますか？」
  • 統合箇所：「既存のエンドポイントに接続しますか、それとも新しく作成しますか？」
  • データモデル：「対象となるフィールドやテーブルは何ですか？新規ですか、既存のものですか？」
  • UI／UX：「特定のデザインパターンはありますか？既存ページに合わせますか、それとも新しいレイアウトにしますか？」
  • エッジケース：「[X に失敗した場合／ユーザーが Y を行った場合／データが空の場合] は、どのように動作させますか？」
  • 依存関係：「他の作業に依存しますか、または他の作業をブロックしますか？」

文脈から答えが明らかな質問は省略します。目的は不足情報を補うことであり、質問攻めにすることではありません。

質問 4：実行モード（複数のプロンプトが必要なタスクのみ）

ステップ 5 でタスクに複数のプロンプトが必要だと判断した場合は、どのように実行したいかユーザーに尋ねます。分割を決定した後にのみ尋ねてください。単一のプロンプトに対して実行モードを尋ねても意味がありません。

推奨を決めるには、まず次の点を内部で調査してください。

  1. モノレポですか？ ルートに複数の package.json、Cargo.toml、または個別のアプリディレクトリがあるか確認します。モノレポには、並行して作業できる独立したサブプロジェクトが含まれていることがよくあります。
  2. プロンプト間に強い依存関係はありますか？ プロンプト 2 がプロンプト 1 の出力（データベーステーブルや API エンドポイントなど）を必要とする場合は、必ず順番に実行します。プロンプトが完全に独立した領域を扱う場合は、並行実行できます。
  3. プロンプトが重複するファイルを扱いますか？ 該当する場合、ワークツリーなしでの並行実行にはリスクがあります。該当しない場合は、タスクを分離して並行実行しても安全です。
  4. Git ワークツリーは利用できますか？ git worktree list を実行して確認します。プロジェクトが Git リポジトリでない場合、ワークツリーは利用できません。

AskUserQuestion を使って、**（推奨）**の選択肢を付けた以下のオプションを提示します。

オプション A — 順次実行（プロンプトに依存関係がある場合に推奨）： 同じチャットセッションで、プロンプトを順番に実行します。それぞれのプロンプトは、前のプロンプトでコミットされた出力を基にします。最も安全な方法で、競合のリスクはありません。 推奨する条件：プロンプトに依存関係がある場合（プロンプト 2 がプロンプト 1 の出力を必要とする）、プロンプトが重複するファイルを扱う場合、またはタスクがパイプライン（スキーマ → API → フロントエンド）の場合。

オプション B — ワークツリーを使った並行実行（プロンプトが独立していて Git を利用できる場合に推奨）： 各プロンプトを、それぞれ専用の Git ワークツリーで別々の Claude Code セッションとして実行します。完全に分離されるため、各エージェントはリポジトリの独自のコピーを使います。最後に結果をマージします。 推奨する条件：プロンプトが完全に独立していて、Git を利用でき、プロジェクトがワークツリーをサポートしている場合。並行実行の選択肢の中では、これが最も安全です。

オプション C — 分離したタスクでの並行実行（プロンプトが独立していてモノレポの場合に推奨）： 各プロンプトを、同じリポジトリ上の別々の Claude Code セッションで実行しますが、ファイルの範囲は厳密に重複しないようにします。ワークツリーは不要ですが、範囲を慎重に管理する必要があります。 推奨する条件：明確に分かれたパッケージ／アプリ（例：frontend/ と backend/）を持つモノレポで、プロンプトがまったく異なるディレクトリを扱い、Git ワークツリーが利用できない、または実用的でない場合。

並行実行が安全かどうか判断できない場合は、順次実行を推奨し、その理由を説明してください。並行実行によるマージ競合や上書きのリスクは、順次実行にかかる時間よりもはるかに大きな問題です。

重要： ユーザーが並行実行を選んだ場合でも、プロンプト間でファイルの範囲が重複していると分かったら、異議を伝えてください。競合のリスクを説明し、次のいずれかを提案します。

  • 分離のためにワークツリーを使う
  • 重複がなくなるようプロンプトを再構成する
  • 順次実行を提案する

注： 自動オーケストレーション（コピー＆ペーストの代わりに claude -p でプロンプトを実行する方法）は、以下のステップ 6.5 でプロンプトを生成した後に提案します。ここでは提案しません。これにより、ユーザーは実際のプロンプトを確認してから決定できます。

ステップ 4：チーム構成を設計する

必ずエージェントチームを使います。タスクを分析し、最適なチーム構成を設計してください。

チーム構成のパターン

パターン A — 先に調査し、その後実装する： 適しているタスク：変更を加える前に、既存のコードを理解することが重要なタスク。

  1. メインエージェントが Explore サブエージェントを起動し、コードベースを並行して調査します
  2. メインエージェントが調査結果をまとめ、実装計画を作成します
  3. メインエージェントが実装の専門家でチームを編成します

パターン B — 最初から専門家が並行して作業する： 適しているタスク：明確に分割できる領域（フロントエンド＋バックエンド＋データベース）があるタスク。

  1. すぐに領域ごとの専門家でチームを編成します
  2. 各チームメンバーが、明確なファイルの担当範囲を持って領域を担当します
  3. チームメンバーは、自分の担当領域を調査するためにサブエージェントを活用します

パターン C — 順次進行のパイプライン： 適しているタスク：強い依存関係があるタスク（データベーススキーマ、API、フロントエンドの順など）。

  1. リードアーキテクトと実装担当者でチームを編成します
  2. アーキテクトが計画を立て、依存関係の順にタスクを作成します
  3. 実装担当者は、ブロックが解除されたタスクに着手します

パターン D — 調査してから分担する： 適しているタスク：バグ修正、パフォーマンスの問題、範囲が不明確なタスク。

  1. 調査担当者と修正担当者でチームを編成します
  2. 調査担当者が問題を調べ、具体的な修正タスクを作成します
  3. 修正担当者が並行して修正を実施します

タスクに合ったパターンを選びます。コーディングエージェントが理由を理解できるよう、生成するプロンプトで選択理由を簡潔に説明してください。

よくあるチーム構成
  • フルスタック機能： フロントエンド開発者＋バックエンド開発者＋テストエンジニア
  • バックエンド中心： API 開発者＋データベース開発者＋テストエンジニア
  • フロントエンド中心： UI 開発者＋状態／ロジック開発者＋テストエンジニア
  • バグ調査： 調査担当者＋フロントエンド修正担当者＋バックエンド修正担当者
  • リファクタリング： アーキテクト＋実装担当者 A＋実装担当者 B＋テスト責任者
  • インフラストラクチャ： DevOps リード＋設定スペシャリスト＋検証担当者

競合を防ぐうえで最も重要なこととして、各チームメンバーに明確なファイルの担当範囲を必ず割り当ててください。

チームの人数は 3～5 人にしてください。5 人を超えると、調整の負担が過剰になります。

ステップ 5：単一プロンプトにするか、複数に分けるかを決める

すべてのタスクが 1 つのプロンプトに収まるわけではありません。大規模なタスクでは、コンテキストウィンドウを使い切ったり、エージェントの集中力が続かなくなったり、終盤に雑な成果が出たりすることがあります。タスクを評価し、分割するかどうかを決めてください。

単一プロンプトを使う場合
  • タスクの焦点が絞られている：1 つの機能、1 つのバグ、1 つのリファクタリング
  • 3～5 人のチームが 1 回のセッションで作業を完了できる
  • 自然なフェーズの区切りがない（すべてを並行して進めるか、単純な依存関係で進められる）
  • 推定規模：変更するファイルが約 15 個未満、新規モジュールが約 3 個未満
複数のプロンプトに分割する場合

以下のいずれかに該当する場合は、分割してください。

  • 異なるチーム構成が必要となる自然なフェーズがある。 例：「トーナメントシステムの構築」には、基盤フェーズ（スキーマ＋コア API）、ゲームプレイフェーズ（マッチメイキング＋ブラケットロジック）、UI フェーズ（ページ＋コンポーネント）があります。各フェーズで必要な専門家は異なり、後続フェーズは先行フェーズの完了に依存します。

  • 単一のコンテキストウィンドウに収まらない規模である。 4 つ以上のモジュールにまたがって 20 個以上のファイルに変更が及ぶ場合、1 つのエージェントチームでは一貫性を保てなくなります。それぞれが動作し、テスト可能な成果を生む単位に分割してください。

  • 明確な依存関係の境界がある。 フェーズ 2 を始める前に、フェーズ 1 をデプロイ、マイグレーション、または人間がテストする必要がある場合、そこが自然な分割点です。例：API の構築に進む前に検証が必要なデータベースマイグレーション、アプリケーションのデプロイ前に必要なインフラストラクチャのプロビジョニング。

  • フェーズごとに必要な MCP ツールや権限が異なる。 例：フェーズ 1 ではスキーマ作業に Supabase が必要で、フェーズ 2 では E2E テストに Playwright が必要です。分割すれば各プロンプトの焦点が絞られ、事前チェックも個別にできます。

  • 調査／設計と実装が混在している。 「認証システムを再設計する」タスクでは、プロンプト 1 で調査とアーキテクチャ設計（成果物：設計ドキュメントとマイグレーション計画）を行い、続くプロンプト 2 でチームとともにマイグレーションを実行する必要があるかもしれません。

スマートな分割方法

目標は、各プロンプトで動作し、テスト可能な単位を完成させることです。未完成の骨組みで終わらせてはいけません。連続するプロンプトはそれぞれ、コードベースを正常な状態（テストが通り、壊れたインポートや不要なコードがない状態）にして終える必要があります。

分割戦略：

  1. レイヤーごと（ボトムアップ）： まずデータベース／スキーマ、次に API／バックエンド、最後にフロントエンドを実装します。各プロンプトは、前のプロンプトでコミットされた成果を基に進めます。新規開発の機能に最適です。

  2. 機能単位（垂直分割）： 各プロンプトで、1つのサブ機能について、データベース、API、UIを含む垂直スライスを完成させます。独立したサブ機能を含む大規模な機能に最適です（例：「トーナメント作成」をプロンプト1、「ブラケット管理」をプロンプト2、「トーナメント UI」をプロンプト3で実装）。

  3. フェーズごと（設計 → 構築 → 仕上げ）： プロンプト1で調査を行い、設計ドキュメントとテスト計画を作成します。プロンプト2で主要部分を実装します。プロンプト3で境界ケース、エラー処理、仕上げ、最終テストに対応します。複雑なリファクタリングや移行に最適です。

  4. リスクレベルごと： プロンプト1で、最もリスクが高く不確実な部分（概念実証、スパイク）に取り組みます。アプローチの妥当性が確認できたら、プロンプト2で残りを構築します。アプローチがうまくいくかユーザーが確信を持てない場合に最適です。

複数プロンプトの連続実行ルール

連続する各プロンプトには、次の内容を含める必要があります。

  1. シーケンスヘッダーで始める — 何番目のプロンプトか、これまでに何が完了したかを明確に記載します。

    ## Sequence: Prompt N of M — [Phase Name] ### What previous prompts completed: [brief summary of what's already done and committed] ### What this prompt will do: [brief summary of this phase's goal]

  2. プロジェクトコンテキストのセクション全体を含める — 各プロンプトは記憶がない新しいセッションに貼り付けられます。規約や技術スタックなどを、毎回あらためて含めてください。これは必須です。

  3. 独自の開始前チェックを含める — プロンプトで MCP ツールが必要な場合は、それらをテストします。また、前のプロンプトの成果が存在することも確認します（例：「list_tables を実行して、notifications テーブルが存在することを確認する」）。

  4. 独自の完了条件を含める — このフェーズに固有の条件を設定します。最初に「前の作業を検証する」手順を含めてください（例：「新しい作業を始める前に、プロンプト1のテストがすべて引き続き通ることを確認する」）。

  5. 独自の作業ルールを含める — 通常のルールと同じ基準を適用します。

  6. 引き継ぎメモで終える — 次のプロンプトで行う作業をエージェントに伝え、コードベースを適切な状態で引き渡せるようにします。例：「次のプロンプトでは、この機能のフロントエンドを構築します。このプロンプトを完了とする前に、すべての API エンドポイントが動作し、ドキュメント化されていることを確認してください。」

分割案をユーザーに提示する

生成前に、AskUserQuestion を使って選択肢とともに分割案を提示します。必ず （推奨） の選択肢を含めます。

  • 単一プロンプト（スコープが小さい場合に推奨）：「このタスクは1つのプロンプトで対応できます。1チーム、1セッションです。」
  • N 個のプロンプト — ［分割戦略］（スコープが大きい場合に推奨）：「理由は［理由］です。そのため、N 個のプロンプトに分けることをおすすめします。内訳は次のとおりです：…」
  • 選択を任せる：「スコープを分析し、最適な分割方法を選びます。」

分割案ごとに、次の点を簡潔に説明します。

  • プロンプトの数と、その理由
  • 各プロンプトで対応する内容
  • 依存関係の順序
  • 各プロンプトに必要なチーム構成の目安

生成前に、ユーザーが確認または調整します。

ユーザーが複数プロンプトへの分割を承認した場合は、直ちにステップ3の**質問4（実行モード）**に進み、順次実行か並列実行かを判断します。

Parallel 固有の分割ルール

ユーザーが並列実行を選択した場合、分割には次の追加制約を満たす必要があります。

  1. プロンプト間でファイルが一切重複しないこと。 各プロンプトは、完全に重複しないディレクトリ／ファイルのセットを担当する必要があります。共有ファイルは認められません。2 つのプロンプトがどちらも package.json や共有設定ファイルを編集する必要がある場合、それは競合です。分割を再構成するか、共有ファイルの編集をすべて 1 つのプロンプトに担当させてください。

  2. プロンプト間に実行時の依存関係がないこと。 Prompt A が作成するデータベーステーブルを Prompt B が読み取る場合、2 つを並列実行することはできません。各プロンプトが完全に独立して実行できるよう、分割を再構成してください。

  3. 各プロンプトはファイル境界を最上位レベルで宣言すること。 チームメイトごとだけでなく、プロンプト全体のファイル境界を宣言してください。これにより、どのエージェントがリポジトリのどの部分を担当するかが明確になります。

  4. マージ戦略を定義すること。 実行ガイドでは、並列作業をどのようにマージして統合するかをユーザーに伝える必要があります。

    • ワークツリーの場合：どのブランチを先にマージするか、想定されるマージ競合（ある場合）、および解決手順
    • 分離されたタスクの場合：すべてのプロンプト完了後に実行する最終検証手順（テストスイート全体の実行、インポートの競合確認など）

  5. 最終統合プロンプトが必要になる場合があります。 並列プロンプトの成果を接続する必要がある場合（例：別のプロンプトで構築された新しいバックエンドエンドポイントをフロントエンドから呼び出す場合）、各要素を接続してエンドツーエンドテストを実行するための、短い最終「統合プロンプト」を追加してください。

ステップ 6：プロンプトを生成する

各プロンプトには、次のセクションをこの順序で含めてください。各プロンプトは自己完結している必要があります。コンテキストがまったくない新しい Claude Code セッションでも実行できるようにしてください。

プロンプトの構成

セクション 0 — シーケンスヘッダー（複数プロンプトの場合のみ） 複数プロンプトのシーケンスの一部である場合は、次のように始めてください。

## Sequence: Prompt N of M (Sequential) — [Phase Name]
### What previous prompts completed: [完了した作業の概要]
### What this prompt will do: [このフェーズの目標]
### Git root for this prompt: [絶対パス。例：/path/to/your/repo — ワークツリーモードでオーケストレーターが使用]

並列モードの場合：

## Parallel Task: Prompt N of M — [Phase Name]
### Execution mode: PARALLEL — this prompt runs independently alongside other prompts
### This prompt's file boundaries: [このプロンプトが排他的に担当するディレクトリ／ファイルの一覧]
### What this prompt will do: [このフェーズの目標]
### DO NOT touch these files (owned by other parallel prompts): [他の並列プロンプトが担当するファイルの一覧]
### Git root for this prompt: [絶対パス。オーケストレーターがワークツリーの作成に使用]

単一プロンプトの場合、このセクションは省略してください。

セクション 0.5 — 最初に引き継ぎファイルを読む（複数プロンプトの場合のみ）

何かを始める前に（事前確認よりも先に）、エージェントはプロジェクトルートにある共有引き継ぎファイル orchestrate-handoff.md を読む必要があります。

ファイルが存在しない場合は問題ありません。これは Prompt 1 であるか、ユーザーがオーケストレーションを使用しない選択をしています。そのまま続行してください。

ファイルが存在する場合、エージェントは次の作業を行う必要があります。

  1. ブロッカー（### BLOCKER: 見出し）や、以前のプロンプトから未解決の手動手順がないか確認する
  2. このプロンプト宛てのメモ（### Notes for Prompt N）を確認し、計画に反映する
  3. 以前のプロンプトが行った変更のうち、このプロンプトの事前確認に影響するものがないか確認する
  4. このプロンプトだけでは解決できないブロッカーが見つかった場合は、停止して === BLOCKED: PROMPT N OF M — <reason> === を出力し、終了する

プロンプトには次を埋め込んでください。

作業を始める前に、次を実行してください。
    cat orchestrate-handoff.md 2>/dev/null || echo "(引き継ぎファイルはまだありません — Prompt 1 では問題ありません)"
すべてのセクションを読んでください。このプロンプトの事前確認と照合してください。以前のプロンプトで、このプロンプトが依存する未解決のブロッカーが残されている場合は、停止して BLOCKED センチネルを出力してください。

セクション 1 — ミッション概要 何を構築するのか、その理由、最終目標を 1 つの段落で明確に説明してください。複数プロンプトのシーケンスでは、プロジェクト全体ではなく、このプロンプトが達成する範囲に絞ってください。 Section 2 — 事前チェック（認証情報、MCP ツール、前回の出力）

このセクションには 3 つのパートがあります。該当するものを含めてください。

2a — 認証情報の取得元（プロンプトで外部サービス（AWS、GCP、Azure、Supabase の service-role、Stripe、OpenAI、Datadog など）を使用する場合は必須）

エージェントは、環境変数を引き継がない新しいシェルで実行されます。認証情報が自動的に使える状態にはなりません。プロンプトでは、次の内容を明示的に指示する必要があります。

  1. ユーザーのプロジェクト内のどこに認証情報があるか（ファイルパス、MCP サーバー、シークレットマネージャー、.zshrc で設定された環境変数など）
  2. すべてのシェルセッションの開始時に認証情報を読み込むための正確なコマンド
  3. 認証情報が見つからない場合の対応（作業を停止してユーザーに伝えること。明示的に許可されていない限り、SSO、インスタンスロール、対話型プロンプトなどの別の認証方法に決して切り替えないこと）

ステップ 2 でプロジェクトを調べ、認証情報が実際にどこにあるかを確認してください。よくあるパターンは次のとおりです。

  • プロジェクトルートまたはサブフォルダーにある .env ファイル（set -a; source <path>; set +a で読み込む）
  • MCP サーバー（例：Supabase MCP — 設定を .claude/settings.json に記載）
  • ~/.aws/credentials にある AWS プロファイル（まれです。ほとんどのユーザーは .env または SSO を使用します）
  • direnv／asdf／mise の設定による環境変数

確認したパスと読み込みコマンドを、プロンプトに直接記載してください。例：

### AWS credentials

AWS 認証情報は `api/.env` にあります。`aws` コマンドを実行する前に読み込んでください。

    set -a
    source /Users/me/projects/myapp/api/.env
    set +a

使用する環境変数：`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_REGION`。プロファイル：`default`。`api/.env` にこれらがない場合は、作業を停止してユーザーに伝えてください。

ステップ 2 で認証情報の取得元が見つからない場合は、プロンプトを生成する前にユーザーに確認してください。推測してはいけません。初回実行時に認証情報エラーが発生するプロンプトは不完全です。

2b — MCP ツールと権限（タスクで MCP ツールを使用する場合）

コーディングエージェントに、必要な各ツールを最小限の操作ですぐにテストするよう指示してください。例：

  • Supabase：list_tables または簡単な SELECT を使った execute_sql
  • Playwright：アプリに移動してスクリーンショットを撮影
  • Datadog：基本的なクエリを使った get-monitors または search-logs

ツールが 1 つでも失敗した場合、エージェントはただちに作業を停止し、失敗したツールと不足している権限を正確に報告して、ユーザーが問題を解決するまで待つ必要があります。作業を停止してよい理由はこれだけです（2a の認証情報の問題を除きます）。

すべてのツールが動作する場合、エージェントは「事前チェックに合格しました。すべてのツールを確認しました。続行します。」と報告し、待つことなくただちに作業を続けます。

MCP ツールが不要な場合は、このパートを省略してください。

2c — 前回のプロンプトの検証（複数プロンプトを使う場合のみ。プロンプト 2 以降）

前回のプロンプトの出力が存在することを確認する手順を追加してください。例：「list_tables を実行して notifications テーブルが存在することを確認する」「curl テストを実行して /api/teams エンドポイントが応答することを確認する」「cd backend && npm test を実行して前回の作業が引き続き成功することを確認する」。検証に失敗した場合は作業を停止し、まず前回のプロンプトを再実行するようユーザーに伝えてください。

Section 3 — プロジェクトのコンテキスト ステップ 2 で確認した、関連するプロジェクトのドキュメントを埋め込んでください。

  • 技術スタックと規約
  • ファイル構成と命名パターン
  • テスト要件とコマンド
  • スタイルガイドライン、デザイントークン、ブランドのトーン
  • 関連するアーキテクチャ上の決定事項

実際の内容を埋め込んでください。「CLAUDE.md を読む」や「docs フォルダーを確認する」と書いてはいけません。エージェントはコンテキストをまったく持っていないため、すでに読んだファイルを読むのに時間を費やさせてはいけません。

Section 4 — タスクの仕様 構築するものを詳しく説明します。詳細度はユーザーの選択によって異なります。

  • オプション A：ユーザーと話し合った内容に基づく、完全な実装の詳細
  • オプション B：明確に示した、こちらで決定した実装方針
  • オプション C：機能要件のみを示し、実装方法はエージェントが決定 セクション 5 — エージェントチームへの指示 チーム作成に関する明示的な指示：
  • 使用するパターン（A/B/C/D）とその理由
  • 参加させるチームメイトの人数と各自の役割
  • チームメイトごとの正確なファイル境界（各自が担当し、触れてはならないディレクトリ／ファイル）
  • 各チームメイトが調査に使用するサブエージェント
  • コミュニケーションプロトコル（リードに連絡するタイミング、チームメイト同士で連絡するタイミング）
  • 依存関係を含むタスクの分解
  • チームメイトごとに 5～6 個のタスクを割り当てる

エージェントが手順どおりに実行できる、明確な番号付きの計画として記述します。

セクション 6 — 完了条件と検証 「完了」の定義を明示したチェックリスト：

  • 機能要件を満たしていること（各要件を列挙）
  • テストを作成し、パスしていること（正確なコマンドを指定）
  • 既存のテストが引き続きパスしていること（正確なコマンドを指定）
  • 型エラー／リントエラーがないこと
  • 手動での検証手順
  • プロジェクトで課題管理を使用している場合は、バックログやタスク管理の更新

セクション 7 — 作業ルール 生成するすべてのプロンプトに含める標準ルール：

  • 事前確認の失敗を除き、すべての完了条件を満たすまで作業を中断しないこと

  • エラーが発生したら、ユーザーに尋ねずにデバッグして修正すること

  • チームメイトの作業が別のメンバーの作業と衝突した場合は、リードが直ちに解決すること

  • 作業を段階的にコミットすること（未コミットの変更を残したままコンテキストウィンドウを期限切れにしないこと）

  • Project Context セクションに記載されたプロジェクトのコーディング規約に正確に従うこと

  • 不要な抽象化や、依頼を超える過剰な設計を行わないこと

  • 完了したら一時ファイルを削除すること

  • ユーザーのタスクを完全に解決するまで作業を続けてから、処理を返すこと

セクション 8 — 完了時の引き継ぎとセンチネル（複数プロンプトの場合のみ）

最終センチネルを出力する前に、エージェントはステータスブロックをプロジェクトルートの orchestrate-handoff.md に追記しなければなりません（ファイルが存在しない場合は作成します）。このブロックは、プロンプトをまたいで保持される記録であり、次のエージェントとオーケストレーターに何が行われたかを伝えます。

エージェントが追記するテンプレート（Markdown をそのまま使用し、角括弧内を置き換えます）：

---

## Prompt N of M — [Phase Name] — [DONE | FAILED | BLOCKED]
_Completed at: [ISO-8601 timestamp]_

### Summary
[実際に作成／変更した内容を 2～5 個の箇条書きで記載]

### Files changed
[パスを 1 行に 1 つずつ記載]

### Decisions made (deviations or judgment calls)
[プロンプトの仕様から逸脱した箇所、または仕様で未定義の判断を行った箇所]

### BLOCKER:
[ステータスが BLOCKED の場合にのみ、このセクションを含めます。ブロッカー、そのブロッカーを自動解決できない理由、解消のためにユーザーが行うべきことを 1 段落で記載します。ブロッカーがない場合は、このセクション全体を省略します。]

### Notes for Prompt N+1
[次のプロンプトを担当するエージェントに知っておいてほしいことのうち、そのプロンプトの仕様に記載されていない情報を記載します。例：「古いテーブルが存在していたため、テーブル名を `browserSession` ではなく `browserSessionV2` にしました」]

追記後、エージェントはセンチネルを最後の行として出力します。

成功時：

=== DONE: PROMPT N OF M ===

回復不能な失敗時（合理的なデバッグを尽くした後）：

=== FAILED: PROMPT N OF M — <one-line reason> ===

ユーザーの対応が必要なブロッカーの場合（例：手動でのマイグレーション適用、シークレットのローテーション、ユーザーのみが変更できる IAM 設定）：

=== BLOCKED: PROMPT N OF M — <one-line reason> ===

オーケストレーターは grep を使って 3 種類の状態を検出します。FAILED の場合は停止します。BLOCKED の場合は停止し、ブロッカーのセクションをユーザーに表示します。DONE の場合は、引き継ぎ内容を再読して、エージェントがセンチネルで報告し忘れたブロッカーがないか確認してから、次のプロンプトに進みます。

単一プロンプトのタスクでは、このセクション全体を省略します。コピー＆ペーストのみの複数プロンプト実行（ユーザーがステップ 6.5 でオーケストレーターを使用しないことを選択した場合）では、引き継ぎとセンチネルを残します。オーケストレーターがなくても、後で参照できる記録として役立つためです。

ステップ 6.5：オーケストレーションについて尋ねる（プロンプト作成後、複数のプロンプトがある場合のみ）

プロンプトの .md ファイルができたので、ユーザーは各プロンプトが何をするのかを実際に確認できます。ユーザーに代わって実行をオーケストレーションするかどうかを尋ねるのは、このタイミングです（このチャット内の Claude が行います）。それより前に尋ねてはいけません。まずユーザーがプロンプトを確認し、その後で決定します。

AskUserQuestion を使い、**（推奨）**の選択肢を設けてください。

質問：このチャット内で、私がプロンプトをオーケストレーションしましょうか？

選択肢 A — はい、あなたがオーケストレーションする（複数のプロンプトがある場合に推奨）： あなた（現在のチャット内の Claude）が Bash ツールを使って claude -p 経由でプロンプトを実行し、チェーン全体を停止せず最後まで実行します。実行のたびに共有の orchestrate-handoff.md を読み、各実行後に短い進捗報告をしますが、続行の許可を求めてはいけません。DONE センチネルがあれば、直ちに次のプロンプトを実行します。ユーザーはいつでも中断できます。各ステップの実行を個別に許可する必要はありません。FAILED または BLOCKED の場合にのみ停止します。

オーケストレーションするなら、徹底してオーケストレーションしてください。 ユーザーが各プロンプトを手動で実行したいのであれば、コピーして貼り付ける方を選んでいます。各プロンプトの後に「プロンプト N+1 に進みますか？」と尋ねるのでは、この選択肢の目的が台無しになります。また、このスキルがユーザーの時間を無駄にする最もよくある原因です。絶対に尋ねてはいけません。

複数のプロンプトがある場合は、常にこちらを推奨してください。ユーザーは、コピーと貼り付けの手間をかけずに進捗を把握したいと考えています。

選択肢 B — いいえ、コピーして貼り付けるだけにする： .md ファイルを渡すだけにします。ユーザーは新しいチャットを開き、それぞれを手動で実行します。

ユーザーがすべてを把握したうえで各ステップを自分で進めたい場合、またはチェーンの信頼性に確信が持てない場合に推奨してください。

実行後に放置する Bash スクリプトは絶対に生成しないでください。 失敗を隠し、ユーザーの判断を省き、「あとは放置できる」という体験は幻想にすぎません。実際のインフラ作業では何かが壊れるものです。何が起きたのかわからない 90 分間の記録をデバッグするより、ステップごとに実行する方が優れています。チェックポイントを設けた Claude によるオーケストレーションの方が、間違いなく適切です。

ユーザーが A を選んだ場合は、claude -p のフラグを確認してください。デフォルトは次のとおりです。

  • --permission-mode bypassPermissions — 各プロンプト内で自律的に実行し、対話型のプロンプトを表示しません
  • --output-format stream-json — 各ターンの進捗をリアルタイムで出力します
  • --verbose — ログにツールの使用状況をすべて記録します
  • 標準出力を logs/prompt-N.transcript.jsonl に、標準エラー出力を logs/prompt-N.log にリダイレクトします

ユーザーに別の希望（bypass ではなく acceptEdits、ツールの許可リストの制限、--model claude-sonnet-4-5-20250929 のようなモデルの上書きなど）がある場合は、ここで確認してください。各プロンプトの実行時にその設定を使用します。

ステップ 6.6：手動でオーケストレーションする（ステップ 6.5 でユーザーが選択肢 A を選んだ場合のみ）

あなた（このチャット内の Claude）が実行の最初から最後まで自分でオーケストレーションし、許可を求めて停止することはありません。 各 claude -p 呼び出しは Bash ツール経由で実行します。実行のたびに引き継ぎ情報を読み、短い進捗報告をします。DONE なら、次のプロンプトを直ちに実行します。FAILED または BLOCKED の場合にのみ停止します。

バックグラウンドでチェーンを実行するランナーを使ってもかまいません（長いチェーンでは推奨します）。たとえば、プロンプト N を実行し、センチネルを確認して、DONE なら N+1 を実行する小さなスクリプトです。ただし、失敗を隠すランナーは使ってはいけません。FAILED または BLOCKED で停止し、何が起きたのかを正確に報告できるよう、センチネルとログをそのまま残す必要があります。

実行モード（逐次または並列）は、プロンプト間の依存関係によって異なります。ワークフローに合ったものを選んでください。

  • 逐次： プロンプト間に強い依存関係があります（P2 が P1 のコミット済み出力を読み取るなど）。1 つずつ実行し、それぞれの完了を待ってから引き継ぎ情報を読み、続行するか判断します。
  • worktree 並列： プロンプト同士が独立しており、それぞれに一意の Git root for this prompt が指定されています。各プロンプトをバックグラウンドで実行し、それぞれの指定された Git ルート内に作成した専用 worktree で実行します（親のモノレポレベルには決して作成しないでください。親は多くの場合、未追跡です）。すべての完了を待ってから、worktree をマージします。
  • 分離並列： プロンプト同士が独立しており、同じリポジトリ内の重複しないディレクトリを対象としています。worktree は使わず、すべてをバックグラウンドで実行し、完了を待ってから検証します。
引き継ぎファイルを初期化する（必ず最初に）

最初のプロンプトを実行する前に、プロジェクトルートに orchestrate-handoff.md が存在しない場合は作成します。

cat > orchestrate-handoff.md <<'EOF'
# オーケストレーション引き継ぎログ

_作成日時：<ISO timestamp>_

プロンプトチェーンで共有するノートです。各プロンプトは次の処理を行います。
- 作業開始時にこのファイルを読み込みます（セクション 0.5）
- DONE／FAILED／BLOCKED を出力する前にステータスブロックを追記します

オーケストレーター（親チャットの Claude）は、プロンプト間でこのファイルを読み込み、ブロッカーを検出して続行するかどうかを判断します。

EOF
順次オーケストレーション

各プロンプトについて、順番に次の操作を行います。

  1. 引き継ぎ内容を事前確認し、以前のプロンプトから未解決のブロッカーが残っていないか確認します。

    cat orchestrate-handoff.md | grep -A 10 "^### BLOCKER:"

    ブロッカーが存在し、その下に対応する ### RESOLVED: エントリーがない場合は、停止します。ブロッカーをそのままユーザーに表示し、どうするか尋ねてください（ユーザーがすでに別途解決していて、RESOLVED の行を追記するだけでよい場合や、中止を希望する場合があります）。

  2. run_in_background: true を指定して、Bash からプロンプトを実行します。

    mkdir -p logs
claude -p "$(cat prompt-N-name.md)" \
  --permission-mode bypassPermissions \
  --output-format stream-json \
  --verbose \
  > logs/prompt-N.transcript.jsonl \
  2> logs/prompt-N.log

    バックグラウンド実行から返される shell_id を記録します。

    重要 — 必ずバックグラウンドで実行し、フォアグラウンドでは実行しないでください（10 分の上限があるため）。 Bash ツールのフォアグラウンドのタイムアウトは最大 600000 ミリ秒（約 10 分）です。実際のエージェントチームのプロンプトはこれよりはるかに長く実行されます（P プロンプトは実際に 10～60 分以上、または 60 ターン以上かかります）。そのため、フォアグラウンドで claude -p を実行すると、実行途中で強制終了されます。これが長時間のオーケストレーションを妨げる制約です。run_in_background: true を指定するとプロセスは切り離され、10 分の上限を超えても実行を続け、終了時に再度通知されます（そのため、完了を待つためにポーリングする必要もありません）。これはオーケストレーションで必ず守ってください。

    現在の Claude Code（2.1.x で確認済み）には --max-turns の上限はありません。このフラグは存在しません。 過去に長時間の実行が途中で打ち切られる問題は、ターン数の上限ではなく、上記のフォアグラウンドのタイムアウトが原因でした。--max-budget-usd はデフォルトでは無効で、明示的に指定した場合のみ有効です。長時間の自律実行では指定しないでください。上限額に達したとき、ビルドの途中でプロンプトが強制終了される可能性があります。ユーザーが明示的に支出上限を希望する場合を除き、指定しないでください。

    ヒント：「P(N) の開始前に RESOLVED の引き継ぎ内容を読み込む」要件を満たすには、引き継ぎ内容の追記と claude -p の実行を同じバックグラウンドコマンドに含めます（cat >> orchestrate-handoff.md <<'EOF' ... EOF の後に claude -p の行を続けます）。これにより、別々のツール呼び出しが競合することなく、切り離されたシェル内で順序が保証されます。

  3. 完了を監視するため、トランスクリプトファイル内のセンチネルをポーリングします。Bash を使って定期的に grep してください（ビジーループは使わず、長時間かかるプロンプトでは確認の間隔を 30～60 秒空けます）。

    grep -E "=== (DONE|FAILED|BLOCKED): PROMPT N" logs/prompt-N.transcript.jsonl

    grep が一致を返したら、プロンプトは完了です。（セッションで遅延 Monitor ツールを利用できる場合は、ストリーミング検出にそちらを使ってください。通常の Bash によるポーリングは、どこでも使える代替手段です。）

  4. 引き継ぎファイルを読み、プロンプトが実際に行った内容を確認します。

    cat orchestrate-handoff.md

    最新のステータスブロック（Prompt N のもの）を見つけます。作成されたもの、変更されたファイル、決定事項をチャットでユーザーに要約します。

  5. センチネルに基づいて判断します。

    • DONE → 引き継ぎ内容の要約を含む短い進捗メモを投稿し、ただちに次のプロンプトのためにステップ 1 に戻ります。確認を求めたり、待ったりしないでください。
    • BLOCKED → ### BLOCKER: セクションをそのままユーザーに表示します。ブロッカーを解決し（マイグレーションの適用、シークレットのローテーションなど）、ブロッカーの下に ### RESOLVED: <how> の行を orchestrate-handoff.md に追記するよう依頼してください。ユーザーが解決を確認するまで先に進まないでください。
    • FAILED → 失敗理由とログの末尾約 50 行を表示します。再試行、スキップ、中止のどれにするか、ユーザーに尋ねてください。
並列オーケストレーション（worktree モード）

各プロンプトのセクション 0 で固有の Git root for this prompt が指定されており、どのプロンプトも同じ git root を共有していない場合にのみ使用してください。親のモノレポフォルダーは通常 git リポジトリではありません。worktree は各サブリポジトリ内に作成する必要があります。

  1. 事前検証：各プロンプトの Git root for this prompt: の行を解析します。2 つのプロンプトが同じ git root を共有している場合は、並列 worktree の実行を拒否し、プロンプトを再構成するか、並列分離モードを使うようユーザーに伝えます。

  2. 引き継ぎを初期化（上記と同様）。

  3. 各プロンプトについて、宣言された git root 内に worktree を作成し、claude -p をバックグラウンドで実行します。作業ディレクトリは worktree にします。

    cd <gitRoot>
git worktree add .orchestrate-wt/prompt-N -b orchestrate/prompt-N HEAD
cp <projectRoot>/prompt-N-name.md <gitRoot>/.orchestrate-wt/prompt-N/
cp <projectRoot>/orchestrate-handoff.md <gitRoot>/.orchestrate-wt/prompt-N/

cd <gitRoot>/.orchestrate-wt/prompt-N
claude -p "$(cat prompt-N-name.md)" \
  --permission-mode bypassPermissions \
  --output-format stream-json \
  --verbose \
  > <projectRoot>/logs/prompt-N.transcript.jsonl \
  2> <projectRoot>/logs/prompt-N.log &

    各バックグラウンドプロセスの shell_id を記録します。

  4. すべての処理が完了するまで待機します。各トランスクリプトをポーリングしてセンチネルを確認します。すべてのプロンプトが DONE／FAILED／BLOCKED になるまで、wait を先に進めないでください。

  5. 引き継ぎ内容を統合します。各並列プロンプトは、worktree 内にある独自の orchestrate-handoff.md に書き込みます。worktree から追加された各セクションをプロンプト番号順に連結し、プロジェクトルートの引き継ぎファイルに統合します。

    for i in 1..N: tail the new section from <gitRoot>/.orchestrate-wt/prompt-$i/orchestrate-handoff.md and append to <projectRoot>/orchestrate-handoff.md

  6. すべての結果をユーザーに要約します。BLOCKED または FAILED のプロンプトがあれば、それぞれ個別に提示します。ユーザーが明示的に「clean up」と指示するまで、worktree は確認用に残します（その後、各 worktree に対して git worktree remove を実行します）。

並列オーケストレーション（分離モード）

並列 worktree と同様ですが、git worktree add の手順を省略します。各プロンプトは、宣言された git root 内で直接実行します（指定がない場合はプロジェクトルート）。引き継ぎファイルは共有されます。複数のバックグラウンドプロセスが 1 つのファイルに追記すると、行が混在する可能性があります。そのため、各プロンプトの追記は単一のアトミックな書き込み（行ごとではなく、1 つの heredoc）にしてください。この方法を採用する場合は、そのリスクをユーザーに伝えてください。判断に迷う場合は、並列 worktree を推奨します。

ブロッカー解消後の再開

ユーザーがブロッカーを解消し、続行を指示した場合：

  1. orchestrate-handoff.md のブロッカーの下に ### RESOLVED: 行があることを確認します。ない場合は、追加するようユーザーに依頼します（または、ユーザーが説明した解決内容を使って自分で追加します）。
  2. ブロックされていたプロンプトから再開します。そのプロンプトを再実行すると、そのセクション 0.5 で引き継ぎファイルが読み込まれ、RESOLVED 行を確認して、以前ブロックされていた条件を通過します。
フラグ

ステップ 6.5 でユーザーが確認した内容を使用します。デフォルトは次のとおりです。

--permission-mode bypassPermissions
--output-format stream-json
--verbose

ユーザーがモデルを選択した場合は --model <name> を追加します。制限付き許可リストを使用する場合は --allowedTools "..." を追加します。追加のコンテキストディレクトリを指定する場合は --add-dir <path> を追加します。

チャットに表示する内容（プロンプト間）

各プロンプトの完了後、次の形式で投稿します。

プロンプト N 完了 — [フェーズ名]

要約：

  • [引き継ぎ内容の箇条書き]
  • [引き継ぎ内容の箇条書き]

変更ファイル：[件数と主要なパス]

決定事項：[引き継ぎ内容にある特記事項]

プロンプト N+1 を開始します。

BLOCKED の場合は、ブロッカーのテキストと、プロンプトのエージェントが ### BLOCKER: に記載した解決手順をそのまま投稿します。FAILED の場合は、失敗理由とログ末尾を投稿します。

チェーンの正常完了時のクリーンアップ

実行後は、必ずプロンプトファイルを削除してください。これは毎回必須であり、任意ではありません。すべてのプロンプトが DONE の状態でチェーンが終了した場合（FAILED や BLOCKED がない場合）、オーケストレーションの最後の手順として、プロジェクトルートからプロンプトの .md ファイルを削除します。プロンプトは一度だけ使う仕様書です。実行して検証した後は、不要なファイルになります。次のファイルは残します。

  • orchestrate-handoff.md — 実施内容の永続的な記録です。ユーザーが後から読む場合があります
  • logs/ — 実行のトランスクリプトと stderr の永続的な記録です

次のファイルは削除します。

  • このスキルがプロジェクトルートに生成した prompt-*.md ファイル

グロブを使ってください。プロジェクトルートで prompt-*.md に一致するファイルはすべて対象です。

rm -f /absolute/project/root/prompt-*.md

これは意図的に広い範囲を対象とします。ユーザーが削除し忘れた、以前のチェーンの孤立したプロンプトファイルも削除します。prompt-*.md という接頭辞は十分に固有なので、プロジェクトルートの他のファイルが誤って一致することはありません。

削除したファイルを列挙した確認メッセージを、チャットに一行で出力します。

クリーンアップ完了：prompt-1-foo.md、prompt-2-bar.md、prompt-3-baz.md、prompt-A0-orphan.md を削除しました（handoff と logs は保持しました）

FAILED または BLOCKED の場合は削除しないでください。 ユーザーが問題を解決した後で再実行する必要がある場合があります。削除するのは、すべてのプロンプトのセンチネルが DONE の場合に限ります。

コピー＆ペーストモードの場合も同様です。 ユーザーがプロンプトを手動で実行した場合（オプション B）でも、実行が完了したら（ユーザーが完了を確認したとき、またはその後このセッションに戻ったとき）、prompt-*.md をすべて削除してください。「参照用」として残してはいけません。永続的な記録として残すのは handoff と logs です。完了後に残るファイルは orchestrate-handoff.md と logs/ だけです。

ステップ 7：検証と出力

各プロンプトを頭の中で作成した後、以下の品質チェックリストに照らして、問題がないか確認してください。任意で、プロンプトの内容を echo して検証スクリプトに渡すこともできます。

echo "prompt content here" | bash scripts/validate-prompt.sh

このスクリプトは、よくある書式の問題（コードブロックの崩れ、セクションの不足、シーケンスヘッダーなど）をチェックします。

出力形式

出力は常に、プロジェクトルートに保存された 1 つ以上の .md ファイルです。チャットメッセージは、短い概要とクリック可能なリンクのみです。プロンプト本文をチャットに貼り付けてはいけません。

単一のプロンプト： prompt-<short-task-name>.md という形式でファイルを 1 つ作成します。例：prompt-fix-auth-bug.md、prompt-add-dark-mode.md、prompt-refactor-billing.md。名前は約 50 文字以内の kebab-case にします。その後、チャットメッセージには次の内容を含めます。

  • プロンプトで作成するものの概要（1 段落、または箇条書き 2～3 項目）
  • ファイルへのクリック可能な Markdown リンク（絶対パス）
  • 該当する場合はオーケストレーションに関する質問（ステップ 6.5）、該当しない場合はコピー＆ペーストのヒント

単一のプロンプトのチャット出力例：

一式をまとめました。ファイルはこちらです。

[prompt-fix-auth-bug.md](/Users/me/Documents/myproject/prompt-fix-auth-bug.md)

概要：ログインフローのリダイレクトの問題を調査し、`auth/session.service.ts` のセッション更新処理を修正して、回帰テストを追加します。チームは 1 つ、チームメイトは 2 人（調査担当＋修正担当）です。

内容を確認してから、`claude -p` で実行する場合は「go」と伝えるか、新しいチャットにご自身で貼り付けてください。

複数のプロンプト（逐次または並列）： プロジェクトルートに、それぞれ別の .md ファイルとしてプロンプトを作成します。説明的な名前を使ってください。

prompt-1-foundation.md
prompt-2-gameplay.md
prompt-3-frontend.md
prompt-integration.md   (並列実行の場合に必要)

その後、チャットには次の内容だけを出力します。

  • 実行順序、各プロンプトの内容、実行方法を説明する簡単なガイド
  • ユーザーが各ファイルを開けるようにするファイルパス（クリック可能なリンク。次のセクションを参照）
  • 並列実行の場合：セットアップ手順（worktree または別々のターミナル）と、完了後のマージ手順
重要：プロンプトファイルは必ずクリック可能なリンクとして表示する

チャットでプロンプトを一覧表示する際は、必ずそれぞれを絶対パスを指す Markdown リンクとして記述してください。Claude Desktop ではクリック可能なリンクとして表示されるため、ユーザーは会話を離れずにチャットから直接ファイルを開いて確認できます。コード形式のファイル名だけではクリックできず、ユーザーが手動で移動する必要があります。

チャット出力でプロンプトに言及する際は、すべて次の形式を使用してください。

[prompt-1-foundation.md](/absolute/path/to/project/prompt-1-foundation.md)

次の形式は使用しないでください。

`prompt-1-foundation.md`

引き継ぎファイルができたら、実行中にユーザーが開けるよう、一度リンクしてください。

[orchestrate-handoff.md](/absolute/path/to/project/orchestrate-handoff.md)

絶対パスが分からない場合は、Bash の pwd でプロジェクトのルートを確認してから、そのパスを使ってリンクを作成してください。推測はせず、リンク先が確実に開けるよう、必ず実際の絶対パスを使用してください。

逐次実行の場合のチャット出力例（クリック可能なリンクを使用）：

プロジェクトのルートにプロンプトファイルを3つ作成しました。

1. [prompt-1-foundation.md](/Users/me/Documents/myproject/prompt-1-foundation.md) — データベーススキーマ＋コア CRUD API（git root：`api/`）
2. [prompt-2-gameplay.md](/Users/me/Documents/myproject/prompt-2-gameplay.md) — トーナメント表のロジック＋マッチメイキング（git root：`api/`）
3. [prompt-3-frontend.md](/Users/me/Documents/myproject/prompt-3-frontend.md) — トーナメントページ＋リアルタイム更新（git root：`app/`）

各リンクをクリックして、実行前にプロンプトを確認してください。

## 実行

**オプション A — こちらでオーケストレーション（推奨）：**「go」と入力すると、`claude -p` を使って引き継ぎ内容を各ステップ間で読み込みながら、途中で停止せずに全体を実行し、進捗を随時報告します。プロンプトが失敗するか、ブロックされた場合にのみ停止します。

**オプション B — 手動でコピー＆ペースト：** 各ファイルを開き、内容をコピーして、新しい Claude Code チャットに順番に貼り付けます。次のプロンプトを貼り付ける前に、`=== DONE: PROMPT N OF M ===` が表示されるまで待ってください。各ステップの間に、[orchestrate-handoff.md](/Users/me/Documents/myproject/orchestrate-handoff.md) を自分で確認してください。

並列実行の場合のチャット出力例：

プロジェクトのルートにプロンプトファイルを3つ作成しました。

1. [prompt-1-backend.md](/Users/me/Documents/myproject/prompt-1-backend.md) — リーダーボード API（git root：`backend/`）
2. [prompt-2-frontend.md](/Users/me/Documents/myproject/prompt-2-frontend.md) — リーダーボード UI（git root：`frontend/`）
3. [prompt-integration.md](/Users/me/Documents/myproject/prompt-integration.md) — 統合＋E2E 検証（1 と 2 の後に実行）

リンクをクリックして確認してください。

## 実行

**オプション A — こちらでオーケストレーション（推奨）：**「go」と入力すると、プロンプト 1 とプロンプト 2 を並列で実行し（それぞれの git root 内に専用の worktree を作成）、両方の完了を待ってから、統合プロンプトを実行します。

**オプション B — 手動：** ターミナルを2つ開いて、それぞれで `claude` を実行します。各セッションにプロンプトを1つずつ貼り付けます。両方が完了したら、3つ目のセッションを開いて統合プロンプトを貼り付けます。
プロンプト内の Markdown 形式

生成されるプロンプト自体が Markdown 形式です。# の見出し、- の箇条書き、コード用のバッククォート、チェックリストの - [ ] などを使用します。これは意図的なもので、Claude Code は Markdown をネイティブに読み取れます。プロンプトの内容には、見出し、リスト、コードブロック、太字など、標準的な Markdown を自由に使用してください。ディスク上の .md ファイルには、記述したソースがそのまま保存されます。

品質チェックリスト

出力する前に、各プロンプトが次のリストを満たしていることを確認してください。

  • プロンプトが完全に自己完結しています（「ファイル X を読んでください」のような指示はなく、内容が埋め込まれています）
  • Project Context セクションが、規約を埋め込んだ状態で含まれています（プロンプト 2 以降も同様です）
  • ファイルの境界が明確で、チームメンバー間で重複していません
  • MCP ツールが必要な場合は、MCP の事前確認が含まれています
  • 認証情報の取得元が明記されています：プロンプトで外部サービス（AWS、Supabase、Stripe、OpenAI など）を使用する場合、Pre-Flight Check Section 2a に認証情報の正確な取得元（パス、MCP サーバーなど）と、埋め込み形式で正確な読み込みコマンドが記載されています。「AWS CLI を設定してください」のような曖昧な指示はありません。
  • 完了基準が具体的で検証可能です（「正しく動作する」のように曖昧ではありません）
  • チーム構成がタスクの複雑さに合っています（3～5 名）
  • テスト手順に実行する正確なコマンドが記載されています
  • 以前のプロンプトで確定した内容以外に、事前のコンテキストがないことを前提としています
  • 実装の詳細度がユーザーの選択に合っています
  • Rules of engagement セクションが含まれています
  • プロンプト本文をチャットに貼り付けてはいけません。 必ずプロジェクトルートの .md ファイルに記述します。チャットメッセージには、短い概要とクリック可能な Markdown リンクのみを記載します。これは単一プロンプトと複数プロンプトの両方に適用されます。チャットにプロンプト本文を含むコードフェンスを記載してはいけません。
  • チャット出力で言及するプロンプトのファイル名はすべて、通常のコード表記 `filename` ではなく、クリック可能な Markdown リンク [filename](/absolute/path) 形式にします。これは初回のファイル一覧、オーケストレーションの進捗更新、ハンドオフファイルへの言及すべてに適用されます。Claude Desktop では、チャットを離れずにファイルを確認・開けるよう、これらのリンクがクリック可能に表示されます。

複数プロンプト（順次実行）の追加チェック：

  • 各プロンプトに Sequence Header（Prompt N of M）が含まれています
  • 各プロンプトに Project Context セクション全体が再度埋め込まれています
  • プロンプト 2 以降では、Pre-Flight Check で前のプロンプトの出力を検証します
  • 各プロンプトの末尾に Handoff Note があり、次のプロンプトが必要とするものを説明しています
  • 各プロンプトの実行後、コードベースが正常な状態になっています（テストが成功し、インポートの破損がありません）
  • 冒頭の実行ガイドに、すべてのプロンプトが概要付きで記載されています

複数プロンプト（並列実行）の追加チェック：

  • 各プロンプトに Parallel Task ヘッダーと明確なファイル境界が含まれています
  • 各プロンプトに、他のプロンプトが所有するため変更してはいけないファイルが列挙されています
  • いずれの 2 つのプロンプト間にも、ファイルの重複がありません（慎重に確認してください）
  • 実行時の依存関係がプロンプト間にありません（あるプロンプトが別のプロンプトの出力を読み込みません）
  • 各プロンプトに Project Context セクション全体が再度埋め込まれています
  • 実行ガイドに、worktree の設定または分離されたタスクの手順が含まれています
  • 実行ガイドに、完了後のマージ／検証手順が含まれています
  • 並列作業をつなぎ合わせる必要がある場合は、統合プロンプトが含まれています
  • 各プロンプトの Done Criteria は、そのプロンプトの担当範囲のみを対象としています（プロジェクト全体ではありません）

複数プロンプト — ハンドオフとセンチネルのチェック（オーケストレーターの選択にかかわらず常に適用）：

  • 各プロンプトに Section 0.5「Read Handoff File First」があり、他の作業に着手する前に cat orchestrate-handoff.md を実行し、ブロッカーや自身のプロンプト番号宛てのメモを確認し、未解決のブロッカーによって作業を進められない場合は BLOCKED センチネルを出して停止するよう指示しています
  • 各プロンプトに Section 8「Completion Handoff + Sentinel」があり、センチネルを出す前に、ステータスブロック（Summary / Files changed / Decisions made / 任意の BLOCKER / Notes for Prompt N+1）を orchestrate-handoff.md に追記するよう指示しています
  • センチネル形式：成功時は === DONE: PROMPT N OF M ===、回復不能な失敗時は === FAILED: PROMPT N OF M — <reason> ===、ユーザーの対応が必要な場合は === BLOCKED: PROMPT N OF M — <reason> ===
  • 各プロンプトの Section 0 に ### Git root for this prompt: <absolute or repo-relative path> が含まれており、オーケストレーターがどこに移動するか、またはどこに worktree を作成するかを把握できます 複数のプロンプト＋Claude が追加チェックをオーケストレーションする場合（ユーザーがステップ 6.5 でオプション A を選択した場合）：
  • orchestrate.sh スクリプトは生成されません。オーケストレーションは、親チャット内の Claude が claude -p を Bash で呼び出して、その場で行います。エンドツーエンドの自動化はしないでください。
  • オーケストレーター（このチャット内の Claude）は、最初のプロンプトを実行する前に orchestrate-handoff.md を初期化します。
  • 各 claude -p 呼び出しでは、--permission-mode bypassPermissions --output-format stream-json --verbose（またはステップ 6.5 でユーザーが確認したフラグ）を使用します。
  • 各呼び出しの stdout は logs/prompt-N.transcript.jsonl に、stderr は logs/prompt-N.log にリダイレクトします。
  • 長いプロンプトでは、Bash ツールで run_in_background: true を使用します。Claude は、センチネルが現れるまでトランスクリプトファイルをポーリングします。
  • プロンプトの合間に、Claude は orchestrate-handoff.md を読み込み、最新のステータスブロックを要約してユーザーに伝え、続行する前に確認します。
  • BLOCKED の場合：Claude は ### BLOCKER: のテキストをそのまま表示し、ユーザーが ### RESOLVED: を追加するまで待ってから再開します。
  • FAILED の場合：Claude は失敗理由とログ末尾を表示し、どのように進めるかをユーザーに尋ねます。
  • 並列ワークツリーモードの場合：各ワークツリーは、親モノレポ（多くの場合 Git リポジトリではありません）ではなく、プロンプトで宣言された Git ルート内（例：api/.orchestrate-wt/prompt-2/）に作成します。
  • 並列ワークツリーモードの場合：同じ Git ルートを共有する 2 つのプロンプトは拒否し、構成を変更するか、並列分離モードを使うようユーザーに伝えます。
  • 並列ワークツリーモードの場合：wait の後に、ワークツリーごとのハンドオフファイルをプロジェクトルートのハンドオフファイルに統合します。
  • プロンプトの .md ファイルは、実行後に必ず削除します — オーケストレーションモード（オーケストレーションまたはコピー＆ペースト）にかかわらず、毎回削除します。チェーンの完了時（すべてのプロンプトが DONE）に、プロジェクトルートにあるすべての prompt-*.md を削除し、残存する孤立ファイルを一掃します。orchestrate-handoff.md と logs/ は保持します。唯一の例外は、FAILED または BLOCKED となり、再実行を待っているプロンプトです — DONE になった時点で削除します。
  • チャットの出力では、「Claude がオーケストレーションする」方法と手動でコピー＆ペーストする方法の両方を説明します

コメント

Markdown 対応