plan-brief

計画概要：要件 → 詳細な計画 → ランチャープロンプト → レビュー（审查闭环）

1つの作業で3つの成果物を作成します：（1）詳細な実行計画書、（2）実行用の新しいセッションを開始する、コピー＆ペースト可能なランチャープロンプト、（3）後日、そのセッションのレポートをレビューした結果。 計画の作成とレビューを行います。計画の実行や実行用サブエージェントの起動は決して行いません。

成果物チェックリスト — どれも黙って省略してはいけません。

• 計画書 docs/plans/YYYY-MM-DD-<slug>.md（プロジェクト独自の作業ドキュメント用ディレクトリが異なる場合は、そちらに保存）
• ランチャープロンプト：計画書内にコードフェンスで記載し、チャットにも出力
• レポートが返ってきたら、計画書と同じ場所に <slug>.review.md を作成し、修正が必要な場合は修正用プロンプトも作成

このスキルを適用する場合

• ユーザーが、永続的な実行計画の作成、実行を別のセッションに引き継ぐこと、またはレポートのレビューや修正ラウンドの実施を求めている場合 — 上記の3つの成果物を作成します。
• ユーザーが明示した選択を優先し、ワークフローを黙って切り替えてはいけません。セッション内での実装には quick-do / steady-do を使用します。引き継ぎが有用でも依頼されていない場合は、実行担当を変更する前に提案してください。

フェーズ 0 — 要件を把握する

• 生の要件をすべて読みます（チャットのテキスト、またはユーザーが指定したファイル）。
• 目標、範囲、客観的に確認できる完了条件、「完了」の状態を2〜3文で言い換えます。
• 明示された要件と未確定の詳細に分けます。まだ計画を立ててはいけません。

フェーズ 1 — プロジェクトを調査する

• プロジェクトのルール（AGENTS.md）、README、プロジェクトのメモリとドキュメント、エントリーポイント、要件に関わるすべての内容を読みます。
• 現状、実際の呼び出し経路、既存の機能と再利用できる箇所、互換性の境界、プロジェクト固有の規約（環境マネージャー、ドキュメントの保存場所、実行コマンド、正式な実行を開始する担当者）を確認します。
• コード、設定、メモリ、ドキュメント、上流のソースやイシューから、自分で事実を調査します。コマンド、API の詳細、プラットフォームの制限をでっち上げてはいけません。確認できる事実をユーザーに尋ねず、判断が必要な事項についてのみユーザーに確認します。

フェーズ 2 — 未決事項をすべて洗い出す

要件には詳細が十分に含まれていないことがほとんどです。個別のスキルは不要です。次の範囲を絞ったラウンド方式をそのまま使ってください。

• スコープ、動作、互換性、リスク、実行順序、または受け入れ条件を変える未決事項だけを質問し、簡潔なトレードオフとともに推奨案を示します。
• 個別に回答できる質問は1つのラウンドにまとめ、前提条件が整うまで依存する質問は保留します。各ラウンドの後、何が新たに判断可能になったかを再検討して次の質問をします。以降の判断に影響する質問がなくなるまでラウンドを続けます。終了条件は「ラウンドを1回終えた」ではなく、「重要な未決事項が残っていない」です。
• 決着した質問を繰り返したり、ノルマを設けたり、すべての要件が不完全だと決めつけたりしないでください。

調査またはユーザーの明示的な判断を通じて、次の事項を必ず確定します。

• 実行環境 — インタープリターと環境を正確に指定します（venv／conda のパスと有効化コマンド）。環境変数名、作業ディレクトリ、パッケージマネージャー、バージョンも指定します。システム Python を決して前提にしないでください。認証情報を計画にコピーせず、既存のシークレットの保管場所を示してください。
• 入力／出力 — 形式、パス、想定される成果物、互換性の制約を指定します。
• 実行順序 — 依存関係、マイルストーン、実際に独立している作業または並行可能な作業を示します。
• ドキュメントの場所 — プロジェクトの作業用ドキュメントディレクトリを指定します。既定値は docs/plans/YYYY-MM-DD-<slug>.md です。レポートとレビューは、同じベース名で計画書の隣に置きます。
• 検証モード — 必須の決定事項です。計画書に1行で明記し、その理由を説明してください。
  • TDD モード — フィードバックループが速く、テストのコストが低い場合に限ります（フロントエンド／UI、プロダクトサービス、すぐに単体テストを実行できるライブラリコード）。tdd スキルを実行します。
  • スモークテストと読み直しモード（調査、長時間実行、または高負荷の計算処理では既定）：最小限の実行可能な処理経路を実行し、自分のコードを読み直し、影響する隣接動作を確認します。pytest、テスト用の足場、ラッパーハーネスは使いません。実行そのものにコストがかかるためです。その後、ユーザーが実際のワークロードを実行します。
  • 目安：テストの作成と実行にかかるコストが、検出できる不具合によるコストを上回るなら、テストを書かないでください。
• 受け入れ条件と責任 — 何を観測するか、期待される結果、コストと環境の制約、最終的に誰が実行・検証するかを明確にします。

合意したスコープ、アプローチ、検証方法を簡潔にまとめてから、別途承認を求めずに計画書を作成します。要約で新たな重要な判断が生じた場合に限り、そこで確認を待ちます。

フェーズ 3 — 仕上がりの方針を定める

ポニーテールをそのまま適用します（ここにルールを記載するだけで十分です）。

• 最小限の動作する変更を計画します。既存コードを再利用し、次に標準ライブラリやネイティブ機能を使い、その後にインストール済みの依存関係を使います。過度なカプセル化、推測に基づく抽象化、防御的な定型コード、冗長な再検証、将来のためだけの足場、無関係な整理は行いません。
• 実際の呼び出し経路に沿って根本原因を修正し、共有ロジックを呼び出す他の箇所にも配慮します。信頼境界での検証、セキュリティ、アクセシビリティ、データ保護、データ損失を防ぐエラー処理は維持します。
• 破壊的または取り消せない操作には認可ゲートを設けます。計画の実行許可は、シークレットの上書きや無関係な環境の変更を許可するものではありません。正しく動作する機能コードができたら完了です。

フェーズ 4 — 計画ドキュメントを作成する

ユーザーの言語で、構成を整えた Markdown ドキュメントを 1 つ作成します（見出しはデフォルトで中国語：目标与范围 / 现状 / 环境与前提 / 执行步骤 / 注意事项与已知坑 / 验证方式 / 交付物清单）。比較やパラメーターには表を、手順にはリストを使い、見出しの直後に長文を続けないでください。セクション：

1. 目標と範囲 — フェーズ 0 で言い換えた内容（対象外の項目を含む）。
2. 現状 — 現在あるものと再利用する部分、フェーズ 1 の調査結果。
3. 環境と前提条件 — 正確に把握しているコマンド、パス、バージョン。未解決の外部要因はその旨を明記します。
4. 実行手順 — 順序を示し、各手順で対象 / ファイルまたはコマンド / 期待される結果 / 依存関係を明記します。検証していないコマンドや API の詳細を作り出さないでください。
5. 制約と既知の問題 — 互換性、リスク、フェーズ 3 で確認した承認ゲート。
6. 検証 — 選択した方法（TDD / スモークテストと読み取り）とその理由を明記します。具体的な受け入れ証拠と、誰が何を実行するかも記載します。静的チェック、正常な読み込み、ローカル呼び出し、実際のユーザー操作を区別し、エラーがないことだけを成果の証明として扱わないでください。
7. 成果物 — 計画と同じ場所に <plan-basename>.report.md を含めます。必須の製品ドキュメントとプロジェクトのメモリも引き続き必要です。

フェーズ 5 — 起動プロンプトを作成する

計画ドキュメントにフェンス付きコードブロックで追記し、コピーできるようチャットにも出力します。新しいセッションですぐに使える、完全に自己完結した内容にしてください。

• 計画ドキュメントのパスを示し、作業を始める前に計画ドキュメント、AGENTS.md、関連するプロジェクトドキュメントを読むよう実行者に指示します。
• 合意済みの範囲、環境、手順の順序と依存関係、ポニーテールの好み、検証方法、承認ゲート、成果物を引き継ぎます。計画に従い、ワークフローの選択をやり直したり、決定済みの事項を再確認したりしないでください。
• 厳守事項：何かを実行する前に指定された環境を有効にすること。計画の手順順序に従うこと。範囲を拡大しないこと。計画が曖昧な場合、新たな証拠で計画の妥当性が失われた場合、または範囲の変更が必要な場合は作業を止めて確認すること。通常のローカルな実装上の詳細については、繰り返し承認を求めずに解決してください。
• 開発レポートは必須です（作業が一部にとどまる場合も同様）： 計画と同じ場所に、ユーザーの言語で <plan-basename>.report.md を作成します。内容には 完成情况总表（計画の各手順について：完成 / 部分 / 搁置 / 未动 ＋ 証拠）、做了什么、没做什么与搁置原因、规范遵循情况、特殊处理与偏离、遗留问题与建议 を含めます。
• 部分的な完了も正当です： 依存関係の不足、環境の制限、範囲外など、実際の制約で妨げられた手順は保留にできます。完了したと偽ったり、黙って省略したりしてはいけません。レポートには、実施したことと実施していないことを正確に記載します。
• 証拠を正確に扱います。静的チェック、正常な読み込み、入力の注入、実際のエンドツーエンドの挙動を区別します。ユーザーの環境に依存する項目がある場合は、残っている確認内容と期待される結果を具体的に示します。
• 成果物を明記します。

レビューループ（審査の完了サイクル）— ユーザーがレポートを持ち帰ったとき

ユーザーが実行担当の作業が完了したと伝えてきたとき（またはレポートのパスを提示したとき）は、プロジェクトを最初から調査し直すのではなく、監査してください。

1. 計画書とレポートを並べて読みます。主張の根拠が必要な箇所に限り、コードを抜き取り確認します。
2. 照合表を作成します。計画の各ステップについて、レポートの主張／根拠／判定（適合／要確認／不適合）を記載します。
3. 規範の遵守状況を監査します。環境の有効化、ステップの順序、対象範囲、ポニーテールの趣味、選択した検証モード、認可ゲート、テストスクリプトの抑制を確認します。逸脱をすべて誤りと決めつけず、それぞれの理由を踏まえて判断します。
4. 判定（適合／一部適合／不適合）を示し、ポニーテールのスタイルで、具体的かつ優先順位を付けた最小限の修正を提示します。
5. 計画書と同じ場所に、ユーザーの言語で <slug>.review.md を作成し、その内容をチャットに表示します。実行担当者のレポートは絶対に編集しないでください。レポートは実行担当者の成果物です。
6. 修正が必要な場合は、新しい自己完結型のランチャープロンプトを作成します（フェーズ 5 のルールに従ってください）。修正項目のみを正確に再指示し、レビュー ファイル、計画書、前回のレポートを参照させます。
7. 修正ラウンドごとに専用の成果物を残します。 修正セッションでは <slug>.report-2.md（以降は -3 など）を作成し、以前のレポートを上書きしてはいけません。各ラウンドでは専用の <slug>.review-2.md（以降も同様）を作成し、すべてのラウンドを監査できるようにします。
8. 終了： 適合の判定が出たらループを終了します。計画書の冒頭に Status: done (rounds: N) と記録し、未完了の項目があれば列挙して、プロジェクトのルールに従ってプロジェクトのメモリ／ドキュメントを更新します。同じブロッカー項目についてラウンドを重ねても進展がない場合は、ループを続けず、未解決の質問をユーザーに引き継ぎます。

連絡事項：復帰はユーザーを介して行われます。このセッションは実行担当者によって自動的に再開されず、ユーザーがレポートを持ち帰ったときにのみ再開します。引き継ぎ時にこの点を伝え、自動通知を待つ人が出ないようにしてください。

厳守すべき境界

計画書とランチャープロンプトを渡した時点で、計画作成の作業はいったん完了です。この場で計画を実行したり、実行用サブエージェントを立ち上げたり、自分で修正ラウンドを開始したりしないでください。ユーザーが新しいセッションを開始します。このセッションの次の役割はレビュー担当者です（「レビューループ」を参照）。