write-techspec

Write TechSpec

docs/specs/<slug>/_techspec.md を作成します。これは、仕様の要件に対する技術的な回答です。PRD では 何を、なぜ 作るのかを示しました。このドキュメントでは、どのように、どこで、何を使って 作るかを決定します。また、Build Order は write-tasks によってタスクグラフへ変換されるため、ここでの順序付けの質が、その後の実行の質を左右します。

前提条件 — 2 つの開始モード

$ARGUMENTS は仕様（スラッグまたはパス）を指定するか、リファクタリング／バグ修正について説明します。プロダクトの動作が変わるかどうかでモードを選択します。

• 機能開発（プロダクトの動作が変わる） — docs/specs/<slug>/_prd.md が存在している必要があります。存在しない場合は作業を中止し、ユーザーに write-prd を案内してください。プロダクトに関する判断には、まずプロダクトについての対話が必要です。PRD にここで扱うべき低レベルの技術的判断が含まれている場合は、黙って重複させるのではなく、その点を指摘事項として示し、移動を提案してください。
• リファクタリングまたはバグ修正（プロダクトの動作は変わらない） — このスキルがパイプラインの開始点となり、PRD のヒアリングは行われません。仕様フォルダーがまだ存在しない場合は、write-prd の採番ルールに従ってフォルダーを作成します（<spec-root>/NNNN-<kebab-slug>/。設定された Spec Root と、その解決済みアーカイブディレクトリの両方を調べ、最も大きい番号を使用します。組み込みの docs/specs ルートでは docs/history/specs/、それ以外では <spec-root>/_archived/ です）。そして、下流のスキルが解析する契約だけを含む最小限の _prd.md を作成します。契約には、frontmatter（spec、status: active、surfaces）、問題の説明、Project Constraints、目標、主な機能、対象外事項、## Decisions の Clarification Record が含まれます。各項目はエンジニアリングの観点で数行にまとめます。記録は write-prd のclarification guide に従い、誰かに回答してもらった質問ごとに - YYYY-MM-DD: <question> — <answer> を 1 行記載します。誰も参加していなかった場合は、執筆者の判断の根拠となった出典を明記して Autonomous route: no person present; decisions taken from <source>. と記載します。これは write-tasks、qa-gate、archive-spec で成果物の契約を統一するためのものであり、プロダクト文書ではありません。「リファクタリング」が実際にはプロダクトの動作を変えると判明した場合は、作業を中止して write-prd に進んでください。

基本ルール

• まず読む：CONTEXT.md（すべてのインターフェース名とコンポーネント名には、用語集の語彙を使用してください）、既存の docs/adr/（過去の判断に従うか、明示的に異議を唱えてください。黙って矛盾させてはいけません）、PRD 全文。
• 判断してから書く。 ヒアリング中に判断を固め、重要なものを ADR として記録してから、完成したドキュメントを書いてください。アウトラインの承認を求めるやり取りは行いません。
• YAGNI。 既存のモジュールへの追加で実現できる機能に対して、新しいパッケージ、レイヤー、ディレクトリを提案してはいけません。新たな構造要素を加える場合は、その必要性を明示した代替案と比較して説明してください。
• 重複させず、参照する。 PRD のセクション名で参照してください（「User Stories 3–5 をカバー」など）。ビジネス上の背景をここに繰り返すと、内容がずれていくコピーが 2 つできてしまいます。
• 所有者側のソースパスを使う。 採用したソースはすべて、参照インデックスに残す採用前のパスではなく、所有する Spec 内の採用後のパスをリンクしてください。リンク先は _techspec.md からの相対パスにします。二次 Spec は一次所有者のコピーをリンクし、自身では何も採用しません。所有者のアーカイブ処理では Archive Relink を行い、そのコピーを docs/references/ に移して、二次 Spec のリンクを書き換えます。これにより、ソースの所有者は 1 つに保たれ、二次 Spec にコピーを置く必要もありません（ADR-0260、ADR-0083）。

同じコンテキストを共有するソース

Spec では、コンテキストが似ている、または補完し合う複数の Backlog Entry と Finding を採用できます。ソースごとに Spec を作成する必要はなく、推奨もされません。Spec を新規作成する前に、コンテキストを共有するソースがないか、オープン中の Backlog Entry と未解決の Finding を確認してください。スコープが実装 Task 4 件とその QA ゲートに収まる場合に限り、まとめてください。その上限を超える場合はスコープを分割し、各ソースに担当する Spec を 1 つずつ割り当てます。

新しい Finding または Backlog Entry を作成する前に、内容が合致する既存項目を拡張してください。オープン中の Backlog Entry はその場で改訂し、未解決の Finding には日付入りの追記を加えます。

roundfix spec judge が推奨するペアを出力した場合は、上限の範囲内でオープン中のソースを採用するか、レポートで分けたままにする理由を述べて、推奨された各ペアに回答してください。推奨は必須ではありません。また、推奨がないからといって、合致するソースがないとは限りません。コンテキストを共有するオープン中のソースは、引き続き確認してください。Finding または Backlog Entry に対応するリファクタリングやバグ修正では、最小限の PRD を作成する前に、コンテキストを共有する他のソースも確認してください。

プロセス

1. アーキテクチャを調査する

機能を実装するコードを把握してください。拡張するモジュール、接続できるシーム、同種の作業に既存のパターン（既存のアダプター、既存のジョブランナーなど）、利用可能なテスト基盤を確認します。新たなシームを設けるより、既存のシームを優先してください。新たなシームの理想的な数はゼロです。サブエージェントを利用できる場合は、調査を委任してください。Spec に必要なのは結論であり、ファイルの羅列ではありません。

調査中に、リポジトリのセマンティックガイドから実際に適用されるプロジェクト制約を特定してください。

• docs/agents/domain.md は識別子に関する指針を定め、現在有効な ADR の調査先を示します。
• そのガイドがないリポジトリでは、対象領域のポリシーを定めるガイドを参照します。
• docs/agents/agent-instructions.md は、ツールの権限を含む、普遍的に適用される規範条項を定めます。
• docs/agents/spec-routing.md は Spec ワークフローの契約を定めます。

存在するすべてのパスを読み、そのリンクをたどって、実際に適用される決定事項を確認してください。推奨されるデフォルトを推測したり、ガイドがないことを許可と見なしたりしてはいけません。完成したスナップショットでは、識別子戦略、認証と HTTP、現在有効な ADR の要件、ツールの権限について、それぞれ該当する理由を示して、適用対象か非該当かを分類してください。また、各行について、実際に適用される docs/agents/ のソースパスを記載してください。

2. 技術的な決定事項を明確にする

PRD 段階と同じプロトコル、つまり 1 メッセージにつき質問 1 つ、デフォルト案と一行の理由を添えた選択式 を使います。ただし、対象はどのように、どこに、どれを選ぶかです。アーキテクチャ上の配置、データモデル、API の形、移行戦略、テストシーム、パフォーマンスとセキュリティの制約を扱います。調査で解決できなかった事項だけを質問してください。

3. ADR を記録する

重要な技術的決定（覆すのが難しく、背景がなければ意外で、実際にトレードオフがあるもの）はそれぞれ、docs/adr/NNNN-slug.md に記録してください。番号は PRD 段階で使用したものと同じ連番を続けます。機能全体で決定ログを 1 つ共有します。各項目は 1〜3 文にしてください。

4. 作成する

テンプレート references/techspec-template.md を使って _techspec.md を作成してください。後続工程への影響が特に大きいセクションは 2 つです。

• すべての PRD の目標とユーザーストーリーを、名前付きの技術コンポーネントに対応付けてください。 対応付けられていないストーリーは設計上の穴です。タスク実行中ではなく、今の時点で見つけてください。
• ビルド順序 — 番号付きの手順を記載し、最初の手順を除く各手順に、依存する前の手順を明記してください。write-tasks はここからタスクグラフのエッジを導出します。

API Contracts は、番号付きの API Contract 項目として記載するか、該当項目がない理由に続けて、単一の項目 None. として記載してください。後続の Task References で参照できるよう、各番号付き契約には名前と番号を付けてください。

用語集

TechSpec で、用語集に定義されていない概念を使う場合は、ドメインモデリングを開始して用語を明確にし、PRD または TechSpec の用語集セクションに記載してください。

具体的な契約

主張が決定記録に基づく動作を示す場合、または TechSpec によってコマンドの仕様が変わる場合は、concrete-contracts ガイドを使用してください。ここでは、Claim Receipt、Surface Transcript ブロック、QA ゲートで使用する照合規約、コードシグネチャのインターフェイス、番号付き不変条件を定義します。

Project Constraints は本文の内容であり、フロントマターには記載しません。設計で、保護対象のツール設定、スクリプト、無視ファイル、プラグイン宣言、バージョン固定の作成、編集、名前変更、移動、削除を提案する場合は、メンテナーから明示的な承認を得るまで停止してください。その承認と対象を限定した正確なファイル一覧を、Tooling authority の行に記録してください。一般的な実装依頼、セットアップの完了、返答がないこと、または対象ファイルを限定していない承認は、変更を許可するものではありません。正式な記録は<spec-root>/<slug>/_authorization.mdに置きます。proposed の記録や付与日がない記録は何も許可しないため、正式な許可が存在するまで、保護対象のツール作業を分解へ進めないでください。新しい許可または拡張された許可は、それを利用する squash デリバリーより前に、対象の祖先コミットに含める必要があります。許可対象の変更とは別に、許可または修正を行ってください。

インターフェイスのスケッチはそれぞれ20行未満にしてください。これらは実装ではなく、形状を記録するものです。目標は1,500～2,500語です。誰にも読まれない仕様は、誰も守りません。

Delivery Queue がデリバリーするすべての Spec には、保護対象のツールがあるかどうかにかかわらず、承認済みの_authorization.mdが必要です。この記録のoperationsリストには、implement、commit、push、pull_request、mergeを指定します。Governed Path を変更しない Spec では、paths: []を記録します。

Spec の主張を裏付ける証拠

TechSpec では、名前を付けた箇所に3種類の証拠を記録します。roundfix spec checkは、すべてのアクティブな Spec について、記載箇所の欠落をギャップとして報告します。このチェックが読み取るのは構造だけです。証拠が正しいかどうかは、読み手が判断します。

• 不在の証拠。TechSpec が新規と宣言するコンポーネントごとに、不在を証明した検索を、番号付き項目として## Absence Evidenceの下に記録します。項目には、コンポーネント、バッククォートで囲んだ検索内容を含むcommand:、検索で見つかった内容を含むresult:を記載します。その動作について TechSpec が引用するファイルを検索し、名前だけを検索しないでください。新規項目がない場合は、理由に続けてNone.と記載します。SC-ABSENCE-UNPROVENは、宣言の欠落、またはcommandかresultがない項目を報告します。
• 却下された代替案。## ADR Alternativesの下に、Active ADR obligations の各行に記載されているADRごとに、- ADR-NNNN: <relation>という1行を記載します。そこでは、ADR が却下した代替案と設計がどのように関連するかを説明します。設計で却下された代替案を採用する場合は、その旨を明記し、ADR を置き換えるか修正してください。SC-ADR-ALTERNATIVES-UNRELATEDは、一覧にあるADRに該当する行がない場合に報告します。
• Coverage Cross-Read。write-tasksの前に、PRD の各ユーザーストーリー、Core Feature、Success Metric を、Coverage Map が指定するコンポーネントと照らし合わせて確認します。Coverage Map にDeviations from the PRD:という行を追加し、その後にNone.を記載するか、TechSpec が別の形で提供するPRD項目ごとに1つの箇条書きを記載します。箇条書きには、その項目と理由を明記してください。SC-COVERAGE-UNREADは、行の欠落、またはPRD項目を特定していない逸脱を報告します。

5. 報告

報告する前に、完成した成果物と、このスキルで作成した最小限の PRD を読み直してください。新しい成果物ごとに Project Constraints があり、4 行すべてに適用対象か対象外かとその理由が記載され、各行が有効な docs/agents/ の出典を引用し、保護対象のツール設定を変更した場合は、メンテナーの明示的な許可と対象ファイルの範囲が記録されていない限り、完了を報告したり write-tasks を推奨したりしてはいけません。許可をフロントマターに記載しないでください。

次に、成果物を生成したステージに対してチェッカーを実行します。

roundfix spec check <slug> --stage techspec --run-verification

エラーレベルの指摘、またはチェッカーの実行失敗がある場合、報告はできません。指摘で指定された PRD または TechSpec を修正し、コマンドを再実行してください。いずれかの状態が残っている間は、完了を報告したり write-tasks を推奨したりしないでください。

TechSpec ステージでチェックに合格しても、Spec 全体をカバーしたことにはなりません。このステージでは、Task Graph の ADR との対応付け、タスクの網羅性、コンテキストの参照、Verification の独立性、要件の矛盾、リハーサルの宣言、コミットに依存する変更パスの範囲、まだ機械的に判定できないルール、またはユーザーが到達可能な経路で製品の目標が実現されるかどうかは判断しません。これらの項目は、Task 作成ステージ、スコープ指定なしの全体チェック、および QA で引き続き確認します。チェッカーがスキップ対象として挙げた検出項目は、指摘なしではなく未実施として扱ってください。

ファイルパス、作成した ADR、未決定の事項、次のステップである write-tasks を回答してください。

助言的な判断

roundfix spec check <slug> --stage techspec --run-verification が問題なしとなった後、報告の前に roundfix spec judge <slug> --stage techspec を実行してください。指摘された判断事項にはそれぞれ、成果物を修正してチェッカーを再実行するか、記述を維持する場合は報告内で維持する理由を述べて回答してください。judge は助言的なものであり、決してゲートにはなりません。スキップという結果は失敗でも合格でもないため、スキップの理由を報告して続行してください。Jev キーを表示、保存、要求してはいけません。対象となるのは ROUNDFIX_OPENROUTER_JUDGE_API_KEY、ROUNDFIX_OPENROUTER_API_KEY、ROUNDFIX_TYPESAFE_API_KEY です。

アンチパターン

• PRD を参照する代わりに、ビジネス上の背景を言い直す。
• 仕様のない要件に対する抽象化など、根拠のない一般化。
• 実装へと発展してしまうインターフェースのスケッチ。
• 依存関係の記述がない Build Order。これでは write-tasks がグラフを推測することになります。
• 既存の ADR を、該当する ADR を明示して置き換えを提案せずに矛盾させる。

参照資料

• references/techspec-template.md — _techspec.md の完全なテンプレートです。ファイルを書く前に読んでください。