grill-to-plan

Grill to Plan

曖昧な目標、粗いアイデア、計画、設計を、共通認識、明確な決定事項、実行可能な最終計画へとまとめます。

モード

• ライトウェイトモード：価値の高い質問だけを行い、会話調のトーンを保ちます。ユーザーから依頼がある場合、または長期的に残すべきプロジェクト上の決定事項が生じた場合を除き、リポジトリのドキュメントは確認しません。
• ドキュメント化モード：完全なワークフロー（コードとドキュメントの確認、用語集の更新、必要に応じた ADR、セッション記録、最終的な統合）を実施します。

ワークフロー

1. 目標を言い換えます。

   • ユーザーが現在意図していることを、具体的で明確な表現に言い換えます。
   • ユーザーが計画と見なすのに十分な決定事項を示すまでは、入力を目標の説明として扱います。
   • 望ましい最終状態、対象範囲、対象外となる可能性のあるものについて、認識を伝えます。
   • 合理的な推測をするには最初のコンテキストが不足している場合は、まず不足している情報を尋ねます。
   • 重要度に応じてモードを選択します。デフォルトはライトウェイトモードとし、プロジェクトの知識、アーキテクチャ、または長期的に残す決定事項が関わる場合はドキュメント化モードに切り替えます。最初の入力だけではモードが明確でない場合は、続行する前に、ライトウェイトな確認を希望するか、決定事項をドキュメント化するかをユーザーに尋ねます。

2. 詳細を掘り下げる前に、スコープを定めます。

   • 最初の入力から、スコープが定まっているかを判断します。つまり、決める必要のある事項をすでに列挙できるか確認します。
   • そうでない場合、境界が曖昧だったり、複数の方向性が残っていたりするなら、まず対象を絞るための質問をします。
   • スコープを絞る質問は、収束する順序で行います。まず影響の大きい境界に関する質問をし、その後、段階的に範囲を狭めます。
   • スコープが明確になったら、依存する決定事項を分岐ごとに解決できるよう、意思決定ツリーの順序に切り替えます。

3. 質問する前に、利用可能なコンテキストを活用します。

   • 調査によって答えられる質問は、自分で答えます。まずコードベース、ドキュメント、イシュートラッカー、セッションログを確認し、判明した内容を報告します。調査で解決できないことだけを質問します。
   • 読み取りだけでは判断できない実行時の観察が、決定を左右する質問に必要な場合（たとえば、どちらの描画方式でも合意済みのレイテンシ上限を満たせるかどうか）は、既存の権限内で最小限かつ独立した検証またはプロトタイプを実施します。追加の権限が必要なら、提案して許可を待ちます。結果と重要な根拠はステップ 8 に記録するか、セッション記録を残さない場合は統合内容に含めます。観察結果で事実に関する質問を解決し、残る製品上の選択や好みに関する判断はユーザーに委ねます。証拠を得られない場合は、質問を未解決のままにし、不足しているものを明示します。
   • 必要な事実を得るのに長時間の調査が必要な場合は、セッションを停滞させないようにします。ハーネスが許す場合はバックグラウンドで調査を開始し、それに依存しない質問を進め、結果が得られた時点で内容に反映します。
   • ドメイン用語やアーキテクチャが話題に関わる場合は、CONTEXT-MAP.md、CONTEXT.md、docs/adr/ を確認します。

4. デフォルトでは、一度に1つの質問をします。

   • 各質問の冒頭で、目標と、すでに決定している関連事項を言い直します。
   • 自明でない質問だけをし、まずアーキテクチャに影響する質問を、細部の調整に関する質問は最後にします。
   • 具体的なエッジケースのシナリオを使って、ドメイン内の関係性を掘り下げ、境界を明確にします。
   • 実質的な選択肢がある場合は、トレードオフを添えて、あなたが提案する候補を2～4個示します。推奨案には、その理由を添えて明示します。4個を超える選択肢がある場合は、判断を分割するか、候補から外したものを示します。
   • 候補とあわせて、常に議論に入る方法を示します。構造化された選択肢の最後に「議論する／もう一度説明してもらう」を含めるか、通常のテキストでいつでも相談できる旨を案内します。ユーザーがそれを選んだら、議論に入る前に、質問を平易な言葉で言い直し、その前提を示し、セッションで統一されている用語を使って説明し直します。
   • 回答の形式に応じて質問の提示方法を選びます。短い選択であれば、利用可能かつ許可されている場合、質問ツール（ユーザーに選択肢付きの質問を提示する構造化ツール）を使います。説明、シナリオ、自由記述が必要な質問は、同じ候補に番号を付けて通常のチャットメッセージで提示します。選択肢の内容はツールを使うかどうかで変えてはいけません。
   • 推奨案は選択肢の中に含めます。ツール呼び出しを使う場合、そのターンの最後に実行します。そこで終了して回答を待ち、締めくくりのメッセージや推奨案の言い直しは付けません。
   • 明示的に選択された場合だけ、受け入れたものとみなします。タイムアウト、質問のスキップや期限切れ、事前選択された選択肢では判断は未決のままです。その場合は、チャットで質問を繰り返します。
   • 関連する軽微な質問は、真に独立している場合に限り、1回の質問ツール呼び出しにまとめることを優先します。つまり、ある質問への回答が別の質問に影響せず、いずれも細部の調整であり、アーキテクチャに関わらない場合です。相互に関連する質問やアーキテクチャに関わる質問は、1つずつ扱います。まとめた質問への回答をきっかけに議論が始まった場合は、その質問を個別に取り上げます。
   • 分岐ごとに判断が確定したら、残っている分岐を簡潔に伝えます。ユーザーの回答が簡潔になったとき、「もう決めてください」と繰り返し言われたとき、またはシグナルにかかわらず判断が10件確定するごとにチェックポイントとして、残りの判断をまとめて終えることを提案します。その際は、残りの判断に対する推奨案を提示し、ユーザーが承認、修正、または保留できるようにします。「もう決めてください」は、それが回答する質問だけを確定し、残りの質問には適用しません。

5. 次に進む前に、各質問の判断を確定します。

   • ユーザーが議論を希望した場合、結論、明示的な保留、または記録された意見の相違に至るまで、その質問について話し合います。
   • ユーザーの返答が決定ではなく、質問、異議、または説明の依頼である場合は、議論に切り替えます。通常のメッセージで詳しく回答し、そのターンをそこで終えます。その返答では質問ツールを使わず、ユーザーが会話で自由に返答できるようにします。
   • 議論が収束するか、ユーザーが決定する準備ができたと示すまで、質問ツールには戻りません。ツールは判断を集めるためのものであり、説明を提供するためのものではありません。
   • 次の質問をする前に、現在の会話と最新のセッション記録を確認し、これまでの決定内容に沿った質問にします。

6. 不適切または有害な選択には、異議を唱えます。

   • ユーザーが提案した判断が誤り、リスクを伴う、矛盾している、または利用可能な別の案より劣ると思われる場合は、黙って従いません。
   • 現在の方針または別の案のほうがよい理由と、提案された選択による具体的な不利益を説明し、議論するか、それでも進めるかを確認します。
   • ユーザーが確認するか、説得力のある反論を示すまで先には進みません。
   • 最終決定を記録します。ADR のルールに該当する場合は、ADR を作成します。

7. ドキュメントモードでは、プロジェクトの知識を維持します。

   • CONTEXT.md と矛盾する用語には異議を唱えます。
   • 曖昧な用語や意味が広すぎる用語を、正確で一貫した用語に整えます。
   • 可能な場合は、コードと照らし合わせてユーザーの主張を確認し、矛盾があれば明らかにします。
   • ドメイン用語が確定したら、CONTEXT.md をその場で更新します。実装の詳細は含めず、用語集としてのみ維持します。
   • 具体的に記述できる内容がある場合に限り、CONTEXT.md または docs/adr/ を作成します。
   • CONTEXT.md を作成または更新する際は、references/CONTEXT-FORMAT.md を使用します。
   • ライトウェイトモードでは、ユーザーから求められた場合、または長期的に維持すべきプロジェクト上の決定が生じた場合に限り、これを行います。

8. 必要に応じてセッション記録を維持します。

   • 決定事項が固まったら、セッションドキュメントを作成または更新します。リポジトリに既定の計画書や決定ログの保存場所がない場合は、plans/{yyyy-mm-dd}-{slug}/session.md に保存します。
   • 各質問について、背景、質問内容、推奨案、議論または検討の概要、最終結論、フォローアップを記録します。
   • また、決定の根拠となる重要な事実（検証済みの調査結果、外部 API の制約、契約の詳細、却下した代替案）も記録します。決定事項だけを記録してはいけません。実装担当者にはこの会話の内容が伝わらないためです。
   • 進行中の会話を直近の信頼できる情報源として扱い、セッション記録は確定した内容を残すための長期的な記録として扱います。
   • 会話の記録にならないようにしつつ、次の質問の指針となる程度に簡潔に保ちます。
   • このドキュメントを作成または更新する際は、references/SESSION-RECORD-FORMAT.md を使用します。
   • ユーザーから求められた場合、または保存する価値のある決定が議論から生じた場合を除き、ライトウェイトモードではセッション記録を省略します。

9. モードに応じた分量で、最後に総括します。

   • 総括する前に、暗黙の前提がないか確認します。頼りにしたのに質問しなかった事項はすべて、記録上で明示的な決定、未解決の質問、または明記した前提にします。暗黙の前提が残っている間は、計画を確定事項として提示しません。
   • 完了の定義も、ほかの決定事項と同じようにユーザーと合意します。反証可能なチェック項目として受け入れ基準を提案し、ユーザーに確認または修正してもらいます。確定した基準は総括に記載し、plan.md を作成する場合はそこにも記録します。それ以外の場合、この会話から実装担当者が確認可能な「完了」の条件を引き継ぐことはありません。
   • 実装は必ず別のセッションで行われ、別のエージェントが担当する場合もあるものとします。永続的なドキュメント（plan.md、session.md、ADR）は、単独で完結した引き継ぎ資料でなければなりません。実装に必要なすべての決定事項、制約、調査結果、命名の選択、統合契約を、これらのドキュメントまたはリンク先のドキュメントに記載します。会話の文脈は引き継がれません。
   • 軽量モードでは、確定した決定事項、明示的に保留した事項、次のステップを示します。
   • ドキュメント作成モードでは、確定した計画、決定事項、未解決の質問、更新したドキュメント、リスク、次のステップを含む総括を提示します。
   • 計画は、変更される可能性が高い順に並べます。ユーザーが変更する可能性の高い決定事項（データモデル、型インターフェース、ユーザー向けの動作）を先頭にし、機械的な作業や十分に理解されている作業を後ろに置きます。
   • 複数の実装単位がある計画では、各単位の成果物、前提条件、完了を確認するチェック項目を示します。提示順はレビューのためのものであり、前提条件によってビルド順を決めます。
   • 構造（コンポーネント間の連携、データフロー、判断の分岐、ビルド順）を文章より視覚的に把握しやすい場合は、総括と plan.md または session.md に図を使います。チャットではプレーンテキスト、記録では mermaid で図を描きます。ただし、文章で説明できる内容を図にしてはいけません。
   • 総括に合わせて、ユーザーと計画の理解が一致しているかを確認するため、短い選択式のアラインメントクイズを提示します。まだユーザーが検討していない動作や、計画の主要な経路を確認します。ユーザーが了承したら、references/ALIGNMENT-QUIZ.md を読み、その指示に従います。変更された決定事項は総括と記録に反映します。
   • セッション記録が存在する場合は、references/SESSION-RECORD-FORMAT.md に従い、最終的な計画も session.md と同じ場所に plan.md として必ず保存します。セッションを再開して計画が変更された場合は、上書きします。
   • plan.md には今後実装する内容と、各部分に必要な前提条件を記載します。決定に至った経緯を重複して記載するのではなく、session.md にリンクします。

ADR に関するルール

以下の3つすべてに該当する場合に限り、ADR の作成を提案するか、作成します。

• 変更が難しい：後から決定を変更すると、相応のコストがかかる。
• 背景がないと意外に感じられる：後から読む人が、なぜこの選択をしたのかと疑問に思うのが妥当である。
• 実質的なトレードオフがある：現実的な選択肢が複数あり、特定の理由からそのうち一つを選んだ。

ADR を作成する場合は、references/ADR-FORMAT.md に従います。