implement-spec

仕様の実装

現在の仕様を、レビュー可能なパスを一つずつ進めながら最後まで実装します。仕様は実装計画です。アーキテクチャが変わっても、ユーザーの制約と、受け入れ済みの実験的な証拠は引き続き遵守してください。

パス（通常は一つのスライス）は、コミットのチェックポイントであり、作業の終了点ではありません。 作業の対象は仕様全体です。すべてのスライス、すべてのグローバル TODO が含まれ、最初に成功したコミットだけではありません。パスを終えたら、ユーザーに引き渡すのではなく、次のパスを開始してください。仕様が完全に実装されたとき（または、ユーザーだけが判断できる真のブロッカーがあるとき）に限り、作業を停止してください。

依存関係グラフが許す限り、並行して作業してください。 スライスが独立しているのに、一つずつ順番に進めてはいけません。仕様の依存関係グラフを波状に読み取り、独立したパスは、同時に動作するサブエージェントに委任してください（「ルール」を参照）。オーケストレーションと統合作業はあなたが行い、前の作業に本当に依存する部分だけを順番に進めてください。

ワークフロー

1. 編集を始める前に、リポジトリの README、仕様の README、次のスライスを読みます。仕様で指定されたスキルを読み込みます。現在の着手ポイント、グローバル TODO、必須のゲート、成功状態を維持する必要があるものを特定します。複数スライスからなる仕様に有効な引き継ぎプロンプトがない場合は、最初のパスを終える前に追加します。検証済みのスパイクについては、編集前に以下の成功案を保持するを適用します。

2. 計画を現在のコードと照らし合わせます。スライスによって開発専用のシム、重複した型、弱いラッパー、または廃止された経路が残る場合は、よりシンプルなアーキテクチャに置き換え、仕様の引き継ぎ情報も更新します。

3. まとまりのあるパスを一つ実装します。通常は一つのスライス、一つの垂直チェックポイント、または一つのアーキテクチャ修正です。変更範囲は監査できる程度に小さく保ちます。

4. 実際の契約を検証します。動作を変更する場合は、まず対象を絞ったテストを実行します。ブラウザーに表示される変更では、実際のブラウザー／ハーネスを使い、スクリーンショットを確認して、単に空白でないだけでなく、対象が適切に配置され、読みやすいことを確かめます。視覚的な変更では、変更を「検証済み」とする前に、さらに二つの証拠が必要です。本番ルートで変更前のベースラインとバイト／ピクセル差分を取り（静的チェックと再固定したアサーションは、変更なしの場合にすべて合格します。配色の調整が一度「検証済み」として出荷されたにもかかわらず、本番フレームがバイト単位で変更前と同一だったことがあります）、未調整のscreenshot-critiqueを実施します。対象のパスがユーザーの視覚的な不具合報告に対応する場合は、ユーザーが報告したフレーミングで行ってください。実装者は修正によって目が慣れ、初見なら気付く問題を繰り返し見逃すことがあります。既存のデフォルトゲートを弱めたり、失敗した契約の固定値を変更したりしてはいけません。変更する場合は、従来の契約が誤りであることを証明してください。

5. 各パスの後、コミットする前に変更一覧をレビューし、整理します。 git status／git diff --statを行単位で確認し、すべてのパスを説明できるようにします。一時的な調査、スクリーンショット用スクリプト、作業用ファイル、nohup.out、場当たり的なスクリーンショット用ディレクトリ、使い捨ての SPIKE／デバッグメモをコミットに含めてはいけません。作業用ファイルはツリーの外に置きます。凍結済みの参照資料、フィクスチャ、調査の証拠は、プロジェクトの参照資料または仕様アセットの領域に保持します。長期的な用途がないファイルは出荷しません。委任したエージェントはこうしたファイルを残しがちです。統合するレビュー担当者は、統合後のツリーも同じ観点で再確認します。 パスのサイズ調整 — それがどれだけのコストを要したかを測定し、提供する振る舞いに対して行数が見合わない場合に作り直すこと — は、ステップ6のシェイプパスに属し、refactor-clean の下にあります。

6. すべてのパスの最後、コミットする前に review を実行します。 これは3つの締めくくりレンズを順序立てます — シェイプには refactor-clean、確定した差分には code-review、変更が触れたものには write-docs — そしてあなたは3つすべてからの修正を適用します。長い仕様はまさに堆積物が積み重なる場所なので、シェイプパスをこのパス自身の出力に限定してください: 開発専用のシム、重複した概念、並列の抽象化、そしてそれが導入した互換ラッパーは、単一のオーナーを持つクリーンなコントラクトに統合され、コードが今日設計されたとおりに読めるようになり、後付けにはなりません。最後に、クリーンアップされたパスに対して audit-choices を実行します — これは純粋な監査であり、仕様が沈黙していた箇所でなされたすべての決定（あなた自身のもの、および統合時に各委任サブエージェントのもの）を、判定付きで仕様の選択台帳（specs/<feature>/choices.md）に追記し、それ自体はコードを変更しません。あなたはその調査結果に基づいて行動します: 不健全な選択はその修正された決定からやり直し、ユーザー専用のエントリについては記録された暫定判断を採用します — 監査は実行を決してブロックしません。影響を受けたチェックを再実行し、その後このパスからの焦点を絞った変更のみをコミットします。

7. 仕様 README の「Next Agent Prompt」を更新します: ステータス、完了した作業、次のピックアップポイント、ブロッカー、変更されたゲート、および計画を変更したアーキテクチャ決定。

8. ループの一部として、終盤のクリーンアップとしてではなく メンテナンスチェックポイント を実行します。 レッドパスの後、2、3回のスライスコミットごとの後、リベース/再開/コンパクションの後、機能領域を変更する前、証拠が計画を無効化したとき、ハンドオフが TODO/グラフと矛盾するとき、選択台帳のエントリが1つのスライスに集中しているとき、またはアクティブなプロンプトがスキャンしにくくなったときにトリガーします。長い仕様は繰り返し肥大化します。クリーンアップは通常のパスであり、見栄えのための雑用ではありません。

   チェックポイントは、さらなる機能作業の前に計画とコードの両方をクリーンアップします:

   • README のハンドオフを、1つの現在のピックアップ、1つの優先順位、1つのコンパクトな証拠台帳に短縮し、実況はスライスファイルまたはアセットに移します。
   • 完了/却下/次回のマーカーを修正し、古い TODO、古い受け入れ主張、重複したステータスセクション、時代遅れのプロンプトを削除します。
   • 残りの作業を再ランク付けし、次のレッド/高リスクのコントラクトを明示し、その経路上にないブランチを格下げします。
   • 依然としてレッド、過負荷、または曖昧なスライスを、それを超えて実装する前に、より小さな独立して検証可能なパスに再スライスします。
   • 以前のパスからの足場がもはや実際のコントラクトを所有していない場合、削除または統合します。
   • 作業が軌道から外れていると感じる場合は、新しいレビュー/サブエージェントに仕様のシェイプと優先順位を監査させ、その後修正を適用します。 クリーンアップによって仕様、コードの形、または引き継ぎが十分に変わり、将来のエージェントがそうしなければ古いコンテキストを引き継いでしまう場合は、チェックポイントを独自の集中的なパスとしてコミットしてください。新規のエージェントが README の引き継ぎ、TODO、スライスグラフを読んで、会話履歴なしに同じ次のアクションを選べるようになって初めて完了です。

9. 続行します。 未完了のスライスまたはグローバル TODO がまだある場合は、次のもののためにすぐにステップ 1 に戻ってください — 同じセッションで、承認のために一時停止しません。すべての TODO がクローズされるまでループを続けてください。

10. 仕様全体に対してもう一度 review を実行します。 各パスのレビューは、その時点のコードに対して 1 つのスライスを評価しましたが、今回は完成した機能を評価します。スコープは最後のパスではなく、仕様の完全な diff に設定してください — スライス全体にまたがって重複が広がっていること、すべてのスライスが着地して初めて誤って読める形、機能ではなく増分を説明しているドキュメントが可視化されるのは、そのスコープだけです。修正を適用し、ゲートを再実行し、コミットしてください。

11. 選択の台帳を統合し、その後クローズします。 最後のスライスが着地したとき、パスごとに追記してきた choices.md はビルド順の堆積物です。早期に記録されたエントリには「暫定 — スライス N で再検討」という判定が含まれ、後のパスで暗黙に解決されているもの、後のパスで差し戻されたエントリがまだ残っているもの、同じ選択が 2 回現れているものもあります。パスごとのルール「記録されたものは確定、決して再掲しない」がそのドリフトの蓄積を許したのです — したがって最終的な統合はその意図的な例外です。アーカイブする前に、choices.md を最終台帳としてゼロから書き直してください: 記録されたすべての選択を（それが着地したパスではなく）最終的に出荷されたコードに対して再監査し、各暫定/後日対応エントリをその実際の最終状態に集約し、後のパスが取って代わったまたは差し戻したものは削除し、重複をマージしてください。選択のみに保ってください — ゲート結果、e2e エビデンス、レビュー所見のナレーションは含めないでください。それらは別の場所で報告されるものであり、ユーザーが今所有する決定ではありません。audit-choices に従って提示してください: 判定ごとにグループ化し、確信度の低い順にランク付けし、すべてのエントリを ELI5 かつスタンドアロンにします。その後、close-spec で仕様をクローズしてください。

勝者を保持する

• 凍結された勝利コード、構成、プロンプト/スキル、エビデンスを読んでください。その貢献が不明な癖も含め、実際の動作を保持してください。書き直された仕様やよりクリーンな設計は、測定された結果に取って代わるものではありません。
• まず移植し、実験は別に行ってください。委任先には同じ参照と制約を与えてください。ユーザーが要求する差異を記録し、その他の動作変更は採用する前に勝者に対して検証してください。
• 一致した入力と制御された外部応答を用いて、本番エントリポイントを通じて同等性を証明してください。テンプレートやコンポーネントテストだけでなく、計算されたリクエスト、決定、完全な出力、および関連するリカバリパスを比較してください。文書化された意図的な差異のみを正規化してください。コストのかかる確認の前に、これらの安価なチェックを実行し、元の品質ゲートを維持してください。
• 同等性のエビデンスが欠けている場合は未完了を意味します。参照を保持し、同等性を宣言するのではなく、独立した作業を続けてください。

ルール

• 独立した作業はサブエージェントに委任し、複数の作業を並行して進めます。 仕様の依存関係グラフを手掛かりにします。依存関係が未解決のスライス、分岐（例：フロントエンドとバックエンド）、サブスライス、複製の検証、調査作業が2つ以上ある場合は、自分で順番に進めるのではなく、1つのメッセージでサブエージェントを起動し、並行して担当させます。複数の作業でファイルを編集する場合は、それぞれに独自のGitワークツリーを割り当て、差分が衝突しないようにします。同じファイルやAPIの接点を共有する作業は、マージの混乱を避けるため、1つのエージェントにまとめます。委任した各作業単位は、実装、検証、レビュー、対象を絞ったコミットまで一貫して担当します。結果を統合して競合を解決し、統合後のツリーで影響を受けるゲートを再実行し、次のエージェントへのプロンプトに一貫性を持たせます。依存関係グラフ上で順次実行が必要な作業だけを直列化し、無関係な作業を待つレーンを作らないでください。
• リリース前または開発用の足場では、後方互換性を目標にしません。新しいアーキテクチャへの置き換えに伴い、古い経路、ラッパー、エイリアス、フォールバックモード、古くなったテストを削除します。
• うっかりテストを簡単にしないでください。分割したハーネスや新しいランナーでも、仕様で明示的に変更されていない限り、従来のデフォルトのテスト範囲を維持します。
• クリーンな作業をすべてコミットし、直ちに次の作業に着手します。成功したコミットはチェックポイントであり、停止の許可ではありません。作業が成功していない場合は、完了としてコミットせず、失敗した契約と正確な証拠を報告します。
• 未完了の作業がある限り、停止しないでください。「スライスNが完了し、コミット済み」は、後続のスライスやTODOが残っていればタスクの完了を意味しません。スライスが1つ完了したら、作業を引き継ぐのではなく、次へ進みます。正当な理由で早期に停止できるのは、ユーザーだけが判断できる重大な阻害要因がある場合、誠実な修正ではゲートを通過できない場合、またはユーザーから中断された場合に限ります。コンテキストが不足してきても停止せず、引き継ぎ情報を更新して作業を続けます。停止が必要な場合は、次に行うスライスと一時停止の理由を明確に伝えます。
• 視覚的な証拠は、実際の状態を正直に示す必要があります。コンタクトシート、GIF、スクリーンショット、ベースラインには、評価対象を意図したカメラ位置とフレーミングで表示します。
• スライスに関連する、ユーザーに見えるすべての箇所を確認します。モデル、状態、データを変更した後、メインビュー、カード、メニュー、レポート、検証用フィクスチャの内容に食い違いがあれば、作業は完了していません。
• 実装が共有動作に影響する場合は、write-docsの原則に沿って、ドキュメントまたは仕様上の根拠を残します。複製した一覧ではなく、長期にわたって維持すべき不変条件と参照先を記載します。
• 長い仕様では、仕様自体をレビュー可能な不変の基準として維持します。READMEをあらゆる試行の記録にせず、最新の引き継ぎ情報、TODO／依存関係グラフ、簡潔な証拠台帳をそれぞれ1つにまとめ、詳細はスライスごとのファイルやアセットに記載します。
• 人によるチェックポイントで作業を止めてはいけません。 スライスのレビューまたは承認ゲートでは、preview-shotsを使って該当するショットを開き、判断事項と選択肢を示して、ユーザーに検討する時間を約5分与えます。その間も、ブロックされていない他の作業を続け、決して待機しないでください。ユーザーから返答がない場合は、証拠に基づいて自分で判断し、その決定と根拠をチェックポイントの解決内容として仕様に記録して、作業を続けます。開いたショットは閉じます（preview-shotsがPreviewを終了します）。こうすることで、長時間の無人実行中にウィンドウが積み重なるのを防ぎます。目標や実装のためにユーザーの返答を待って停止してはいけません。仮定を文書化し、後から変更できる状態にして、ユーザーが後で修正できるようにします。

完了

コード、仕様の引き継ぎ、検証エビデンス、レビュー後の整理、そして焦点を絞ったコミットの内容がすべて同じ最新の状態を示した時点で、パスは完了です。その後、次のパスを始めます。

すべてのスライスと全体の TODO が完了し、すべてのゲートがグリーンで、仕様全体のレビューが実施され、その修正が反映され、引き継ぎに未対応事項がなく、close-spec で仕様がアーカイブされた時点で、初めて仕様は完了し、このスキルの作業も完了です。 そこに至っていないものはすべて実装途中です。作業を続けてください。

最終的な引き継ぎでは、差分ではなく、audit-choices に従って選択事項の台帳を提示します。何日も監督なしで実行した作業は、この台帳をもってマージに値することを示します。この台帳は、ユーザーが関与せずに決定されたすべての事項を確認するためのものです。ステップ 11 の統合済み台帳（最終状態で、出荷済みコードと照合済み、選択事項のみ）を引き渡してください。生のパスごとの追記は決して引き渡さないでください。「後のスライスで対応予定」という判定が残っている台帳は、対応済みかどうかを確認しに戻っていないことをユーザーに伝えてしまいます。

引き継ぎの最後は、追加した内容の規模で締めくくってください。台帳の後に、必ず最後に記載します。 台帳が決定事項を示すのに対し、こちらはそのコストを示します。作業全体について、次のような簡潔な表を記載してください。

	追加	削除	差し引き
本番コード（コメントを除く）
コメント
テスト／ハーネス
仕様とドキュメント

続けて、この作業で追加した構造上の要素（新しい cron、テーブル列、インデックス、エンドポイント、設定フラグ、依存関係など）を説明する段落を記載してください。これらはユーザーが今後所有し、保守するものですが、行数だけでは見えないためです。作業でほかに変更していないファイルのフォーマッターによる差分は除外し、除外した場合はその旨を記載してください。

数値がいくつであっても、はっきり示してください。小さな振る舞いの変更に対して差し引きの追加量が大きいなら、隠すべき数字ではなく報告すべき発見です。もしそのことに気づいたのが原因となったパスの時点ではなく、ここであれば、どのパスだったのかも記載してください。

スコープの単位はスライスだけではありません。 仕様には、台帳の行、判断表の項目、不変条件などの決定事項も記録されます。決定事項は、計画段階で合意されていても、特にスライスのテーマと直交する場合は、スライスに落とし込まれないことがあります。その場合、「すべてのスライスが完了」とすると、決定事項がひそかに未実装のままでも完了したように見えてしまいます。仕様の完了を宣言する前に、スライスの一覧だけでなく、記録されたすべての決定事項を出荷済みコードと照合してください。それぞれ、実装済みか、「コード対応不要」と明示されている必要があります。担当するスライスがない決定事項は、典型的な見落としです。それを防ぐ最後の砦は close-spec の監査であり、最初の防衛線ではありません。