write-spec

Spec の作成

大きな機能を、小さな契約を積み重ねた段階的な構成に変換します。各段階は、人間が理解でき、エージェントがテストでき、機能全体が完成する前から役立つものでなければなりません。

基本原則

1. 計画の前に掘り下げます。 望ましい成果、対象外のこと、レビュー対象、変更してはならない契約、不足しているアセット、最初に役立つプレイ可能なチェックポイントが分かるまで、一度に一つずつ質問します。各質問には推奨する回答を添え、ユーザーが承認、拒否、編集できるようにします。コードから答えが分かる質問をするのではなく、リポジトリを調べます。聞き取りの最後に、後方互換性やデータ移行が必要かどうかを尋ねます。デフォルトはどちらも不要です。つまり、完全な切り替えとし、互換性のための仕組み、移行用の足場、デプロイ順序の調整は行いません。ユーザーが明示的に希望した場合にのみ、計画に含めます。

2. API の境界でスライスします。 可能な限り、各スライスは小さなライブラリのように機能させます。名前の付いたモジュール境界、型付けされた入出力、決定論的なフィクスチャ、境界でのテストを用意します。チェックに無関係なシステムを3つ起動する必要があるなら、境界を明確にします。

3. 不確かな領域を調査します。 機能が、なじみのない分野、忠実度の高いビジュアルの参照先、特定の参考例、ベンチマーク、外部リポジトリ、ライブラリ、または「一般にはどう実装するのか」という疑問に依存する場合は、スライスを確定する前に対象を絞ってオンライン調査します。公式ドキュメント、ソースリポジトリ、論文、事例研究、講演、公開済みの実例など、一次情報を優先します。参照実装が存在する場合は、別の形に翻訳したり近似したりする前に、再現するためのスパイクを追加します。

4. 進捗を見えるようにします。 ビジュアルまたはインタラクティブな作業では、各スライスで、ルート、フィクスチャページ、ハーネス、CLI プローブ、HTML ビジュアライゼーションなど、人間が実行、確認、スクリーンショット撮影、評価できるプレイ可能な成果物を作ります。テストは契約を証明し、デモは見た目や意図を伝えます。

5. フィードバックループを最適化します。 次に役立つ問いに素早く答えられるようスライスします。機能全体が完成するまで何も分からない計画ではなく、小さく実行可能な画面、ホットリロード可能なハーネス、サンプルフィクスチャ、自己完結したワークベンチを優先します。アセットが多い作業では、人間やアーティストがサンプルを追加したり、差し替えファイルをアップロードしたり、ライブプレビューを確認したり、検証エラーをすぐに把握できたりするアセットアプリやワークベンチを計画します。

6. リポジトリ本来の構造を活用します。 リポジトリがモノレポなら、すべてを現在のアプリに無理に押し込むのではなく、アプリとパッケージを計画します。テスト可能な各画面や機能には専用のルートまたはコマンドを用意し、小さな専用アプリのほうが明確な場合は、新しい動作を分かりにくいクエリフラグの背後に積み重ねないようにします。

7. 入力不足を理由に止まりません。 アート、データ、認証情報、外部アセットが不足している場合は、生成したプレースホルダーと差し替えの契約を計画します。プレースホルダーで機能の開発を進められるようにしつつ、人間または外部パートナーが後から何を用意すべきかを正確に説明する、別の引き継ぎ手段を設けます。

8. 並行して草案を作り、統合します。 複数のスライスを含む機能では、1回の検討で最適な分割が見つかるとは限りません。複数の独立した草案を作り、最良の案を一つの計画にまとめます（ワークフローを参照）。意見の違いこそが重要です。そのため、各草案に異なるバイアス（最適化する観点）を持たせ、複数のモデルファミリーが利用可能なら、モデルも組み合わせます。バイアスを変えた複数の草案を互いに見せずに作成すると、単独の計画では見落とすスライス、境界、リスクが浮かび上がります。また、独立した草案が一致する部分は、その分割が確かなことを示します。

9. 霧の中に隠れた不確実性を繰り返し明らかにします。 最初のスライスグラフは偵察であり、全体を把握できた証拠ではありません。草案の作成後は、リスクの高い各スライスを独立した機能として扱い、詳しく調べます。複数の変数、未知の外部慣行、未検証のアーキテクチャ、または「実装しながら考える」部分が隠れている場合は、その部分をさらにスライスし、各スライスに一つの問い、一つの境界、一つのレビュー対象、一つの判定が揃うまで繰り返します。

10. スライスごとに視覚的な変数を1つだけ扱います。 1回の作業で最終的なヒーロー画像に合わせようとすると、視覚的なスライスはうまくいきません。評価対象ごとに分割します。密度、シルエット、色、テクスチャ、ライティング、霧、水の配置、水の素材、ラベルの読みやすさ、アニメーションのリズムなどです。各スライスには、対象を切り出した画像またはマスクと、その変数だけに対する判定を用意します。フレーム全体の比較は、各変数の根拠がそろってから、合成・統合の段階で行います。

ワークフロー

1. ヒアリング： 手探りの説明なしにスライスを列挙できるまで質問を続けます。残る不明点を最初のスライスで安全に明らかにできる段階で止めます。
2. 調査： 機能でリファレンス、ライブラリ、手法、標準、視覚的な目標、またはパフォーマンスパターンが指定されている場合、草案を作成する前にリポジトリを調べ、なじみのない外部の実践例を調査します。見つかったソース、リポジトリ、記事、論文へのリンクを仕様に記録し、移植スライスに進む前に、実例を再現するためのスパイクを設けます。 これまでの実験ですでに採用するアプローチが確立されている場合は、代替案を作成する前に、以下の調査から実装へを適用します。
3. 並行して草案を作成： 複数スライスに分かれる機能では、少なくとも3つの独立したサブエージェントを起動し、計画全体の草案を作成させます。各エージェントには新しいコンテキストを用意し、検証のために実行またはビルドが必要なら、それぞれにGitワークツリーを割り当てます。そうでなければ、計画をそのまま返してもらいます。3つは最低数であり、最適な数ではありません。機能の複雑さに応じて人数を増やし、問題に真に異なるアプローチや視点がある場合は、それぞれに草案作成者を追加します。各エージェントには、ヒアリングで得た同じブリーフだけを渡し、他の情報（別の草案など）は渡しません。ただし、各エージェントには異なるバイアスを割り当て、偶然ではなく意図的に異なる草案が出るようにします。基本となる3つの役割は次のとおりです。
   • A — スライス数を最小化するバイアス： 出荷に必要なスライスを最小限にした段階的な計画を作ります。スライスを積極的にまとめ、すべての段階が本当に必要かを問い直します。
   • B — リスクを優先するバイアス： 最も不確実でリスクの高い要素を先に扱います。前提が間違っていたときに計画が早く行き詰まるよう、スライスの順序を決めます。
   • C — 境界の品質を優先するバイアス： スライス数が増えても、各境界でのAPI、責任の所在、テスト容易性を最適化します。 機能が求める場合はレンズを差し替えるか追加します（例：アセットパイプラインのバイアス、パフォーマンスのバイアス、移行安全性のバイアス）。ただし、バイアスは直交させたままにします — 同じレンズを二度使うのではなく、新しいレンズを追加してプールを成長させます。さらにモデルファミリーを混ぜます：現在 codex でドラフトを作成するよう指示されているなら、少なくとも 1 つのドラフトを claude で実行します — またその逆も同様です — そうすることで、プールは異なるプロンプトだけでなく、異なるモデルの盲点のバランスを取ります。ファミリーとはベンダー（claude 対 codex）を意味し、ティアではありません。すべてのドラフトは最先端のモデルを使用します。同じファミリーの弱いティアに落とすことで多様性を確保してはいけません。各ドラフターは：実際のコードとテストを偵察し（測定された事実、失敗したアプローチ、スコープファイアウォール、grep 可能なファイル名／テスト名）、次にスライスグラフ、パッケージ／アプリの境界、依存関係、API シーム、プレイアブルな成果物、検証ゲート、人によるレビューのチェックポイントを提案します。真に単一スライスの問題に限り、ファンアウトを省略します。
4. 統合： すべてのドラフトを読み、正典となる計画を自分で構築します — 1 つを選んで神格化してはいけません。最も強力なスライシングを採用し、各ドラフトが単独で捉えたシーム、リスク、ファイアウォールを統合し、ドラフトが不一致の場合はより正当化された判断を選び、真の代替案を人間のために記録します。ドラフトが独立に一致する箇所は堅固な地盤であり、分かれる箇所こそ最も深く考えるべきところです。機能に視覚的な面がある場合は、screenshot-critique を README 内の常設の検証ゲートにし、すべての視覚スライスがそれを継承するようにします：仕様は、実装エージェントに対し、視覚的なショットを受け入れる前に最後のチェックとして偏りのない screenshot-critique を実行するよう指示しなければなりません。スライスにそのショットと比較すべきものがある場合 — 変更する以前の見た目、または機能のために追加された参考／インスピレーション画像 — 仕様はさらに compare-screenshots を、候補対ターゲットを判定するゲートとして指定しなければなりません：screenshot-critique の単発の目では得られないテレメトリと less-wrong の判定です。
5. 再帰的フォグ監査： 正典グラフをスライスごとにレビューします。隠れた変数、広範な動詞（「リアルに仕上げる」「参考に合わせる」「バックエンドを追加する」）、欠落した調査、または複数の視覚変数／API シームを持つスライスについては、そのスライスをサブ機能として同じスライシングロジックを実行します。次の実装スライスが 1 つの焦点を絞った成果物によって受け入れまたは拒否できるようになるまで繰り返します。延期された変数は、現在のスライス内の散文ではなく、後続のスライスとして記録します。終了テストは意思決定予算です：実装エージェントが意思決定を行うのではなく継承するとき、スライスは完全に仕様化されています — 残されたあらゆる自由は、スライスファイル内で委任として明示されるか、そうでなければスライスにはもう 1 回のパスが必要です。
6. 具体化： 機能に複数のスライスがある場合、またはアセット／可視化が必要な場合は、specs/<feature>/ を作成します。
7. 計画をリファクタクリーンする： 具体化された仕様に対して refactor-clean を実行します — 計画もまたアーキテクチャであり、今日設計するならコードベースが望む形を記述しなければならず、機能を後付けした古い形であってはなりません。単一のオーナーを持つべき各概念（プロジェクション、環境、データコントラクト、レンダラーフェーズ、ステートマシン、テストオラクル）を明示し、どのスライスも並行する抽象化、重複する概念、または後のスライスが削除しなければならない互換レイヤーを導入しないことを確認します。スライスが真に必要とする過渡的な足場は、明示的な削除条件とそれを削除するスライスを伴う短命なシームとして明示しなければなりません — そのコンシューマーが移行した瞬間に折りたたまれ、デフォルトで最後まで持ち越されてはなりません。結果として得られる単一オーナーの不変条件と最終状態（「今日設計されたとおりに読め、後付けではない」）を README にエンコードし、すべての実装パスがそれを継承するようにします。
8. スクロールバック監査： 会話は消え、仕様は生き残ります。計画を完了とする前に、会話全体と以前のすべての計画成果物（マップ、インタビューノート、ドラフト）を精査し、そこにしか存在しない内容を探します — 根拠を伴う意思決定、なぜ敗れたかの理由を伴う却下された代替案、途中でのスコープ変更、ユーザー提供の制約、そして何かを決定づけた捨てられた発言。それぞれは、所有する仕様ファイルに落ちるか、意図的に破棄されます。スコープ変更は、それが落ちた場所だけでなく、それを参照するすべての箇所に伝播します。次に、仕様が取って代わる生存している事前計画成果物（マップのキックオフザプロンプト、未解決の質問リスト、または提案された計画）をそれぞれ再読し、取って代わられたセクションを計画へのポインターでマークします — 古い指示が新たなエージェントを誤った方向に導くことができてはなりません。すべての会話の意思決定が仕様内で見つけられ、生存している成果物がラダーと矛盾しないときに完了です。
9. スライスごとに構築： 各スライスは、それに依存する前に、実行可能な成果物と検証を残します。各成果物は、すばやく反復できる程度に小さく保ちます。README の「Next Agent Prompt」は、将来のエージェントが読み従うべきハンドオフテキストとして書き続けます。
10. 作業がそう告げるときにリ・スライス： 実装が行き詰まり、スライスが無関係な変数を変え始めた場合 — または選択の台帳が 1 つのスライスから埋まり続ける場合 — パッチの拡大を止めます。まず仕様を更新します：スライスをより小さなコントラクトに分割し、凍結された入力を明示し、余分な視覚変数を後続のスライスに移し、Next Agent Prompt を最初の新しいスライスから再開するように書き換えます。その後、続行します。リ・スライスは進歩であり、失敗ではありません。

調査から実装へ

採用したスパイクの実行可能なコード、依存関係、設定、入力、プロンプト／スキル、および証拠を、不変の識別情報で固定します。実際の動作を確認してください。オプション名や概要は、動作の証明にはなりません。

仕様書で、実証済みの動作 → 証拠 → 担当スライス → 同等性ゲートを対応付けます。すべての起草者に、この契約と調査結果の限界を伝えてください。ユーザーが必須とする差異と、未検証の提案は分けてください。クリーンアップによって、採用案をひそかに再設計してはなりません。

固定したリファレンスと本番エントリーポイントを、入力を一致させ、応答を制御した状態で早期に比較する計画を立てます。計算されたリクエスト、判断、完全な出力を確認し、許容される差異を明記してください。維持する項目にはすべて、担当者と確認方法を割り当てます。コストの高い確認の前に同等性を検証し、元の品質ゲートも維持してください。

計画フォルダー

小規模で単一スライスの問題には、specs/<feature>.mdのみを使用します。大規模な機能は、次の構成にします。

• specs/<feature>/README.md — 目標、背景、スライスの関係図、レビュー対応表、契約、分離境界、既知の未解決事項、および現在の状況、次の着手箇所、全体のTODOチェックリスト、次の作業担当者への引き継ぎ手順を記載した「次のエージェントへのプロンプト」セクション。
• specs/<feature>/slices/<NN>-<name>.md — 独立して検証できるスライスを1ファイルに1つずつ記載します。
• specs/<feature>/visualizations/*.html — ロードマップ図、プロトタイプ、ハーネスのモックアップ、生成レポート、コンタクトシート、その他の人がレビューできる成果物。
• specs/<feature>/assets/ — 参照画像、フィクスチャ、キャプチャ、および作業の評価に必要なその他の入力。

ビジュアル作業では、機能に関するビジュアル証拠を仕様フォルダー内に保管します。インスピレーション用の画像、参照スクリーンショット、保存したベースライン、比較用コンタクトシート、生成した候補のキャプチャ、批評用の成果物などが含まれます。それらのファイルが最初は仕様フォルダーの外にあっても、機能のレビュー対象になった時点で仕様フォルダーにコピーしてください。製品スナップショットのフォルダーには、各ハーネスが管理するアクティブな回帰テスト用ベースラインを引き続き保管できますが、変更される可能性のある出力や外部パスを、機能の評価対象を記録する唯一の手段として頼りにしないでください。

スライスファイルの契約

各スライスファイルでは、次の点に答えてください。

• どの契約がこれによって利用可能になりますか？
• API の境界は何ですか？（モジュール、関数／型、データ構造、所有権）
• 人間は何を実行したり、確認したりできますか？
• 何のテスト、シナリオ、スクリーンショット、プローブ、パフォーマンスゲートで検証しますか？
• スライスで何らかのビジュアルショット（スクリーンショット、GIF、コンタクトシート、画面上のレンダリング）が生成される場合、スライスファイルには、スライスの受け入れ前に最後の確認として、実装エージェントが screenshot-critique を実行するよう指示する必要があります。これは、回帰ゲートや実装者自身による確認では得られない、事前の情報に左右されないセカンドオピニオンです。単なる言及ではなく、明示的な検証手順としてスライスに記載してください。
• スライスのショットに比較対象（変更前の見た目、または機能のために追加した参考画像）がある場合は、スライスファイルでエージェントに compare-screenshots を使って候補と比較対象を評価するよう指示する必要もあります。目的はテレメトリーを得て、より適切な判定をすることであり、ショットが参考画像と一致するかを確認することではありません。こちらも明示的な手順として記載してください。
• 参考画像を使うビジュアルスライスでは、判定に使う スライス変数 と クロップ／マスク を明記してください。また、範囲外とする、目に見える不備も列挙してください。例：草の密度を扱うスライスでは、画面下部 3 分の 1 の被覆率と減衰のみを比較し、崖の形状、崖のテクスチャ、水、空、霧は後続のスライスで扱います。崖のシルエットを扱うスライスでは、尾根の輪郭と奥行きの列のみを比較し、岩のテクスチャと霞は後続のスライスで扱います。
• 実装者に委ねる判断は何ですか？ 意図的に未確定とする自由度（内部構造、命名、元に戻せる見た目上の判断）を明記してください。それ以外はすべてスライスで解決する必要があります。実装者が独自に決めなければならない、記載のない判断は仕様の抜け漏れであり、選択肢台帳（audit-choices）に記録します。実装者の裁量に任せてはいけません。
• 何を成功状態に保つ必要がありますか？
• 人間からのどのようなフィードバックが、このスライスを変更しますか？
• スライスに人間によるレビューのチェックポイントがある場合、スライスファイルではそれを 非ブロッキング と位置付ける必要があります。実装エージェントには、preview-shots でショットをユーザーに開き、短い時間（約 5 分）を設けて返答を待つよう指示してください。ユーザーから返答がない場合は、得られた証拠に基づいて判断し、その判断と根拠を仕様に記録し、開いたショットを閉じて（preview-shots は Preview をクリーンアップするため、夜間実行でウィンドウが増え続けることはありません）、作業を進めるよう指示してください。サインオフを待って実装を止めてはいけません。このチェックポイントは、元に戻せる判断を軌道修正する機会であり、ビルドを妨げるゲートではありません。

README の引き継ぎプロンプト

複数スライスに分かれた仕様の README には、冒頭近くに「次のエージェントへのプロンプト」を必ず設けてください。将来のエージェントが機能の作業を再開するときに読むプロンプトとして、二人称で記述してください。README は、ライブの引き継ぎ状態であることを説明するだけでは不十分です。このセクション自体で、次のエージェントに次の作業を直接指示する必要があります。以下を含めてください。

• 現在の状況と最終更新日。
• 次に着手する箇所を正確に示すこと。
• 対応中のブロッカーや警告。
• 各項目の担当スライスを示した、全体の TODO チェックリスト。
• 作業を終える前にこのセクションを更新するよう、次のエージェントに直接指示すること。

目的は、新しいエージェントがチャットを読まずに README を開くだけで、次に何をすればよいか分かるようにすることです。

完了

新しいエージェントが会話の内容を知らなくてもスライス 1 から開始でき、人間が長文を読み解かずにロードマップを確認できるようになったら、機能計画は完了です。

すべてのスライスをリリースしたら、close-spec で計画を specs/done/ にアーカイブし、ビルドの手順書から、長期的に参照できる根拠の記録へと書き換えます。