technical-spec-template

技術仕様書テンプレートスキル

エンジニニアが実際に読んでくれる技術仕様書を作成します。課題を明確に整理し、要件を曖昧さなく記述し、決定事項を明示し、トレードオフを文書化します。

必須の入力情報

提供されていない場合は、ユーザーに次の情報を尋ねてください。

• 機能またはシステムの説明（仕様書の対象）
• 関連する PRD または製品概要（入手可能な場合）
• エンジニアリングレビュー担当者（承認が必要な担当者）
• 既知の制約（技術的制限、セキュリティ要件、パフォーマンス目標）

技術仕様書を作成するタイミング

次の場合は技術仕様書を作成してください。

• 機能の実装に 2 つ以上のシステムの変更が必要な場合
• 重要なアーキテクチャ上の決定が必要な場合
• 実装に複数のエンジニアが携わる場合
• 機能にセキュリティ、プライバシー、またはコンプライアンス上の影響がある場合
• 見積もり工数が 5 ストーリーポイントを超える場合

些細なバグ修正や 1～2 時間で完了する変更では、仕様書の作成を省略してください。

---

技術仕様書の出力形式

技術仕様書 — [機能名]

作成者： [名前] ステータス： ドラフト | レビュー中 | 承認済み | 実装済み 作成日： [日付] | 最終更新日： [日付] レビュー担当者： [エンジニアリングリード、アーキテクト、PM、必要に応じてセキュリティ担当者] 関連 PRD： [リンク] | Jira エピック： [リンク]

---

1. 問題の説明

[2～3 文で、解決する問題と、なぜ今取り組むのかを記述します。ここでは解決策に触れないでください。]

2. 目標と対象外

目標（対象範囲内）：

• [具体的で測定可能な成果]
• [具体的で測定可能な成果]

対象外（明示的に範囲外）：

• [この仕様書で扱わない内容]
• [早い段階で明確に否定しておくべき一般的な思い込み]

3. 背景とコンテキスト

[意思決定の選択肢を理解するためにエンジニアが必要とする、先行事例、関連システム、または背景情報を記載します。以前の仕様書、ADR、調査へのリンクを含めてください。]

4. 提案するソリューション

概要アプローチ： [選択したソリューションを説明する 2～4 文。代替案ではなくこのアプローチを選ぶ理由も記載します。]

システムアーキテクチャ図： [関係するサービス、データフロー、呼び出す API を説明または埋め込んでください。]

データモデルの変更：

-- New tables or schema changes
[Include DDL or schema definition]

API 設計：

[Endpoint] [Method]
Request: { [fields and types] }
Response: { [fields and types] }
Error codes: [list]

主な実装の詳細：

• [重要な技術的制約またはアプローチ]
• [エッジケースへの対処]
• [サードパーティの依存関係とバージョン]

5. 検討した代替アプローチ

選択肢	メリット	デメリット	採用しなかった理由
[代替案 1]	[利点]	[欠点]	[採用しなかった理由]
[代替案 2]	[利点]	[欠点]	[採用しなかった理由]

6. セキュリティとプライバシーに関する考慮事項

• 保存するデータ： [関係する個人識別情報または機密データ]
• 認証： [アクセス制御の方法]
• 認可： [必要な権限]
• 暗号化： [保存時／転送時の要件]
• コンプライアンスへの影響： [該当する場合、GDPR、SOC2 など]

7. パフォーマンスとスケーラビリティ

• 想定負荷： [リクエスト数／秒、データ量]
• レイテンシ要件： [P50／P95 の目標]
• キャッシュ戦略： [該当する場合]
• データベースのインデックス： [新たに必要なインデックス]
• 既知のボトルネック： [注意すべき箇所]

8. テスト計画

• 単体テスト： [対象とする主要なシナリオ]
• 統合テスト： [テストするシステム境界]
• 負荷テスト： [パフォーマンスが重要な場合]
• エッジケース： [既知の難しいシナリオ]
• ロールバック計画： [問題発生時に元に戻す方法]

9. ロールアウト計画

• 機能フラグ： [あり／なし — フラグ名]
• ロールアウト段階： [各段階のユーザー割合]
• モニタリング： [設定するメトリクスとアラート]
• ロールアウトを進めるための成功基準： [満たすべき条件]
• ロールバックのトリガー： [即時ロールバックを行う条件]

10. 未解決の質問

質問	担当者	期限	解決内容
[未解決の質問]	[名前]	[日付]	[保留中]

11. 実装スケジュール（概算）

フェーズ	作業内容	見積もり工数
[フェーズ 1]	[実装する内容]	[X 日／ポイント]
[フェーズ 2]	[実装する内容]	[X 日／ポイント]
合計		[X ストーリーポイント]

---

ガイドライン

• 仕様書はタスクリストではなく意思決定記録です。決定に至った理由を記録してください
• 未解決の質問には、すべて担当者と期限を設定してください
• ユーザーデータを扱う機能では、セキュリティとプライバシーのセクションを必ず設けてください
• 非同期レビューを推奨します。まずエンジニアが読み、その後30分の同期ミーティングで質問を解決してください
• 実装の進行に合わせて仕様書を更新してください。古くなった仕様書は、仕様書がない場合よりも問題です

詳細資料

このスキルにはサポートファイルが含まれています。利用可能な場合は使用してください。

• references/spec-decisions.md — 仕様書の目的：意思決定、代替案、影響範囲。出力を作成する際に参照してください。このファイルには、上記の方法の概要では省略されている判断基準と判断の指針が記載されています。
• templates/spec-skeleton.md — 品質ゲートが文書内に記載された、記入式の成果物テンプレートです。生成を依頼するのではなく、ユーザー自身が文書を作成したい場合に提示してください。

品質チェック

• 問題の記述に解決策を示す表現が含まれていない
• 非目標に、スコープ内だと誤解される可能性がある項目を少なくとも2つ明記している
• 少なくとも2つの代替アプローチを、却下した理由とともに記録している
• ユーザーデータを扱う機能について、セキュリティとプライバシーのセクションを完成させている
• すべての未解決の質問に、担当者の氏名と期限を記載している（「TBD」ではない）

アンチパターン

• 問題の記述に解決策を示す表現を含めないでください。問題は、提案する解決策とは独立して記述する必要があります
• 検討した代替案を省略しないでください。1つのアプローチしか検討していない仕様書は、適切に評価されたとはいえません
• 担当者の氏名と期限を設定せず、未解決の質問を「TBD」のままにしないでください。未解決の質問はブロッカーです
• ユーザーデータを扱う機能で、セキュリティとプライバシーのセクションを省略しないでください
• 非目標のセクションを空にしないでください。スコープ内だと誤解される可能性がある項目を、必ず2つ以上記載してください