spec-driven-implementation

spec-driven-implementation

Warp の大規模な機能向けに、仕様を優先するワークフローを進めます。

概要

仕様書を作成することで、実装の品質向上、曖昧さの軽減、レビューの容易化につながる重要な機能に、このスキルを使用してください。現実的に判断してください。すべての変更に仕様書が必要なわけではありません。

仕様書は通常、次の場所に保存します。

• specs/<linear-ticket-number>/PRODUCT.md
• specs/<linear-ticket-number>/TECH.md

例：

• specs/APP-1234/PRODUCT.md
• specs/APP-1234/TECH.md

specs/ の直下には、チケット名のディレクトリだけを置いてください。エンジニア名や機能名のディレクトリを作成しないでください。

関連する Linear の課題がまだ存在しない場合は、仕様書を作成する前に課題を作成してください。Linear MCP ツールを直接使用します。

• list_teams で適切なチームを確認します
• list_issue_labels で想定されるラベルやタグを確認します
• save_issue で適切なチームとラベルを指定して課題を作成します

依頼内容や周辺のコンテキストから正しいチームやラベルが明確でない場合は、推測せずに ask_user_question で確認してください。

これらの仕様書は、手作業ではなくエージェントが大部分を作成し、レビューやコードとの整合性維持ができるよう、ソース管理にチェックインしてください。

仕様書が必要な場合

次のような大規模な変更では、仕様書の作成を強く推奨します。

• プロダクトやアーキテクチャに曖昧さがある
• 想定される実装規模が約 1k+ LOC である
• スタックの広範囲または複数の層にまたがる変更である
• リグレッションが高くつくリスクのある動作変更である
• 入力が明確になることで、エージェントの品質が大きく向上する作業である

次のような場合は、仕様書が不要なことも多くあります。

• 小規模で局所的なバグ修正
• 単純なリファクタリング
• 曖昧さがほとんどない、限定的な UI 調整

UI のみを変更する場合は、プロダクト仕様書が役立つことが多い一方で、技術仕様書は不要な場合があります。

ワークフロー

1. 機能に仕様書が必要か判断する

機能の規模、曖昧さ、リスクを評価します。仕様書を作成しても実行やレビューが大きく改善しない場合は、作成を省略して検証に注力してください。

2. まずプロダクト仕様書を作成する

実装前に、ユーザー向けの望ましい動作を説明する PRODUCT.md を作成します。

作成には write-product-spec スキルを使用してください。プロダクト仕様書では、次の項目を定義します。

• 解決する問題
• 望ましいユーザー体験
• 不変条件とエッジケース
• 成功基準
• 動作の検証方法

機能に UI やインタラクションのデザインが含まれる場合は、Figma のモックがあれば共有を依頼してください。モックがない場合は、その旨をプロダクト仕様書に明記したうえで作業を進めてください。

Linear の課題がある場合は、仕様書からその課題を参照してください。仕様書は specs/<linear-ticket-number>/... に置くため、通常は簡単に参照できます。

3. 必要に応じて技術仕様書を作成する

大規模または曖昧な実装作業では、write-tech-spec スキルを使用してください。

次の場合は、技術仕様書の作成を推奨します。

• 実装が複数のサブシステムにまたがる
• アーキテクチャや拡張性が重要である
• 記録すべき重要なトレードオフがある
• レビュアーにとって、生のコードより実装計画のレビューのほうが有益である

e2e プロトタイプの後に技術仕様書を作成することで、より正確な実装計画になる場合は、その順序でも問題ありません。実装の詳細がまだ不確かな段階で、無理に技術仕様書を作成しないでください。

4. 承認済みの仕様書を実装する

仕様書の承認後、implement-specs スキルを使用して、承認済みの PRODUCT.md と TECH.md に基づいて実装します。

プロダクト仕様書や技術仕様書と同じ PR に実装を含められる場合もよくあります。エンジニアが反復して作業を進める間、PRODUCT.md、TECH.md、コードの変更、テストを同じ PR に含め、実際にリリースされる機能を反映したレビューができるようにしてください。

大規模な機能では、実装担当者は必要に応じて、次のドキュメントを追加できます。

• PROJECT_LOG.md：調査した方法、チェックポイント、現在の実装状況を記録します
• DECISIONS.md：設計や実装で決定した具体的なプロダクト上および技術上の事項を記録します

これらは任意の補助資料であり、必須の成果物ではありません。

5. 実装中も仕様を最新の状態に保つ

実装が仕様から変わった場合は、仕様を古いままにせず更新してください。

次の場合は PRODUCT.md を更新します。

• ユーザー向けの動作が変わる
• 成功基準が変わる
• UX の詳細やエッジケースが変わる

次の場合は TECH.md を更新します。

• 実装アプローチが変わる
• アーキテクチャ上の境界が変わる
• リスク、依存関係、またはリリースの詳細が変わる
• テストまたは検証計画が変わる

チェックイン済みの仕様には、最初の意図だけでなく、実際にリリースされる機能を記述してください。可能な限り、関連するコード変更と同じ PR で仕様も更新してください。

6. 仕様に照らして動作を検証する

作業を完了とみなす前に、検証内容が仕様に対応していることを確認してください。プロダクトの動作を直接検証するテストや成果物を優先してください。

• リポジトリ固有のテスト規約に沿ったユニットテストと回帰テスト
• 重要なユーザーフローの結合テスト
• 適切な場合は、Loom のウォークスルーまたは同等の機能デモ
• UI が中心の作業で有用な場合は、スクリーンショットまたは動画

ベストプラクティス

• 何よりも実用性を重視してください。
• 儀式としてではなく、エージェントへの入力品質を高めるために仕様を作成してください。
• プロダクト仕様は動作を中心に記述し、実装の詳細は最小限にしてください。
• 技術仕様は実装を中心に記述し、現在のコードベースのパターンに基づいたものにしてください。
• 仕様で関連するコードの範囲を参照する場合は、可能であればファイル参照に確認したコミット SHA を含め、正確な GitHub の blob/<sha>/...#Lx-Ly 行へのリンクを設定してください。
• レビュー時間は仕様と動作の検証に使い、コードスタイルの細かな指摘に偏りすぎないようにしてください。

関連スキル

• implement-specs
• write-product-spec
• write-tech-spec