close-spec

仕様をクローズする

仕様は、開発中はビルド計画であり、リリース後は根拠の記録です。クローズすると、一方からもう一方へ切り替わります。計画はスライスと予測を積み重ねたものでした。記録は、コードには収められない意味の層です。なぜこれが存在するのか、絶対に壊してはならないものは何か、どの試みが失敗したのかを記録します。コードは「どのように」の唯一の信頼できる情報源です。クローズ済みの仕様は「なぜ」の信頼できる情報源であり、コードへの道しるべです。

実装を要約しないでください。コードは誰でも読めます。関数の動作を言い換えているだけの段落は削り、代わりにその関数を示してください。

ワークフロー

1. リリース済みであることを確認します。 機能がマージ済み、またはツリー内で動作しており、テストとスクリーンショットの確認項目がすべて成功していることを確認します。未検証のスライスが残っているなら、まだ完了していません。先に完了させるか、レビューを行ってください。

2. 計画と実際の差分を確認します。 仕様の README とスライスを読み、その後、実際に取り込まれた内容を読みます。ビルドが計画から逸れた箇所をすべて記録します。削除されたスライス、名前が変わった境界、予想とは異なる仕組み、崩れた前提などです。こうした差分は、記録する価値が最も高い情報です。将来の読者が再び導き出すことになる内容そのものだからです。

3. 移動します。 specs/<feature>/ → specs/done/<feature>/（git mv を使用）。単一ファイルの仕様の場合は、specs/<feature>.md → specs/done/<feature>.md とします。

4. README を計画ではなく記録として書き直します。 次の内容を残します。

   • 概要と目的 — リリースされたものと、それが解決する問題を現在形で記述します（「経済は毎月精算されます」）。未来形（「追加します」）にはしません。
   • 理由 — 明白な代替案ではなく、この方法を採用した理由を記述します。形を決定づけた制約とトレードオフも含めます。ここはコードからは読み取れない部分です。
   • 原則と不変条件 — 実装が守り続けるべきルールを記述します。何が真であり続けなければならないか、違反すると何が気づかれないまま壊れるかを明確にします。
   • コードへの手がかり — grep で検索できるモジュール、型、関数の名前、ファイルパス、挙動を固定するテストを記載します。仕組みの詳細はコードを参照するよう案内し、1 回の grep で見つけられるようにエントリーポイントを示します。
   • 行き止まり — 試して却下した方法と、その理由を記録し、誰も同じ道をたどり直さないようにします。
   • ビジュアルの由来 — 見た目を合わせるためのベースライン、比較対象、またはインスピレーションとしてアップロードされた画像があれば記載します。これらは要件そのものです。「完了」とは何に似ている必要があったのか、なぜ結果がその形になったのかを示します。リポジトリ内に残し、それぞれの出所（実際のスクリーンショット、ムードボード、参考ゲームなど）と、何のために使われたのかを README から参照します。これらがなければ、読者には結果は見えても、どの基準に照らして作られたのかはわかりません。

   削除するもの：スライスごとのビルド順、「次は〜します」といった記述、足場づくりの手順、スライスごとの検証チェックリスト、およびコードを改めて説明する文章。

5. スライスをまとめ、画像は残します。 スライスはビルドの足場でした。リリース後は、その役目を終えています。永続的に役立つ情報（差分、行き止まり、スライスで確立された不変条件など）は README にまとめてから、slices/ を削除します。ただし、ベースライン、比較、インスピレーションの画像は残してください。作業の評価基準となった参照画像と、結果を判断する助けになる visualizations/ や assets/ も残します。これらは足場ではなく、由来を示す資料です。ビルド手順は捨てても、ビルドの目標を定めた画像は決して捨てないでください。それぞれを README のビジュアルの由来に関する記述から参照し、要件がどこから来たのかという経緯がクローズ後も残るようにします。

6. 参照を修正します。 古いパスを指していたリンクを更新します。[[memory]] のメモや他のスキルが仕様を参照している場合は、参照先を変更します。

7. すべての記述を、偏りなく監査します。 仕様書を書いておらず、会話の文脈も持たないサブエージェントを起動し、最終ドキュメントを実際のコードとテストに照らして1つの主張ずつ確認させます。分担して進めてください — 1セクションにつき1エージェント、あるいは主張のリストを複数のエージェントに分割することで — 偏った単一のパスがそのまま通してしまうことを防ぎます。各エージェントは記述ごとに判定を返します:

   • ポインター（名前を挙げられたモジュール/型/関数/ファイル/テスト） — それは実在し、仕様書に書かれている通りの内容になっていますか？ 古くなった名前や誤ったパスにフラグを立ててください。
   • 不変条件 / 原則 — それは実際にコードで強制されているのか、それとも単に主張されているだけなのか？ コードが矛盾している、あるいは裏付けていない主張にフラグを立ててください。
   • 概要 / 理由 — それは出荷された内容と一致しており、現在形で書かれ、取り残された「will」や「next」、スライス番号はありませんか？
   • 視覚的来歴 — 参照されているベースライン/インスピレーションの画像は今もツリー内に存在し、README はそれぞれがどこから来て何を導いたかを説明していますか？ 準拠すべき標準が示されていないまま提示された結果にフラグを立ててください。

   裏付けのない記述、矛盾する記述、古くなった記述は欠陥として扱ってください: 仕様書（またはポインター）を修正し、変更された主張を再監査します。いずれかの記述が未検証である限り、仕様書は完了していません。

スメルテスト

• 読者がコードを読むことでこの段落を再構成できるか？ → それは削り、ポインターを残します。
• 「will」や「next」と書かれている、あるいはスライス番号が名付けられているか？ → それはまだ計画です。
• 実際の決定が計画から逸脱し、記録されていないままになっていないか？ → それは残す価値のある唯一のことです; 追記してください。
• 照らし合わせていたベースラインやインスピレーションの画像があったか？ → それを残し、何を導いたかを書き記してください; 標準がなければ結果は無意味です。

完了

仕様書は specs/done/ の下に置かれ、どのようにではなくなぜと何が成り立たなければならないかとして読まれ、それを実装するコードを名指しし、作業が照らし合わされたベースラインとインスピレーションの画像を保持しており、すべての記述がコードに対する偏りのない監査を生き延びています。新たな読者は、コードなしで意図と不変条件と視覚的標準 — なぜ完了したのか、そしてどのように決定がなされたのかという物語 — を理解し、ポインターをたどることでその仕組みを理解します。