marcioaltoe/write-techspec

テクニカルスペックの作成 (Write TechSpec)

docs/specs/<slug>/_techspec.md を生成します。これはスペックの要件に対する技術的な回答です。PRDが「何を」「なぜ」を定義したのに対し、このドキュメントは「どのように」「どこで」「何を使って」を決定します。そして、そのビルド順序は 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 を記述します。これには、フロントマター（spec、status: active、surfaces、バグ修正の場合は type: fix、リファクタリングの場合は type: refactor）、問題ステートメント、プロジェクト制約、目標、コア機能、非目標、および ## Decisions の下にある明確化記録が含まれます。これはエンジニアリングフレームで、各項目数行程度です。記録は write-prd の明確化ガイドに従います。1行につき - YYYY-MM-DD: <質問> — <回答> の形式で、担当者が回答した質問ごとに1行、または「自律ルート：担当者なし。決定は <ソース> から取得。」という形式で、担当者がいない場合の著者の決定のソースを指定します。これは write-tasks、qa-gate、archive-spec が単一のアーティファクト契約を維持するために存在し、製品ドキュメントではありません。「リファクタリング」が製品の動作を変更することが判明した場合は、停止して write-prd にルーティングします。

基本ルール

• 先に読む: CONTEXT.md（すべてのインターフェースおよびコンポーネント名で用語集の語彙を使用）、既存の docs/adr/（以前の決定を尊重するか、明示的に異議を唱える。黙って矛盾してはいけない）、および完全なPRD。
• 決定してから、書く。 明確化の間に決定を確定し、重要なものをADRとして記録し、完成したドキュメントを書く。アウトラインベースの承認ラウンドは不要。
• YAGNI。 機能が既存モジュールへの追加として収まる場合、新しいパッケージ、レイヤー、ディレクトリを提案しない。新しい構造要素はすべて、明示された代替案に対してその位置を正当化する必要がある。
• 参照、重複しない。 PRDセクションを名前で参照する（「ユーザーストーリー3〜5をカバー」）。ここでビジネスコンテキストを繰り返すと、2つのコピーが生じて乖離する。
• 所有ソースパスを使用する。 採用されたすべてのソースを、所有スペック内の採用後パスでリンクする。宛先は _techspec.md からの相対パスとする。参照インデックスに保持されている採用前パスでは決してリンクしない。二次スペックは主要所有者のコピーをリンクし、何も採用しない。 所有者のアーカイブはアーカイブ再リンクを実行する。そのコピーを docs/references/ に昇格させ、二次スペックのリンクを書き換える。これにより、ソースは1つの所有者を持ち、二次スペックはコピーを必要としない（ADR-0260、ADR-0083）。

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

スペックは、コンテキストが類似または補完的ないくつかのバックログエントリと発見事項を採用することができる。ソースごとに1つのスペックは必須でも推奨でもない。スペックを作成する前に、オープンなバックログエントリと未解決の発見事項の中から、コンテキストを共有するソースを探す。スコープが4つの実装タスクとそのQAゲートに収まる場合にのみグループ化する。その範囲を超えた場合は、スコープを分割し、各ソースに1つの所有スペックを与える。

新しい発見事項やバックログエントリを作成する前に、適合するものを拡張する：オープンなバックログエントリをその場で改訂するか、未解決の発見事項に日付の入った補遺を付ける。

roundfix spec judge が提案ペアを出力した場合、各提案ペアに対して、範囲内でオープンソースを採用するか、またはなぜそれを分離したままにするかをレポートに記載して回答する。提案がゲートになることは決してなく、提案がないことは何も適合しないことを意味しない。それでも、コンテキストを共有するオープンソースを検査する。発見事項やバックログエントリに応答するリファクタリングやバグ修正は、最小限のPRDを作成する前に、コンテキストを共有する他のものを探す。

プロセス

1. アーキテクチャの探索

機能が存在するコードをマッピングする：拡張するモジュール、アタッチできる継ぎ目、同じ種類の作業のための既存のパターン（既存のアダプター、既存のジョブランナー）、および利用可能なテストインフラストラクチャ。新しい継ぎ目よりも既存の継ぎ目を優先する。理想的な新しい継ぎ目の数はゼロである。探索は、利用可能な場合はサブエージェントに委任する。スペックには結論が必要であり、ファイルダンプではない。

探索中にリポジトリのセマンティックガイドから有効なプロジェクト制約を解決する。

• docs/agents/domain.md は識別子ガイダンスを所有し、アクティブなADR発見をルーティングする。
• docs/agents/backend.md は認証とHTTPポリシーを所有する。
• そのガイドがないリポジトリは、そのサーフェスのポリシーを所有するガイドを引用する。
• docs/agents/agent-instructions.md は、ツール権限を含む普遍的な規範条項を所有する。
• docs/agents/spec-routing.md はスペックワークフロー契約を所有する。

存在するすべてのパスを読み、そのリンクをたどって有効な決定値に到達する。推奨されるデフォルトを推測したり、欠落しているガイドを承認として扱ったりしてはならない。完成したスナップショットは、識別子戦略、認証とHTTP、アクティブなADR義務、ツール権限を、該当するまたは該当しないものとして理由とともに分類し、各行に運用上の docs/agents/ ソースパスを引用する必要がある。

2. 技術的な決定の明確化

PRDステージと同じプロトコル — メッセージごとに1つの質問、推奨されるデフォルトと1行の根拠を持つ多肢選択 — ただし、スコープはどのように/どこで/何を使用するかに限定される：アーキテクチャの配置、データモデル、API形状、移行戦略、テストの継ぎ目、パフォーマンスとセキュリティの制約。探索で解決できなかったことだけを尋ねる。

3. ADRの記録

重要な技術的決定（元に戻すのが難しい + コンテキストなしでは驚くべき + 実際のトレードオフがある）はすべて docs/adr/NNNN-slug.md となり、PRDステージで使用されたのと同じ番号付けを継続する — 1つの決定ログが機能全体にわたる。各1〜3文。

4. 執筆

_techspec.md を references/techspec-template.md のテンプレートから作成する。下流で最も重要なのは次の2つのセクションである。

• すべてのPRD目標とユーザーストーリーは、名前付きの技術コンポーネントにマッピングされる。 マッピングされていないストーリーは設計上の穴である。今すぐ見つける。タスク実行中に見つけてはならない。
• ビルド順序 — 番号付きのステップ。最初のステップ以降のすべてのステップは、どの以前のステップに依存するかを示す。write-tasks はこれからタスクグラフのエッジを導出する。

APIコントラクトは、番号付きのAPIコントラクト項目として、または単一のエントリ None. とその理由を続けて記述する。番号付きの各コントラクトは、下流のタスク参照でその名前と番号によってアドレス可能でなければならない。

用語集の用語

TechSpecが用語集で定義されていない概念を命名した場合、ドメインモデリングをアクティブにし、用語を明確にし、PRDまたはTechSpecの用語集セクションで宣言する。

具体的なコントラクト

具体的なコントラクトガイドを、クレームが決定レコードに動作を帰属させる場合、またはTechSpecがコマンドサーフェスを変更する場合に使用する。これは、クレームレシート、サーフェストランスクリプトブロック、QAゲートで使用されるマッチング規則、コード署名インターフェース、および番号付き不変条件を定義する。

Project Constraints は本文の内容であり、フロントマターではない。設計が保護されたツール設定、スクリプト、無視ファイル、プラグイン宣言、またはバージョンピンの作成、編集、名前変更、移動、または削除を提案する場合、メンテナーから明示的なメンテナー承認が得られるまで停止する。その承認と正確な境界ファイルをツール権限の行に記録する。一般的な実装リクエスト、セットアップの完了、沈黙、または境界ファイルのない承認は、変更を許可しない。運用記録は <spec-root>/<slug>/_authorization.md に属する。proposed レコードまたは許可日がないレコードは何も許可しないため、運用許可が存在するまで保護されたツール作業を分解に進めてはならない。新しいまたは拡張された許可は、消費するスカッシュデリバリーの前にターゲットの祖先に配置されなければならない。許可または修正は、それが許可する変更の外部に保持する。

インターフェーススケッチは各20行未満に保つ。形状を文書化し、実装を文書化しない。1,500〜2,500語を目標とする。誰も読まないスペックは誰も保護しない。

配信キューが配信するすべてのスペックには、保護されたツールの有無にかかわらず、承認された _authorization.md が添付される。レコードの operations リストは implement、commit、push、pull_request、merge を命名する。統治パスを変更しないスペックは paths: [] を記録する。

スペックが主張する内容の証明

TechSpecは3つの証明を名前付きの場所に記録し、roundfix spec check は欠落した場所をアクティブなすべてのスペックのギャップとして報告する。チェックは構造のみを読み取る。証明が正しいかどうかは読者に委ねられる。

• 不在の証拠。 TechSpecが新しいと宣言する各コンポーネントについて、## Absence Evidence の下に、それを欠如していることを証明した検索を番号付き項目として記録する：コンポーネント、バッククォート内の検索を含む command:、およびそれが見つけたものを含む result:。TechSpecが引用するファイル内の動作を検索する。名前のみを検索しない。新しいものが何もない場合は、None. と理由を続けて記述する。SC-ABSENCE-UNPROVEN は、宣言の欠落、またはコマンドや結果のない項目を報告する。
• 拒否された代替案。 ## ADR Alternatives の下に、アクティブなADR義務行がリストする各ADRに対して、- ADR-NNNN: <関係> を1行記述する：設計がそのADRによって拒否された代替案にどのように関連するか。設計が拒否された代替案を採用する場合、その旨を述べ、ADRを supersede または修正する。SC-ADR-ALTERNATIVES-UNRELATED は、その行がないリストされたADRを報告する。
• カバレッジクロスリード。 write-tasks の前に、各PRDユーザーストーリー、コア機能、成功指標を、カバレッジマップが命名するコンポーネントに対して読み取る。Deviations from the PRD: という行をカバレッジマップに追加し、その後に None. またはTechSpecが別の形状で提供するPRDユニットごとに1つの箇条書きを、ユニット名と理由を指定して続ける。SC-COVERAGE-UNREAD は、行の欠落、またはPRDユニットを命名しない逸脱を報告する。

5. 報告

報告する前に、完成したアーティファクトとこのスキルによって作成された最小限のPRDを再読する。以下の場合を除き、完了を報告したり、write-tasks を推奨してはならない：各新しいアーティファクトに Project Constraints がある。4つの行すべてが該当するまたは該当しないと理由とともに述べている。すべての行が運用上の docs/agents/ ソースを引用している。保護されたツールの変更が、明示的なメンテナー承認と境界ファイルを記録している。承認をフロントマターから除外する。

次に、アーティファクトを生成したステージに対してチェッカーを実行する。

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

エラーレベルの発見またはチェッカー実行の失敗は、報告をブロックする。発見によって指名されたPRDまたはTechSpecを修正し、コマンドを再実行する。いずれかが存続している間は、完了を報告したり write-tasks を推奨したりしてはならない。

クリーンなTechSpecステージの結果は、完全なスペックカバレッジではない。このステージは、タスクグラフADR会計、タスクカバレッジ、コンテキスト参照、検証独立性、要件の矛盾、リハーサル宣言、コミット依存の変更パス範囲、まだ機械化されていないルール、製品目標がユーザー到達可能なサーフェスを通じて機能するかどうかを決定しない。タグオーサリングステージ、完全なスコープ外スイープ、およびQAはそれらのクラスを保持する。チェッカーの名前付きスキップ検出器を、クリーンな発見としてではなく、省略として扱う。

ファイルパス、作成されたADR、まだ未解決の決定、および次のステップである write-tasks を返信する。

配信タイプとリリース決定

修正ルートの最小限のPRDは、その配信タイプを type で宣言する：バグ修正の場合は fix、リファクタリングの場合は refactor。アーカイブレコードと配信キューのプルリクエストタイトルはそれを保持する。

メンテナーがスペックでのリリースを要求した場合、構造化された質問ツールを使用してリリース質問を行い、リリース上限（patch、minor、major）とリリースが変更する可能性のあるバージョン専用パスを含める。次に、_authorization.md の operations に release、release_ceiling、release_paths を記録し、その回答を本文に逐語的に引用する。そのリクエストがない限り、決して release を追加しない。リリースされたコードを変更する refactor 配信は、リリース計画に手動分類を要求させる。

リリース質問は計画時に尋ねる。マージ後には決して尋ねない。

スペックイベントアナウンスメント

スペックイベントアナウンスメントは、ユーザー自身の指示（グローバルまたはこのリポジトリ用）がその宛先と形式を定義している場合にのみ存在する。このスキルは決して名前を付けない。メッセージ、ハンドオフ、またはアナウンスメントを要求するスペックアーティファクトは何も定義しない。ユーザー自身の指示が何も定義していない場合、レポート行なしでステップをスキップする。ユーザー自身の指示が定義している場合、スペックからそれを作成する：プロジェクト、スペック番号と完全なスラッグ、タイトル、イベント、イベント日付、開始日、提案された期限またはなし、スペックパス、およびそれらの指示が追加するフィールド。それらが命名する宛先を通じて送信し、返信を待たず、それが続くステップをブロックしたり失敗させたりしてはならない。送信できない場合、レポートはイベントと理由を命名し、作成されたアナウンスメントを保持する。Daemon割り当て実行内のエージェントは決してアナウンスしない。提案された期限は、クライアント、法律、または測定からの実際の期限であり、PRDが ## Decisions にそのソースとともに記録する。ユーザーが承認するまで提案のままである。

new を一度だけアナウンスする。

…

[翻訳用に切り詰められました]