write-tech-spec

write-tech-spec

Warp の重要な機能について、TECH.md 仕様書を作成します。

概要

技術仕様書では、プロダクトの意図を既存のコードベースに適合する実装計画へ落とし込み、アーキテクチャ上の選択を文書化して、エージェントが作業を進めやすくし、レビュアーが評価しやすくします。

仕様書は specs/<id>/TECH.md に作成します。<id> は次のいずれかです。

• Linear のチケット番号（例：specs/APP-1234/TECH.md）
• gh- を接頭辞に付けた GitHub Issue の ID（例：specs/gh-4567/TECH.md）
• 短いケバブケースの機能名（例：specs/vertical-tabs-hover-sidecar/TECH.md）

同じ機能の PRODUCT.md がある場合は、そちらで使用されている ID に合わせます。specs/ の直下には、ID を名前とするディレクトリのみを置きます。

チケットや Issue の参照は任意です。ユーザーが Linear のチケットまたは GitHub Issue を持っている場合は、その ID を使用します。ない場合は、ディレクトリ名に使用する機能名を尋ねます。ユーザーから明示的に依頼された場合に限り、新しい Linear チケットまたは GitHub Issue を作成します。その場合は、それぞれ Linear MCP ツールまたは gh CLI を使用します（チーム、ラベル、リポジトリが不明な場合は ask_user_question を使用します）。

使用する場面

実装が複数のモジュールにまたがる場合、重要なアーキテクチャ上のトレードオフがある場合、またはコードの実装前や実装と並行して計画を確認できるとレビュアーに役立つ場合に、このスキルを使用します。UI のみの変更や単純な修正では、技術仕様書は不要なことが多いです。

技術計画の前提となる振る舞いについて合意できるよう、まず PRODUCT.md を用意することをおすすめします。実装の不確実性がまだ高すぎる場合は、まず E2E プロトタイプを作成し、そこから得られた知見をもとに技術仕様書を作成します。

作成前の調査

草案を作成する前に、プロダクト仕様書（ある場合）を読み、関連コードを調査して、主要なファイル、型、データフロー、所有権の境界を特定します。コードを直接調査できる場合は、現在のアーキテクチャを推測しないでください。 仕様書で関連するコードの箇所を参照する場合は、将来の読者が調査時点の正確なコードを確認できるよう、コミットに固定した参照を優先します。調査した各リポジトリについて現在のコミット SHA を記録します（例：git rev-parse HEAD）。可能な場合は、ファイルへの参照を、対応する GitHub の blob/<sha>/...#Lx-Ly URL への Markdown リンクにします。仕様書内でパスを読みやすく保つため、リンクテキストを使用します。

構成

必須セクション：

1. コンテキスト — 何を構築するのか、変更対象の領域で現在のシステムがどのように動作するのか、関連性の高いファイルと行番号を示します。「問題」「現在の状態」「関連コード」を、根拠のある1つのセクションにまとめます。参照例：

   • app/src/workspace/mod.rs:42 @ <commit-sha> — ユーザーフローのエントリーポイント
   • app/src/workspace/workspace.rs (120-220) @ <commit-sha> — 変更される可能性が高い状態とイベント処理 ユーザーから見える動作を言い換えて繰り返すのではなく、PRODUCT.mdを参照してください。

2. 変更案 — 実装計画です。変更するモジュール、新たに導入する型／API／状態、データフロー、所有権の境界、設計が既存のパターンにどのように沿うかを示します。妥当な選択肢が複数ある場合は、トレードオフを明記してください。

3. テストと検証 — 実装がプロダクトの動作に照らしてどのように検証されるかを示します。この機能が動作することの証明に関するすべてを扱います。単体テスト、統合テスト、手動の手順、スクリーンショット、動画、その他の検証を含みます。内容を言い換えるのではなく、PRODUCT.mdにある番号付きの動作不変条件を直接参照してください。重要な不変条件はそれぞれ、具体的なテストまたは検証手順に対応させてください。検証はこのセクションで扱います。PRODUCT.mdにValidationセクションがないのは意図的です。

4. 並列化 — 並列サブエージェント（run_agents経由で起動）が実際に全体の所要時間を短縮するか、作業を分離できるかを積極的に評価します。run_agentsが利用できない場合は、このセクションを省略します。仕様でサブエージェントの使用を提案する場合は、提案するエージェントごとに次の内容を含めてください。

   • 短い名前／役割と、担当するサブタスク。
   • 実行モード（localまたはremote）と、その理由を1行で説明します。
   • ローカルエージェントの場合：並列エージェントが同じチェックアウトやファイルで競合しないように、使用する作業ディレクトリまたはGitワークツリー。
   • リモートエージェントの場合：使用する環境、またはエージェントが空の環境で実行されることを明記します。
   • ブランチとPRの方針：各エージェントが作業するブランチ、各エージェントが使用するワークツリーパス、成果物の取り込み方法（エージェントごとに1つのPRにするか、1つの統合PRにするかなど）。
   • 調整の境界：各エージェントが担当するファイル／サービスと、兄弟エージェントとの同期方法（メッセージ、マージポイント、検証の担当など）。

   並列で実行できる手順と、順次実行が必要な手順を区別してください。依存関係が複雑な場合は、短いMermaid図（graph TDまたはflowchart LR）を使い、作業の分岐点と合流点がひと目で分かるようにすることを検討してください。

   並列化を提案しない場合は、その判断が妥当である理由（タスクが小さい、サブタスクの結び付きが強いなど）を簡潔に記してください。レビュー担当者がその判断に異議を唱えられるようにします。

   作業ツリー、ブランチ名、実行モードには、曖昧さを残さず具体的なデフォルトを提示してください。

任意セクション — 有益な情報を加える場合にのみ含めます。内容がない場合は見出しごと省略し、「なし」をプレースホルダーとして記述しないでください。

• エンドツーエンドのフロー — システム内の経路をたどることで、「変更案」の箇条書きだけでは得られない情報が分かる場合にのみ含めます。
• 図 — 設計を文章より速く理解できる場合（データフロー、状態遷移、レイヤーをまたぐシーケンス）のみMermaid図を含めます。装飾的な図ではなく、焦点を絞った図を1つまたは2つ使ってください。
• リスクと軽減策 — 失敗につながる実際の要因、リグレッション、移行に関する懸念、またはリリース時の危険について説明する価値がある場合に含めます。
• フォローアップ — 先送りされたクリーンアップや、明記すべき今後の作業がある場合に含めます。

長さの目安

機能に合わせて仕様書の分量を調整します。

• 明確なアプローチがある単一ファイルの変更：技術仕様書は省略するか、約40行以内にします。
• ある程度の曖昧さがある複数モジュールの変更：約80～150行を目安にします。
• 大規模で広範囲に及ぶ変更や、アーキテクチャ上の新規性がある変更：各セクションに意義があるなら、長くてもかまいません。

コンテキストと提案する変更で、同じファイルや状態を異なる視点から説明することになる場合は、まとめてください。

作成時の指針

• 実際のコードベースの構造とパターンに基づいて計画を立てます。
• リポジトリにアクセス可能なリモートがある場合は、重要なコード参照にコミット SHA を付け、該当する GitHub の行へのリンクを設定します。
• 一般的なアーキテクチャの説明より、具体的な実装ガイダンスを優先します。
• 動作の説明を繰り返すのではなく、PRODUCT.md を参照します。
• 各セクションに意義を持たせます。他のセクションと重複するものや、定型文だけのセクションは省略します。

仕様書を最新の状態に保つ

承認済みの仕様書は、実装と同じ PR でリリースされる場合があります。モジュールの境界、実装の順序、リスク、検証戦略、またはロールアウトの前提が変わった場合は、同じ PR で TECH.md を更新します。リポジトリにチェックインされた仕様書には、実際にリリースされる実装を記載してください。

大規模な機能では、実装担当者が具体的な決定事項をまとめた DECISIONS.md ファイルを任意で作成してもかまいません。今後のエージェントに役立つ場合は作成し、そうでなければ省略してください。

関連スキル

• implement-specs
• write-product-spec
• spec-driven-implementation