to-spec

To Spec

タスクを、実装を規定する単一の契約にまとめます。何を変更し、何を維持し、選択した設計がどのように機能し、結果をどう検証するかを明確にします。この仕様と、そこに示された情報源を持っているものの、この会話の内容は知らない実装者に向けて記述します。仕様を提示し、実装は行いません。

現在のタスクと根拠を把握する

すべての呼び出しまたは継続時に、タスク、確定済みのユーザー決定、リポジトリの指示、調査資料を読み直します。既存の仕様がある場合は、前回の呼び出し以降の編集も含め、現在の全文と、リンク先の必読箇所を読みます。提示されたフィードバックはすべて読みます。記憶や過去の報告は情報源の特定にのみ使い、現在の内容を再構成するためには使いません。

チェックアウトとソースのリビジョンを特定します。Git のステータス、関連するコミット済みの変更、ステージ済みおよび未ステージの差分、未追跡ファイルの内容を確認し、設計を裏付ける実ファイルを読みます。指定されたリビジョンがある場合はそれを尊重し、別の状態を混在させません。Git の外にある同等の現行ソースも確認します。作業ツリーがクリーンであること、HEAD が変わっていないこと、または変更のあるファイル一覧に変化がないことだけでは、以前の根拠が今も有効であるとは判断できません。

タスクとユーザーの指示から、必要な成果、許可される変更、維持すべき動作、対象外事項、未解決の判断事項を導き出します。意図された動作と、確認済みの機能を区別します。新しい文書やレビューでの提案だけを理由に、確定済みのユーザー決定やタスクの範囲を変更してはいけません。新たなユーザー決定は、その変更が及ぶ範囲にのみ適用し、その他の制約は維持します。

ロードマップに関する作業では、支配的なタスク、関連する前後のタスク、およびリンクされた決定を再度確認します。前提条件が実際に満たされているか、先行する契約のうち何を維持する必要があるかを確認します。後続タスクが利用、拡張、置換、または移行する内容と、それが現在のタスクに求めること、さらに後続タスクに残される作業や判断事項を引き継ぎます。フェーズをまたぐ関連性も確認します。後続タスクのタイトルや、未指定の将来設計から要件を捏造してはいけません。単独の作業では、ロードマップや特定の準備スキルを必須とせず、利用可能なコンテキストを使います。

設計の前提となる動機付けの事実を検証します。必要に応じて、先行調査で使われた事実を実装、利用側、契約、テスト、設定、バージョンに関連する一次資料と照合します。未確認の事実や、候補設計によって新たに生じる依存関係を調査します。無関係な調査を繰り返さず、今も有効な調査結果を再利用します。検証済みの事実、根拠に裏付けられた推論、未解決の仮定を区別します。ロードマップのチェックボックスや提案されたインターフェースは、機能がすでに存在することの根拠にはなりません。

確立された境界内で設計を決定する

実現可能なアプローチを、必須の動作、検証済みのシステム、および制約に照らして比較します。この段階に委ねられた技術設計を選択し、その理由を説明します。その際、意味のある代替案とトレードオフも示します。ユーザーが明示的に選択・決定した事項は、引き続きユーザーの権限に留保します。実装によって設計が成り立たないと判明しても、それだけで、留保されている代替案の決定権がこちらに移るわけではありません。たとえ、代替案によって目標とスコープを維持できる場合でも同様です。

選択にあたっては、先行タスクや後続タスクとの関係を踏まえます。アプローチが必須の契約を維持するか、後続タスクの前提条件を満たすか、計画された移行を妨げるか、または後続タスクの作業と重複するかを説明します。こうした影響は、実際のタスクと証拠に基づいて説明します。現在の構造を永久に固定するのではなく、計画された置き換えを尊重します。後続タスクを設計したり、その機能を前倒しで実装したり、仮定上のニーズに備えて抽象化を追加したりしないでください。ある経路にこのタスクのスコープ外の作業が必要な場合は、スコープ内の代替案を探すか、依存関係とその影響を提示します。

調査によって確認できる事実は、自分で解決します。目的、プロダクトの動作、スコープ、責任の所在、未合意の重大なリスクの受容、または留保された設計上の選択についてユーザーの判断が必要な場合は、一度に具体的な質問を一つだけ尋ねます。証拠と有用な選択肢を提示し、独立して進められる作業は続けながら、回答を待ちます。証拠を入手できない場合は、何が不足しているのか、それによってどの判断が妨げられているのかを特定し、推測で補いません。

前提が成り立たない場合は、詳細を展開する前に、その前提に依存する結論をすべて再検討します。必要に応じて、影響を受ける部分を再構築します。タスクの根拠や境界が妥当でない場合は、その理由と、何を決定する必要があるかを説明します。要件を追加して無理に成立させてはなりません。動作に影響しないローカルなコーディング上の選択は実装者に委ねますが、外部から観測できる動作や契約を左右する選択は解決します。

実装と検証が可能な仕様を作成する

目的、必須の成果、許可する作業と対象外の作業、維持する動作、開始状態と前提条件、選択した設計、関連するロードマップ上の制約、ユーザーの意思決定の内容を明記します。意図的な選択と未解決の問題を区別できるだけの根拠を示します。

タスクに適した構成を用い、必須の文書形式にこだわることなく、次の要素をつなげてすべての作業上の要件を追跡できるようにします。

• 動作： 入力、事前条件、到達可能な分岐、観測可能な結果、状態変化、副作用を定義します。操作を完了できない場合も含め、呼び出し元と下流の利用者が何を観測するかを明記します。
• 統合： コンポーネントの責任を割り当て、必要に応じてデータ形式、検証、変換、永続化、境界を越えた識別情報について、生成側と利用側の契約を明示します。生成側が利用側の要件を満たせることを確認します。既存および提案する配置場所と、各経路を到達可能にする接続方法を特定します。
• 作業： 依存関係に沿って実装可能な作業を並べ、まとまりのある最小の一連の変更から始めて、最終成果全体を網羅します。各作業について、配置場所、前提条件、意図する変更、確認方法を示します。必要な利用側、設定、データ、テストの変更を含めますが、整理作業や別タスクの責任範囲は取り込みません。
• 検証： 各要件を、セットアップ、期待される結果、観測箇所を備えた観測可能な確認方法に結び付けます。変更だけでなく、既存動作の維持も確認します。期待値は要件と独立した根拠から導き、選択した設計自体の計算や一覧だけを根拠にしません。例だけでは誤った実装が通過し得る場合は、違いを判別できる否定ケースを含めます。

変更した契約を使用する別のエントリーポイントも含め、生成側から利用側までの完全な経路をたどります。到達可能な範囲で、関連する拒否や失敗の結果、入力の欠落や無効、部分的な副作用、再試行、重複、並行処理、復旧を明記します。検証済みの既存動作を再利用する分岐と、新たな作業が必要な分岐を特定します。互換性、移行、段階的なリリースについては、この変更で必要な場合に限って含めます。到達不可能なケースを列挙したり、隣接する機能の方針を作り出したりせず、未決定のプロダクト上の判断はユーザーに委ねます。普遍的な主張は、根拠と確認が及ぶ経路の範囲に限定します。

実装に不可欠なルールはすべて、仕様または明示的にリンクされた参照可能な必須仕様の一部に記載します。「話し合ったとおり」や「選択肢 B」といった表現は具体的なルールに置き換え、タスク固有の用語を定義し、主張の根拠となる具体的なソースの場所や文書のセクションとバージョンを併記します。必須の参照資料は、セッションにアクセスできなくても見つけられるようにします。チャット、調査概要、レビュー報告書で選択の背景を説明してもかまいませんが、それらだけを正式な参照先にしてはいけません。今後実施する検証と、すでに実施済みの確認を分け、環境上の重要な制約を記録します。

改訂を通じて、一貫性のある仕様を保つ

指定された保存先またはリポジトリの仕様書の場所を使用します。指定がない場合は、 既存のタスク仕様書を確認し、新規作成する場合は specs/<task-slug>/spec.md を 使用します。文書は1つにまとめることを優先します。分割が有効な場合は、必須の各 パートからエントリーポイントへのリンクを設定します。各ルールの正本は1か所に 定めます。ユーザーが別バージョンを求めない限り、改訂時も既存のタスク成果物を 維持します。

フィードバックの各指摘を、現在の仕様、タスク、根拠に照らして確認します。指摘を 自動的に適用するのではなく、すでに解決済みの指摘や根拠のない指摘を特定します。 修正を受け入れる場合は、誤ったルールを置き換えるか削除し、動作、インターフェース、 例、図、作業順序、受け入れ基準への影響を更新します。前提が変わったら、依存する 判断を再評価します。上記で定めた権限の範囲内で、妥当な要件を保ちながら、無効な 設計を置き換えます。

成果物は、現在の設計をひとつにまとめた読みやすい文書にします。過去の内容を残す ためだけに、レビューのラウンド、重複するルール、推測に基づく仕組み、例外を追記 しないでください。実際の不足を補うために詳細が必要な場合はありますが、追加する 内容はすべてこのタスクに役立つものでなければなりません。範囲外の改善は範囲外の ままにします。ユーザーの判断が解決するたびに、影響を受ける要件を文書全体で再確認 します。

準備完了を宣言する前に、保存した引き継ぎ内容を検証する

書き込む前に、保存先の内容を読み取ったバージョンと比較し、両立する新しい編集を 取り込み、重要な矛盾は支配的な判断に照らして解決します。仕様書全体と必須の各 パートを保存し、再度開いて確認します。自分で作成した作業リストだけでなく、元の タスクの義務とロードマップ上の制約とも照合します。範囲内の各義務について、動作、 責任の所在、作業順序または再利用の検証、受け入れ基準に一貫性があることを確認 します。明示された除外事項は維持し、計画を完了したように見せるために必須の成果を 落とさないでください。 成功パスと失敗パスのうち関連するものを境界をまたいで追跡し、受け入れチェックから 意図した成果へ逆向きにたどります。説明、例、インターフェース、図、計画の間に 矛盾があれば修正します。

新たに実装を担当する人の視点で読み、会話の記憶、アクセスできない参照資料、推測 した契約、未決定の事項に依存する箇所を洗い出します。正当なローカル実装の自由を 保ちながら、その答えを明示します。ソースの場所とリンクを確認します。ロードマップ 上の判断や依存関係を含め、関連するソース内容を設計の根拠と照合します。途中で変更 があった場合は、該当する選択肢を再検証してから、その状態に合致していると宣言 します。

タスク全体が実行可能であり、重要な事実、動作、実現可能性の問題、またはユーザーに 求めるべき判断が未解決でない場合に限り、準備完了を宣言します。残る不確実性が あれば、それが契約を変えない理由を説明します。部分的な草案、中断された確認、 範囲を限定した改訂だけでは、仕様全体が準備完了とは言えません。残る事項と解決に 必要なことを示します。後でレビューするからといって、把握済みの不足を残しては なりません。

保存した場所、選択したアプローチ、該当する場合はフィードバックへの対応、準備状況 または阻害要因を返します。実施した確認を報告し、予定しているテストを実行済みと 扱わないでください。ユーザーの依頼が次の段階も許可していない限り、この成果物の 作成をもって終了します。