coding-design-plan

コーディング設計計画

スコープが定められたタスクを、実装担当者が新たなプロダクトやアーキテクチャ上の判断をせずに構築できる最小限で一貫した形にします。次の利用者は implement-and-review または変更を行うエンジニアです。変更される振る舞い、担当者、境界、検証方法、未解決の阻害要因を明記したら計画は完了です。

PRD やタスクですでに確定した選択肢は、決定済みとして扱います。新たなヒアリングや選択肢の一覧によって再検討してはいけません。

ワークフロー

1. 承認済みのタスク、受け入れ条件、適用中のプロジェクト規約を確認します。形を提案する前に、関連コード、テスト、現在の振る舞いを調べます。

2. 設計上の問題を一文で述べます。変更する振る舞いと、その振る舞いの担当者を明示します。

3. 影響を受ける境界のみを整理します。対象は、ローカルコード、モジュール、コンポーネント、サービス、データストア、公開契約、デプロイ時の振る舞いです。変更の責任範囲に基づき、次の変更が適切な場所に属するよう各責務を配置します。

4. 既存コードに適合する、最小限で一貫した形を選びます。実際に選択肢がある場合は、決定的なトレードオフを1つ示します。コードとタスクからローカルな変更が明らかな場合は、選択肢を比較しません。

5. 次の条件に該当する場合に限り、対象を絞ったエンジニアリングチェックを適用します。

   1. タスクによって非ローカルな境界が変わり、適用する観点がタスク契約ですでに選択されていない場合は、現在の役割で design-gate を適用します。
   2. タスクで指定された観点の結論がすでにある場合は、その結論を適用します。同じ結論を言い直すために観点を再適用してはいけません。
   3. 実行可能なコードでしか答えられない不確実性が1つある場合は、to-prototype を使用します。プロトタイプコードを本番コードに昇格させてはいけません。

   選択した手法は現在の役割で適用します。独立した専門家に依頼するのは、重大なリスクや未解決の疑問がある場合に限ります。依頼する前に shared/references/model-preview.md を使い、承認済みの具体的なルートスナップショットを再利用するか取得します。独立した最終コードレビューは、別途必要なワークフローです。

6. 計画を、観察可能な検証方法に落とし込みます。変更する振る舞いごとに、それを証明するテストまたは直接確認を明記します。振る舞いに関わらない変更の場合は、自動テストが有用でない理由と、代わりの確認方法を記録します。

7. 発見した関連作業は deferred に記録します。スコープの拡大には、新しいタスクまたはユーザーからの明示的な指示が必要です。

提示済み、または継承したタスク上の選択を再利用します。重要でない詳細には、安全でスコープに沿った既定値を用います。調査できない事実が、選択する形、公開される振る舞い、リスク境界、スコープ、コスト、許可される作用、または未解決の判断を変える場合に限り、ユーザーに確認します。返答がないことは承認を意味しません。それ以外の場合は、前提を明記して作業を続けます。

出力契約

次の項目を返します。

1. design_problem：一文。
2. chosen_shape：最小限で一貫した実装の形。
3. boundaries：影響を受ける担当者、モジュール、契約、または実行時経路。
4. constraints：適用されるタスク上の決定と観点の結論。
5. verification：変更する振る舞いごとのコマンド、テスト、または直接確認。
6. test_scenarios：変更する振る舞いごとの入力、操作、期待される結果。該当しない場合は、理由と代替の確認方法を添えて Test expectation: none と記載します。
7. deferred：このタスクの対象外とする関連作業。
8. blocker_or_assumption：計画を変える可能性のある未解決の事実のみ。

ADR を作成するのは、3つの条件すべてに当てはまる場合のみです。つまり、その決定を覆すのが難しく、背景なしでは意外で、実際のトレードオフがある場合です。それ以外は ADR を作成しません。実装の最後ではなく、決定が確定した時点で記録します。

注意点

1. 通常の修正を、アーキテクチャレビューに発展させてはいけません。
2. 設計上の観点によって、承認済みタスクを超えてスコープを広げてはいけません。
3. 使い捨てのプロトタイプが必要な学習手段である場合に、トレーサーバレットを計画してはいけません。
4. 受け入れ条件と根拠の提示方法がないまま、計画を完了としてはいけません。