spec-writing

仕様書の作成

概要

自然言語による機能の説明から、明確で完全かつテスト可能な仕様書を作成します。仕様書ではユーザー価値とビジネスニーズに焦点を当て、実装の詳細は避けます。

使用する場面

• 新しい機能仕様書を作成する
• 既存の仕様書を改善する
• ユーザーストーリーと受け入れ基準を作成する
• 成功基準を定義する

使用しない場面

• 実装タスクを生成する場合は、task-planning を使用します

基本原則

実装の詳細ではなく、ユーザー価値とビジネスニーズに焦点を当てます。厳密に必要な場合を除き、要件の定義に技術的な選択肢を指定しないでください。すべての要件が測定可能な基準でテストおよび検証できるようにします。確認が必要な箇所を示すマーカーは最小限にし、業界標準に基づいて妥当な仮定を置き、その内容を明記してください。

仕様書の構成

必須セクション

1. 概要／背景：どのような問題を解決しますか？
2. ユーザーシナリオ：誰がどのように使いますか？
3. 機能要件：何を実現する必要がありますか？
4. 成功基準：どのように動作を確認しますか？

任意のセクション

• 成功基準（パフォーマンスやセキュリティが重要な場合）
• エッジケース（特別な処理が必要な場合）
• 依存関係（外部システムが関わる場合）
• 仮定（情報が不完全な状態で判断した場合）

参照：詳細なテンプレートとガイドラインについては、modules/specification-structure.md をご覧ください。

品質チェックリスト

• 実装の詳細が含まれていない
• 要件がテスト可能で、曖昧さがない
• 成功基準が測定可能である
• ユーザーシナリオが主要なフローを網羅している
• エッジケースが特定されている
• スコープが明確に定められている

成功基準のクイックリファレンス

良い例（ユーザー重視、測定可能、技術に依存しない）

• 「ユーザーが3分以内にチェックアウトを完了できる」
• 「システムが同時に10,000人のユーザーをサポートする」
• 「検索の95%で1秒以内に結果が返る」

悪い例（実装重視、内部指標）

• 「API の応答時間が200ms未満」→「ページが2秒以内に読み込まれる」とします
• 「Redis キャッシュのヒット率が80%を超える」→「頻繁にアクセスされるデータが、体感できる遅延なく読み込まれる」とします
• 「React コンポーネントが効率よくレンダリングされる」→「目に見えるフレーム落ちなく UI が更新される」とします

参照：詳しい例と変換手順については、modules/success-criteria-patterns.md をご覧ください。

関連スキル

• speckit-orchestrator：ワークフローの調整
• task-planning：仕様書をタスクに変換

トラブルシューティング

よくある問題

仕様が曖昧すぎる場合は、success-criteria-patterns モジュールを使用して測定可能な成果を定義してください。実装の詳細が 仕様に入り込んでいる場合は、「基本原則」に照らして見直し、 ユーザーの行動に焦点を当てるように修正してください。

完了基準

• 仕様書に4つの必須セクション（概要／背景、 ユーザーシナリオ、機能要件、成功基準）がすべて含まれている
• すべての成功基準がユーザー重視かつ測定可能である（例：「ユーザーが 3分以内にチェックアウトを完了できる」）。実装指標 （例：「API の応答時間が200ms未満」）ではない
• 品質チェックリストを満たしている：実装の詳細がなく、 要件に曖昧さがなく、エッジケースが特定され、スコープが定められている
• 仕様書で厳密に必要な制約として明示されていない限り、 要件に技術的な選択肢が含まれていない
• 各機能要件に、システムの外部から検証できる テスト可能な受け入れ基準が少なくとも1つある