write-implementation-plan

実装計画

obra/superpowers のコミット b36e0829c6d0140e93cfef2ca599b1b07d4a7797（MIT）を基にしています。検証可能な単位の順序付けと移行後のクリーンアップは、コミット 93b00b89ef425a9c1bac0d0b317dfc49c930ac99（MIT、Copyright (c) 2026 Cursor）の Cursor の poteto-mode を基にしています。トレーサーバレットによる分割と、大規模リファクタリングにおける拡張–縮小の例外は、コミット 3cca18b368ae95cdbdebbff572ccafa662551015（MIT、Copyright (c) 2026 Matt Pocock）の Matt Pocock の to-tickets を基にしています。

会話の文脈がない実装担当者に向けて書いてください。振る舞いは仕様が定め、この計画が定めるのは実行の分解のみです。これは planning-contract（契約バージョン：1）で定められた権限の範囲によります。この計画は簡潔な実行マップであり、仕様を書き直すものではありません。この契約スキルがインストールされていない場合は、継承したルールや独自に作ったルールに基づいて計画せず、作業を中断して planning-contract のインストールを依頼してください。依存関係が自動的に解決されると決して想定しないでください。

成果物の方針

• 1 人の担当者が行う範囲の限られた変更では、計画ファイルは作成せず、承認済みのチャット内の設計をそのまま orchestrate-implementation に渡してください。ただし、キャプチャチェックポイントの結果は、状況に応じて適用します。
• アーキテクチャに関わる作業や複数のステップを要する作業では、依存関係、担当、統合の順序、検証が明確になる最小限の計画を作成してください。
• 独立したサブシステムは、1 つの巨大な計画にまとめず、別々の計画に分割してください。
• 計画ファイルが必要な場合は、planning-contract のファイル名規則 YYYY-MM-DD-NNNN-slug.md に従ってください。計画には元となる仕様とまったく同じ接頭辞を使ってください。それ以外の場合は、プロジェクトの仕様ディレクトリと計画ディレクトリ（project/specs/ と project/plans/、旧構成では docs/specs/ と docs/plans/）にまたがる共有シーケンスから、次の番号を割り当ててください。
• トラッカーチケットは、ユーザーから依頼された場合、既存のトラッカーで必須の場合、または調整事項を現在の実行後も引き継ぐ必要がある場合にのみ作成してください。各タスクをチケットとして公開してください。チケットがタスク本文の正本となり、概要からリンクしてもかまいませんが、編集可能なタスク定義を重複して管理してはいけません。

ADR は「なぜ」を説明し、仕様は「何を」定義し、計画やチケットは実行可能な次の単位を定義します。

Lean assurance default

受け入れ基準を満たし、具体的かつ重大なリスクに対処するために必要な、最小限の証拠セットを計画します。異なる到達可能な失敗モードを対象としない限り、テスト、検証コマンド、レビュアー、レビュー境界を追加しないでください。その失敗に名前を付けられない場合は、保証作業を省略します。

各検証単位は、最小限の連鎖として割り当てます。つまり、対象とする名前付きの失敗 → 期待される結果を示す独立した判定基準（承認済みの基準、手計算した例、信頼できるリファレンス、または実際のバグ） → 1つの焦点を絞ったチェック、または該当する既存の証拠を明示的に再利用すること → その証拠を無効にする変更差分です。一般的なレイヤー別・フェーズ別のマトリクスや認定チェックリストは採用しません。ただし、プロジェクトやCIで必須と明記されたゲートがある場合は、この既定の方針より優先し、そのまま計画に含めます。

各検証単位は、次のいずれかに分類します。

• low risk — ドキュメント、機械的な編集、生成された出力、または動作を変更しない内部リファクタリング。既存のチェック、または最小限のスモークテスト、解析、ビルド、差分確認を使用します。テストや独立したタスクレビューは追加しません。
• normal risk — 通常の動作変更やバグ修正。最も低コストで安定した接点において、焦点を絞った回帰テストを1つ、または既存のチェックを1つ使用し、候補レビューを1回行います。同じ動作を単体、統合、API、ブラウザーの各レイヤーで重複して検証しないでください。または
• high risk — 認証、権限、シークレット、金銭、破壊的なデータ処理、マイグレーション、並行処理、分散動作、公開インターフェース。名前を付けた脅威や失敗モードを対象とし、後続の作業で結果を利用する場合は、その時点でレビューを必須とします。

1つの検証単位で、密接に関連する複数のタスクを対象にできます。検証が必要なのは、すべてのチェック項目ではなく、変更された動作やリスクです。各タスクでテスト、lint、型チェックの全マトリクスを繰り返すのではなく、必須のリポジトリCIを再利用します。テストを求めることも指摘事項です。実際に到達可能なシナリオと、違反される基準を明示してください。カバレッジ率や、実現不可能なドメイン状態は理由になりません。文書化された規約には従いますが、文書化されていない好みを理由に作業を止めてはいけません。新しい作業者やレビュアーが状況を勝手に推測しないよう、実際の呼び出し元、入力の由来、環境、適用される指示・スタイル・lint規則（または該当するものが見つからなかったこと）を特定します。

セキュリティレビューを行うのは、タスクが信頼できない入力または外部入力、認証情報、認証、依存関係の変更に関わる場合に限ります。実際の利用経路に沿って、保護対象の資産、現実的な攻撃者、攻撃経路を明示します。信頼された内部呼び出し元や、ユーザーが所有するローカルファイルは、既定では悪意あるものとして扱いません。サービスについては、実際のデプロイ境界を使用します。シークレットの窃取、TLSの破損、悪意ある管理者、一般的なハードニングを持ち出したストーリーは指摘事項になりません。境界に触れない場合は security: n/a とします。セキュリティ関連の作業で事実が不足している場合は unverified とし、脅威モデルを捏造せずに確認を求めます。文書化された安全性の保証は維持します。

親タスクが承認した修正パスは最大1回、その後の再確認は変更差分に限って1回まで計画します。残ったブロッカーは追加のラウンドに進めず、人間に引き継ぎます。候補レビューでは、未レビューのコードと統合による影響を確認し、決着済みの指摘を再検討しません。証拠台帳、レビュー承認、2つ目のライフサイクルは追加しません。

事前確認

1. 承認済みの仕様、プロジェクトの指示、関連するコード／テスト、確立されたドメイン用語集や意思決定記録を確認します。
2. 準備状況のゲート： planning-contract に従い、承認済みの動作の根拠（承認済みの仕様、または変更範囲を限定した同等の文書）があることを必須とします。調査結果や検証の判定は根拠資料であり、仕様の代わりにはなりません。根拠資料がない場合は作業を中止し、不足している前提条件を具体的に報告して、作業を shape-design に差し戻します。
3. 要件が矛盾している場合、または重要なオーナー判断が未解決の場合は中止します。
4. 計画中に動作、インターフェース、または範囲に関する重要な変更が判明した場合は、shape-design に差し戻します。根拠資料を更新し、変更後の範囲と改訂版の承認を取得してから、契約の準備状況ルールに従って根拠資料とタスク分割の整合が取れるまで、影響を受けるタスクをブロックします。
5. 独立したサブシステムは、個別の計画に分割します。
6. ファイル、責務、インターフェース、依存関係、統合順序を特定します。最初に着手すべきブロッキング作業、独立した作業ストリーム、書き込み対象の共有、最小限かつ安全な分割を明らかにします。同じ動作と検証の境界を共有するステップはまとめ、分割によってレビューや調整の負担が増える場合は、順次作業を担当する単一のオーナーを優先します。契約の並列実行ルールを満たす場合にのみ、タスクを並列実行可能としてマークします。
7. 確立されたプロジェクトの規約に従い、無関係なリファクタリングを計画に紛れ込ませないでください。

リポジトリで確立されている計画の保存場所を使用します。存在しない場合は、新たなドキュメント規約を作成する前に、保存場所またはランタイム管理の成果物を提案し、承認を得てください。

計画のヘッダー

仕様の内容を繰り返さず、リンクしてください。次の項目を含めます。

• 目標。
• 仕様のパス、承認の参照情報、承認済みの正確な範囲と改訂版。
• キャプチャチェックポイントの結果。
• 作業の順序付けに必要なアーキテクチャ上の制約と対象外事項のみ。
• 技術／ランタイムの前提条件。
• 仕様の受け入れ基準を参照する、要件とタスクの対応表。
• 必須のリポジトリ CI で暗黙に求められていない、最小限の全体検証コマンド。

タスク

トレーサーバレットスライス

垂直スライスに分解します。各タスクでは、対象となるすべてのレイヤー（スキーマ、API、UI、テスト）を通る、狭くても一貫した経路を切り出し、単独でデモまたは検証できるようにします。中間状態では観察可能な動作が得られない水平レイヤー単位のタスク（まずスキーマ、次に API、その次に UI のタスク）には分解しないでください。完了したスライスでも、リポジトリの一貫性が保たれ、CI が成功する状態にします。

変更しやすくしてから、簡単に変更します。スライスの実装が現在のコード構造と衝突する場合は、その中に隠してしまわず、動作変更タスクの前に明示的なプレリファクタリングタスクを計画します。

大規模リファクタリングは、垂直スライスの例外です。 大規模リファクタリングとは、カラム名の変更や共有シンボルの型変更など、コードベース全体に影響が及ぶため、垂直スライスでは CI が成功する状態で完了できない、機械的な変更を指します。拡張・縮小の順序で進めます。まず新旧の形式を併存させ、新形式を追加します。次に、影響範囲に応じた規模のバッチに分けて呼び出し元を移行し、各バッチを独立したタスクとします。各タスクは拡張タスクに依存し、旧形式がまだ存在するため CI が成功する状態を保ちます。呼び出し元がなくなったら、すべての移行バッチに依存するタスクで旧形式を削除します。バッチ単独で CI が成功する状態を保てない場合は、作業を共有の統合ブランチ上で進め、最終的な統合・検証タスクでのみ CI 成功を約束します。この一連の作業における各タスクの一貫性は、main ではなく統合ブランチを基準に判断します。

タスクとは、実際の依存関係、所有権の境界、または独立して有用な動作を明らかにする、最小限で一貫性のある成果物です。レビューや検証の機会を増やすだけの目的で作業を分割しないでください。すべてのタスクに実行可能なチェックを割り当てますが、関連するタスクで検証ユニットやレビューの境界を共有してもかまいません。各タスクには次の内容を明記します。

• 作成または変更するファイルの正確な一覧。
• 使用するインターフェースと提供するインターフェース。
• 前提条件。
• 動作とエッジケース。
• 検証ユニットとテスト要件（new-test、existing-check、no-new-test のいずれか）、それぞれが対象とする固有の失敗モード、および既存の証拠を再利用する場合は、適用可能な過去の結果とそれを無効にする条件。
• 必須の CI でまだ実行されていない、対象を絞ったコマンドと期待される証拠のみ。
• 完了条件。

チェックボックス形式で手順を記述します。変更した動作に意味のあるテストカバレッジがない場合に限り、new-test を割り当てます。安定性が最も高い公開インターフェースで、対象を絞ったテストを 1 つ実施することを優先します。new-test の場合は、対象を絞ったテスト、独立して導き出した期待値、検証コマンドを示します。失敗を再現する場合と、リファクタリング前に動作を固定する場合に限り、先に失敗を確認する手順を示します。正確なシグネチャや、曖昧さを防ぐために明示が必要なロジックに限り、コードスニペットを含めます。説明文で大規模な実装を創作しないでください。

内部移行では、置き換え、呼び出し元の移行、検証、旧経路の削除、古い参照の検索を、1 つのクリーンアップにまとめます。一時的な互換性名を使う場合は、実際の利用者と削除条件を明記します。

品質ゲート

引き継ぎの前に、次の項目を確認します。

1. すべての要件が少なくとも 1 つのタスクに対応付けられていること。
2. TBD や TODO などのプレースホルダー、曖昧なエラー処理、名前のないテスト、未定義のインターフェースを検索すること。
3. 依存するタスク間で、名前と型に矛盾がないことを確認すること。
4. 各タスクの完了時に、リポジトリの一貫性とテスト可能性が保たれることを確認すること。
5. 重複するチェック、同じ動作に対する重複カバレッジ、到達可能な失敗モードが明示されていないレビューまたは検証手順を削除すること。
6. 残るリスクと、それに必要な手動チェックのみを明記すること。
7. 引き継ぎにあたり、コントラクトのバージョンと、利用可能なインストール済みの来歴情報を記録すること。不明な場合は unknown とします。

計画を提示してユーザーの承認を得ます。承認後、承認済みのソース参照、キャプチャチェックポイントの結果、記録済みのコントラクト来歴情報を添えて、orchestrate-implementation に引き継ぎます。2 つ目の実行ルーターは作成しないでください。