plan

計画

不明確な意図を、実行可能な一つの変更範囲にまとめたら、そこで止めます。変更が明確ならそのまま進め、専門家を呼ぶのは、その専門家が答える問いがある場合に限ります。依頼者がトラッカーを使っている場合はそれを、そうでなければ会話または提供されたテキストを優先します。Idea Genie のポートフォリオや課題など、提供された助言は考慮すべき根拠であり、決定ではありません。

計画が満たすルール

1. ロードマップではなく、一つの変更範囲。 対象となるすべてのレイヤーを通じて、エンドツーエンドで観測可能な結果を生む、最小の変更にまとめます。フェーズ分けも、レイヤーごとの内訳も、バックログも作りません。後続の作業は、新しい根拠によって次の変更範囲になった場合を除き、それぞれ大まかな一行にとどめます。最初に着手できる変更範囲が複数ある場合は、アプローチにおける最もリスクの高い依存関係を検証できる、最小の観測可能な経路を優先します。それぞれ単独で有用かつ検証可能な成果は、別々の計画であり、変更範囲ではありません。依頼、トラッカー、または Navigate によって着手順がすでに決まっていない限り、ルール 3 に従って質問し、残りは Later に記載します。プロバイダー、デバイス、データソースが指定されている場合は、一つの成果を網羅する対象として扱います。指定された要件を満たす共通の経路がない場合に限り、それらを分けます。ある要素を単独で指定すると、別の要素と共有する動作を推測しなければならない場合は、要素を一緒に扱います。代替手段を使う場合は、その名称と、何を確認できないのかを記載します。その代替手段によるデモは、実際の統合を証明するものではありません。
2. 設計の前に例を示す。 観測可能な結果を伴う Given／When／Then を少なくとも一つ記載します。単に正常系を示すのではなく、繰り返し発生する副作用や外部への副作用、データの損失、アクセス範囲の拡大など、誤りを元に戻すコストが高い境界を対象にします。
3. 事実は調べ、選択についてだけ質問する。 質問する代わりに、コード、ドキュメント、トラッカーを読みます。質問できるのは依頼者に対して最大一つです。どの情報源にも答えがなく、選択が必要な場合に限り、推奨案とそのトレードオフを添えて質問します。複数の選択肢が質問枠を競う場合（どの成果を先にするか、ルール 7 との衝突、決定者に基づく記録済みの決定など）は、変更範囲に最も大きな影響を与える一つを質問し、それ以外は変更内容とともに Later に記載します。受け入れ条件を満たすうえで複数の点が障害になる場合は、Interview で一つずつ質問して解決します。
4. リポジトリで使われている用語。 コード、用語集、トラッカーで定義されている用語を再利用し、別の名前を新たに作ってはいけません。
5. 利用者ごとに範囲を定める。 編集対象の所有者、変更する動作を利用するすべての有効な呼び出し元とテスト、生成された関連ファイルの種類を、リポジトリ相対のパターンで明記します。範囲は権限の境界であり、予測されるファイル数ではありません。範囲外に有効な利用箇所があれば、正確なファイルを指定した変更として依頼者に提示し、それとは独立した範囲内の作業は続けます。
6. 違いを明確にできる検証。 現状では失敗し、この変更範囲の適用後には成功する検証を示します。
7. 依頼されていない仕組みを加えるなら、必要性を示す。 ガード、再試行、フォールバック、オプション、抽象化を加えるのは、契約上必須である場合、追加しないと追跡済みの障害を適切な時期に修正できる人が検知できない場合、または後から追加するコストが高い場合に限ります。該当するのは、永続化されるデータや形式、他者が依存するインターフェース、決済、セキュリティなどです。最小の形で実装し、追加項目ごとに同じ基準で判断します。判断に迷った場合は加えず、それを必要とする根拠とともに Later に記載します。変更範囲の失敗に気づいて対処できる人がいない場合、その失敗を可視化することも変更範囲に含めます。保護策によって依頼された動作の範囲を狭めてはいけません。実際に衝突する場合は Question とします。

出力

依頼または既存の承認によって編集が認められている場合（会話での依頼は常に該当します）は、このブロックを依頼者の既存の意図に追加します。それ以外の場合は、修正案として提示します。これが計画のすべてです。

Outcome:  <who observes what, in the repository's terms>
Example:  Given <state>, when <event>, then <observable result>
Slice:    <the one end-to-end change that makes the example true>
Scope:    <owners>; consumers: <live callers and tests>; generated: <class> | none
Check:    <the test or observation that fails now and passes after the slice>
Question: <one caller choice, your recommendation, its tradeoff> | none
Later:    <deferred item and the evidence that would make it next> | none

重大な影響を伴う別の境界を扱う場合に限り Example 行を追加します。名前が指定された人物しか知らない事実がある場合に限り、質問文案を添えて Open 行を追加します。妥当な範囲の誤解を防ぐ場合に限り、非目標を追加します。

ワークフロー

1. 承認済みの意図、既存の計画やネイティブな引き継ぎ、関連するソースの担当者、現在有効な制約を確認します。会話や bead ですでに提示されている承認を再利用し、行動や判断を妨げる点だけを明確にします。再開するときや作業の一部を引き継ぐときは、コードと振り返りまたはスナップショットの意図を組み合わせて、 再開と引き継ぎに従います。
2. 作業の一部に影響し得る不確実性だけを振り分けます（下表）。インターフェースの選択がその不確実性を左右する場合は、境界を確定する前に、条件に応じて 呼び出し元を起点とした設計比較を使います。
3. ブロックを埋めます。動作を維持した再構成によって作業の一部を大幅に小さくできる場合は、Refactorを通じて、前提条件として Slice 行に明記します。Check 行とは別に、変更前後の確認を行い、その作業の一部の差分には含めません。作業の一部ごとに動作する状態を維持できない、機械的で横断的な移行には、expand、migrate、contract の手法を使い、統合が必要な箇所を明記します。記録済みのエビデンス（スコアカード、フィクスチャなど）が、作業の一部で変更するファイルに紐付いている場合は、再取得の計画を立てます。プラグインには同梱されていない ao CLI では、ao provenance evidence-orphans --root <repo-root> --changed <path> を使うと、そうした紐付けを一覧表示できます。エピック全体では、次の bead を Navigate が選び、その bead の形を Plan が整えます。
4. エビデンスによってアプローチの誤りが判明した場合は、失敗した前提、そのエビデンス、改訂した確認内容を、以下の Output 書き込みと同じ権限のもと、既存の意図に記録します。承認済みの成果と範囲内でのアプローチ変更に、新たな許可は必要ありません。承認や範囲の拡大には、呼び出し元の承認が必要です。承認条件の不履行を注意事項と言い換えて、承認を得ようとしてはいけません。

実装者が行動でき、検証者が判断できるようになった時点で計画を止めます。追加の調査、分解、レビューは、名前を挙げた未解決の不確実性を解消する必要があります。実装、統合、修復のための余力を確保します。

不確実性の振り分け

不確実性	次のアクション
ソースで確認できる事実	最小限の権威あるソースを調べ、引用します。より深い追跡は Research、異論のある用語は Domain が担当します。呼び出し元に説明を求めてはいけません。
呼び出し元の選択	まず既存の承認内容を確認します。残るのが選択の問題であれば、具体的なトレードオフを示して、一つの質問に絞ります。エージェントが呼び出し元に代わって回答することはできません。
名前の挙がった別の人物だけが知る事実	人物の名前を挙げ、ギャップを埋めるために必要な少数の質問を、重要度の高い順に、一つの質問につき一つの論点となるよう作成します。回答に必要な文脈も添え、計画とともに返します。送るかどうか、またどのように送るかは呼び出し元が決めます。回答が得られるまで項目は未解決のままです。推測したり、呼び出し元の選択の問題と言い換えたりしてはいけません。
観察によってのみ確定できる前提	互いに異なる予測と、それらを区別できる最小限の観察を示し、必要に応じてプローブまたはプロトタイプを使います。説得力のある設計やエージェントの多数決では、未観測の動作を確定できません。
安全に先送りできる事項	関連性が生じるイベントやエビデンスとともに、Later の下に記載します。先送りによって、未回答の承認条件を隠してはいけません。

承認済みの範囲内で、元に戻せる実装上の詳細を解決します。推論やエビデンスの欠如には印を付け、ソースで確認された事実や、呼び出し元が確定した選択として扱ってはいけません。ソースの確認と観察を経ても残る、重大な不確実性については、必要に応じてチャレンジを利用できます。得られるのは助言または次の判別方法であり、許可や承認ではありません。 メモリの想起が役立つのは、過去のエビデンスによって次のアクションが変わり得る場合に限られます。

誰が決めるか

実際の取り消しコスト、影響を受けるユーザー、既存の権限に基づいて判断します。その権限の範囲外にある、重大で取り消せない選択は呼び出し元に委ねます。また、ADR、公開済みの契約、宣言済みの非目標など、記録された決定に反するスライスも同様です。その決定と、それを再検討する根拠をQuestionとして明示し、呼び出し元が回答するまでは、その範囲内にスライスを留めてください。事前の承認は引き続き有効です。レビュアーの合意は根拠にはなりますが、呼び出し元の意図を置き換える許可ではありません。重大な意見の相違と、その根拠を説明し、受け入れ条件を黙って変更しないでください。提案するプロセス成果物には、具体的な利用者、その成果物が判断を左右する対象、観察された不具合、廃止条件が必要です。そうでなければ省略してください。

例

例はプレーンテキストでも構いません。BDDに.featureファイルや聞き取りは必要ありません。キューに入れられた作業をJobと呼ぶリポジトリでは、「task item」ではなく「Job」と記述します。

Given Jobはすでに完了している、when ワーカーがそのJobを再び受け取る、 then 完了した結果が返され、副作用は繰り返されない。

コーディング後に追加したテストは、受け入れ済みの例を補足できますが、約束した内容を再定義することはできません。