Appendix B: テンプレ集
本書で扱う判断・合意を「再利用可能な形式」にするためのテンプレートです。必要に応じてチーム向けに最小改変して使ってください。
記入例（完成形）が必要な場合は Appendix D を参照してください。
使い分け（要求→要件→仕様→設計→テスト）
本書では、対象を「要求/要件/仕様/設計」に分けます（定義は 00. この本の使い方 を参照）。
テンプレは、各段階の成果物（合意の型）に対応しています。
| 区分 | 何を決めるか | 代表成果物 | テンプレ |
|---|---|---|---|
| 要求 | なぜやるか（目的・課題・KPI） | Needs/Goals の整理 | B-1 |
| 要件 | 何を満たすべきか（Shall） | Requirements 一覧、スコープ、非機能の最小合意 | B-2 |
| 仕様 | どう振る舞うか（外部観測） | 受け入れ条件、例外系、エラー、外部I/Fの振る舞い | B-3（任意: B-10, B-12, B-13, B-14, B-16） |
| 設計 | どう作るか（内部構造） | S/D/V、設計アウトライン、Change Drivers、ADR | B-4〜B-7（任意: B-9/B-10, B-15） |
| テスト | どこをどう守るか | テスト配分（単体/統合/E2E） | B-8 |
| 横断 | 漏れ/矛盾を早期に見つける | 要件→仕様→設計→テストの対応 | B-11（任意） |
B-1. 要求（Needs / Goals）整理テンプレ（目的・課題・KPI）
目的: 「なぜやるか」を目的と測定（KPI）として固定し、後続の要件・仕様の判断軸にする。
# 要求（Needs / Goals）: <テーマ>
## 背景/課題（As-Is）
- 何が起きているか（事実）:
- 誰が困っているか:
- 放置するとどうなるか（損失/機会損失）:
## 目的（Goals / To-Be）
- 目標状態（業務/体験）:
- 期限（いつまでに）:
## KPI（測定）
| 指標 | 現状 | 目標 | 測定方法 | 備考 |
| --- | --- | --- | --- | --- |
| | | | | |
## スコープ/非ゴール
- 含む:
- 含まない（非ゴール）:
## 制約/前提
- 予算/期限:
- 体制/運用:
- 既存システム/外部I/F:
B-2. 要件（Requirements / Shall）テンプレ（約束の一覧）
目的: 実装方法に依存しない「約束（Shall）」を列挙し、スコープと非機能の最小合意を取る。
# 要件（Requirements / Shall）: <対象>
## スコープ
- 含む:
- 含まない（非ゴール）:
## 機能要件（Shall）
| ID | Shall（要件） | 根拠（要求/KPI） | 優先度 | 備考 |
| --- | --- | --- | --- | --- |
| R-1 | | | Must/Should/Could | |
| R-2 | | | | |
## 非機能（最小合意）
- 性能:
- 可用性:
- セキュリティ/権限:
- 監査/ログ:
- 運用（アラート/リトライ/バックアップ）:
## 未決/リスク
- 未決事項:
- リスク:
B-3. 仕様（Specification / Behavior）テンプレ（外部観測の振る舞い）
目的: 外部から観測できる振る舞い（入力/出力、状態遷移、エラー）を曖昧さなく定義し、実装と独立した検証基準にする。
# 仕様（Specification / Behavior）: <対象>
## 参照（要求/要件）
- 要求: <リンク/ID>
- 要件: <リンク/ID>
## 外部I/F（観測できる面）
- UI:
- API:
- 外部連携（通知等）:
## 受け入れ条件（Given/When/Then）
- Given: <前提>
- When: <操作/イベント>
- Then: <期待結果（観測できる形で）>
## 例外系/失敗時の振る舞い（Behavior）
- 認可失敗:
- 存在しない/不正入力:
- 競合（同時更新）:
- 外部I/F失敗（通知等）:
## 観測点（何をもって合否判定するか）
- 画面表示:
- API レスポンス（ステータス、エラー形式）:
- 監査/ログ（必要なら）:
## テスト観点（仕様から導出）
- 単体テストで守る振る舞い:
- 統合テストで守る契約（境界）:
- E2E で守る導線:
B-4. S/D/V 採点表（依存関係トップ 10）
目的: 依存関係の「痛み」を半定量で把握し、手当（境界/契約/テスト投資）の優先順位を付ける。
採点の目安（例）:
- S（統合強度）: 1=独立、3=時々同時変更、5=常に同時変更/同時デプロイ
- D（距離）: 1=同一モジュール、3=同一リポジトリ別パッケージ、5=別サービス/別組織/ネットワーク越し
- V（変動性）: 1=ほぼ固定、3=四半期で変わる、5=週次で変わる/不確実性が高い
| # | 依存元 | 依存先 | 依存の内容 | S(1-5) | D(1-5) | V(1-5) | コメント（観測/根拠） | 手当案 |
| ---: | --- | --- | --- | ---: | ---: | ---: | --- | --- |
| 1 | | | | | | | | |
| 2 | | | | | | | | |
| 3 | | | | | | | | |
| 4 | | | | | | | | |
| 5 | | | | | | | | |
| 6 | | | | | | | | |
| 7 | | | | | | | | |
| 8 | | | | | | | | |
| 9 | | | | | | | | |
| 10 | | | | | | | | |
補助質問:
- 同時変更が必要になる原因は何か（データ構造、仕様、例外処理、認可など）
- 距離が大きい場合、契約（インターフェース/スキーマ/契約テスト）は十分か
- 変動性が高い場合、抽象化は「固定化」になっていないか
B-5. 設計（Design / Structure）アウトラインテンプレ（境界・構造）
目的: 仕様を満たすための内部構造（境界、責務、依存方向、データモデル）を最小で定義する。
# 設計（Design / Structure）: <対象>
## 参照（要求/要件/仕様）
- 要求:
- 要件:
- 仕様:
## 構造（境界と責務）
- domain:
- usecases:
- adapters:
## 依存方向（ルール）
- 依存の向き:
- 例外（許可する参照）:
## データモデル
- 論理（概念/エンティティ）:
- 物理（DB テーブル/インデックス/制約）:
## 重要アルゴリズム/ルール
- 何をどこで計算するか（例: 期限判定、権限判定）:
## トレードオフ
- 得るもの:
- 失うもの:
## テスト戦略への影響
- 単体/統合/E2E の主な対象:
B-6. 変更理由（Change Drivers）整理テンプレ（任意）
目的: 「なぜ今変えるのか」を先に揃え、設計変更の正当化（後付け）を避ける。
# Change Drivers: <変更のテーマ>
## 背景（何が起きているか）
- 事象（観測）:
- 影響（価値/運用/コスト）:
- 期限（いつまでに）:
## ドライバー（何が変更を必要にしているか）
| ドライバー | 内容 | 強さ（低/中/高） | 根拠 |
| --- | --- | --- | --- |
| 変動性（V） | | | |
| 距離（D） | | | |
| 統合強度（S） | | | |
| 運用要件 | | | |
| チーム/組織 | | | |
## 対応方針（案）
- 何を変える:
- 変えないこと（非ゴール）:
- テスト戦略への影響:
- ADR が必要か:
B-7. ADR テンプレ（Context / Decision / Consequences）
# ADR: <短いタイトル>
- Status: proposed | accepted | superseded
- Date: YYYY-MM-DD
- Deciders: <意思決定者/関係者>
- Scope: <対象範囲（モジュール/機能/チーム）>
## Context
- 背景:
- 問題:
- 制約（要件/非機能/運用）:
- 既存の選択（As-Is）:
## Decision
- 採用する決定:
- 理由（S/D/V、複雑性、テスト戦略との整合）:
## Consequences
- 得られる効果:
- 失うもの/トレードオフ:
- 後続タスク:
- 見直し条件（いつ再評価するか）:
B-8. テスト配分テンプレ（単体/統合/E2E）
# テスト配分: <対象機能/導線>
## 方針（ねらい）
- 価値導線:
- 主要リスク:
- 許容できない障害:
## 配分
| レベル | ねらい | 対象 | 備考 |
| --- | --- | --- | --- |
| 単体 | コアの振る舞い保護 | 純粋ロジック / 変換 / ルール | 実装詳細への依存を避ける |
| 統合 | 境界の契約保護 | API / DB / 認可 / 外部連携 | 失敗時の動作も含める |
| E2E | 価値導線の保護 | 主要ユーザーフロー（少数） | 不安定要因を最小化 |
## 禁止事項（例）
- E2E の増やし過ぎ（時間・不安定さで破綻）
- 単体テストで外部 I/O を扱う（統合で検証する）
- モック過多（設計の境界が崩れている兆候）
B-9. 相互作用マップテンプレ（変更シナリオ→波及→観測→制約候補）（任意）
目的: 複雑性を「相互作用」として扱い、設計の焦点（制約/境界）を作る。章 02 の手順を成果物として残すためのテンプレ。
# 相互作用マップ: <テーマ>
## 変更シナリオ
- 例: <期限ルールの変更>
- 例: <権限モデルの拡張>
- 例: <外部I/F（通知）の失敗が顕在化>
## 波及先（UI/API/DB/外部I/F/運用/テスト）
- UI:
- API:
- DB:
- 外部I/F:
- 運用:
- テスト:
## 観測点（何をもって合否判定するか）
- UI:
- API:
- ログ/監査:
- その他:
## 制約/最小手当（候補）
- 例: ルールを domain に集約し、重複実装を禁止する
- 例: 失敗時の期待（継続/停止、検知、再送）を仕様として固定する
- 例: エラー形式（code）を固定し、境界で整形する
## 次アクション（S/D/V とテスト配分への接続）
- S/D/V 採点対象（トップ 3）:
- テスト配分（単体/統合/E2E）で守る契約:
B-10. エラーコードカタログテンプレ（code/message/HTTP/運用）（任意）
目的: 境界（例: HTTP）で返す失敗理由を「契約」として固定し、UI/テスト/運用の相互作用を減らす。章 04（エラーの扱い）と章 05-06（テスト）に接続する。
# エラーコードカタログ: <対象（例: タスク割り当て API）>
## エラー一覧
| code | message（利用者向け） | 起点（境界） | HTTP | 再試行可否 | 監査/ログ | 備考 |
| --- | --- | --- | --- | --- | --- | --- |
| forbidden | 権限がありません | 認可 | 403 | No | 失敗理由を記録 | |
| not_found | 対象が見つかりません | 参照 | 404 | No | 対象IDを記録 | |
| conflict | 競合が発生しました | 同時更新 | 409 | Yes/No | 相関IDを記録 | 楽観ロック等 |
| invalid | 入力が不正です | 入力検証 | 400 | No | 最小限を記録 | 個人情報を出さない |
## 運用方針
- ログに出す項目（相関ID、actor、対象ID、code）:
- 監査ログの記録範囲/保持期間:
- 再試行する場合の上限/間隔（必要なら）:
B-11. トレーサビリティマップ（要求→要件→仕様→設計→テスト）（任意）
目的: 「この Shall は、どの仕様/設計/テストで担保するか」を見える化し、漏れ（未実装/未検証）を早期に発見する。
運用方針（最小）:
- すべてを網羅しない（トップ要件/主要導線から始める）
- 仕様（B-3）とテスト配分（B-8）を更新したら、対応行も更新する（PR の一部にする）
- 「リンク/ID で追える」粒度にする（文章の再掲はしない）
- 仕様（受け入れ条件）を ID（例:
AC-1）で参照したい場合は B-12 を併用する
# トレーサビリティ: <対象（例: タスク割り当て + 通知）>
| 要件ID | Shall（要約） | 仕様（受け入れ条件/観測点） | 設計（境界/ADR/エラーcode等） | テスト（単体/統合/E2E） | 状態 | 備考 |
| --- | --- | --- | --- | --- | --- | --- |
| R-1 | | | | | 未/一部/完了 | |
| R-2 | | | | | | |
B-12. 受け入れ条件（AC）ID 管理テンプレ（任意）
目的: 受け入れ条件（Given/When/Then）を ID 化し、要件/テスト/障害調査の会話コストを下げる。B-3（仕様）と B-11（トレーサビリティ）に接続する。
運用方針（最小）:
- すべての条件を ID 化しない（主要導線から始める）
- ID は「参照のための鍵」として扱い、番号の振り直しを避ける（履歴と追跡性を優先する）
- テスト名や PR の説明に ID を含めると、レビューの往復が減る（例:
AC-3: 期限超過表示）
# 受け入れ条件（AC）: <対象（例: タスク割り当て + 通知）>
| AC ID | 要件ID | Given（前提） | When（操作/イベント） | Then（期待結果/観測点） | 例外系/エラーcode | 推奨テスト | 備考 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| AC-1 | R-1 | | | | | E2E/統合/単体 | |
| AC-2 | | | | | | | |
B-13. 認可（Authorization）ルール表テンプレ（任意）
目的: 認可ルール（役割/所有者/操作）を表形式で合意し、仕様・設計・テストの前提を揃える。B-3（仕様）と B-10（エラーcode）と B-8（テスト配分）に接続する。
運用方針（最小）:
- UI の表示制御に依存しない（サーバ側で必ず強制する）
- 「誰が」「何に」「何をできるか」を最小の語彙で固定し、例外（代理、管理者権限等）は備考に逃がさない
- 監査/ログは、成功だけでなく失敗（
forbidden等）も追跡できる粒度にする（個人情報をログに出さない）
# 認可（Authorization）ルール: <対象（例: タスク管理）>
## 役割/属性（最小）
- role:
- admin:
- user:
- 属性（例）:
- owner（`resource.ownerId == actorId`）:
- assignee（`resource.assigneeId == actorId`）:
## ルール表
| 操作ID | 操作（Action） | 対象（Resource） | 許可条件（Role/属性） | 失敗時（code/HTTP） | 監査/ログ | 推奨テスト | 備考 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| AUTHZ-1 | assign_task | task | admin のみ | forbidden/403 | actor/taskId/code/相関ID | 統合/単体 | |
| AUTHZ-2 | update_status | task | assignee のみ | forbidden/403 | actor/taskId/code/相関ID | 統合/単体 | 状態遷移ルールは別途 |
B-14. API 契約テンプレ（HTTP/エラー/冪等性）（任意）
目的: HTTP API の入出力・エラー・冪等性を「契約」として固定し、UI/API/テスト（統合）の相互作用を減らす。B-10（エラーcode）/B-12（AC-ID）/B-13（認可）に接続する。
運用方針（最小）:
- 「成功の形」と同じくらい「失敗の形（code/HTTP）」を固定する（曖昧なまま実装しない）
- 冪等性（二重送信）と同時更新（競合）の扱いを契約に含める（フレーク・運用負債の主要因）
- 互換性を崩す変更（破壊的変更）は、移行計画とセットで扱う（ADR を残す）
# API 契約: <対象（例: タスク割り当て API）>
## 関連（要求/要件/受け入れ条件）
- 要件ID: (例) R-1, R-2
- AC ID: (例) AC-1, AC-2
## エンドポイント
- method/path: `POST /api/...`
- operationId（任意）:
- 認証/認可: (例) admin のみ（B-13参照）
## Request
- headers:
- (任意) `Idempotency-Key`:
- params:
- `taskId`:
- body（例）:
- `assigneeId`:
## Response（Success）
- status: `200` / `201` / `204`
- body（例）:
- `taskId`:
- `assigneeId`:
- `assignedAt`:
## Response（Error）
最小形式（例）:
- `{ "code": "<reason>", "message": "<user-facing>" }`
| code | HTTP | 条件（いつ起きるか） | 再試行可否 | 備考 |
| --- | --- | --- | --- | --- |
| forbidden | 403 | 認可失敗 | No | B-13 |
| not_found | 404 | 対象なし | No | |
| invalid | 400 | 入力不正 | No | |
| conflict | 409 | 競合/状態不整合 | Yes/No | 同時更新方針を固定 |
## 冪等性（二重送信）/同時更新（競合）
- 冪等性の方針:
- 同時更新の方針（例: 楽観ロックで `409`）:
## ログ/監査（最小）
- 監査/ログに含める項目（相関ID、actor、対象ID、code）:
- 個人情報はログに出さない:
B-15. データ整合性/同時更新（競合）テンプレ（任意）
目的: 整合性制約（invariant）と同時更新（競合）時の方針を合意し、仕様・設計・テストの前提を揃える。B-3（仕様）/B-10（エラーcode）/B-8（テスト配分）に接続する。
運用方針（最小）:
- 「何を同一トランザクションで守るか」を明文化する（守れないなら、観測と復旧をセットにする）
- 競合（同時更新）の扱いを曖昧にしない（後勝ち/排他/楽観ロックのいずれかを選ぶ）
- DB 制約（UNIQUE/FK 等）で守るものと、アプリケーションで守るものを分ける
# データ整合性/同時更新: <対象（例: タスク割り当て）>
## 不変条件（Invariant）
| ID | 不変条件（守るべきこと） | 破ると何が起きるか | 守る場所（domain/DB/両方） | 備考 |
| --- | --- | --- | --- | --- |
| I-1 | | | | |
| I-2 | | | | |
## 整合性境界（トランザクション）
- 同一トランザクションで成立させるもの（例: タスク更新 + 監査ログ記録）:
- 結果整合でよいもの（例: 外部通知の到達）:
## 同時更新（競合）方針
- 方針: 後勝ち / 排他 / 楽観ロック
- 競合時の外部挙動: `conflict/409`（または同等）
- 再試行: Yes/No（上限、間隔、誰が再試行するか）
## DB 物理（任意）
- UNIQUE 制約:
- FK/参照整合性:
- バージョン列（楽観ロック）:
- インデックス:
## テスト観点（最小）
- 単体: 不変条件（ルール）を純粋関数で守る
- 統合: DB 制約と競合時の挙動（`409`/code）を守る
B-16. 外部I/F失敗時設計テンプレ（リトライ/再送/監視）（任意）
目的: 外部I/F（通知等）の失敗・遅延を前提に、業務継続/停止、再送、監視、手動復旧を「仕様として」固定する。B-3（仕様）/B-10（エラーcode）/B-8（テスト配分）に接続する。
運用方針（最小）:
- 「失敗したらどうなるか」を、成功時と同じ精度で決める（曖昧なまま実装しない）
- 再試行は「誰が/どこで/何回まで/どの間隔で」を固定する（無限リトライ禁止）
- 二重実行を前提に、冪等性（重複抑止）と観測点（ログ/メトリクス/アラート）をセットにする
# 外部I/F失敗時設計: <対象（例: メール通知）>
## 前提/非ゴール
- 外部I/F: <通知/決済/認証など>
- 失敗が業務に与える影響: <継続/停止/遅延の許容>
- 非ゴール（例）:
- 厳密な exactly-once を目指さない
- 外部サービスの SLA を自系で保証しない
## 失敗分類（観測できること）
| code（運用） | 失敗種別 | 例 | 再試行 | 期待する挙動（仕様） | 観測点（ログ/メトリクス） | 備考 |
| --- | --- | --- | --- | --- | --- | --- |
| EXT-1 | TIMEOUT | | Yes/No | | | |
| EXT-2 | 5XX | | | | | |
| EXT-3 | 4XX | | | | | |
| EXT-4 | RATE_LIMIT | | | | | |
## 失敗時の業務継続（同期/非同期）
- 「業務結果」と「外部I/F結果」を分離する: <する/しない>
- 失敗時の外部挙動（API/UI）:
- code/HTTP（任意）:
- ユーザー表示:
- 停止させる条件（例: 決済失敗は業務失敗）:
- <条件>
## 再試行/再送方針
- 自動再試行: Yes/No
- 回数上限:
- 間隔（バックオフ）:
- 誰が再試行するか（アプリ/ジョブ/キュー）:
- 手動再送: Yes/No
- 起点（管理画面/運用スクリプト）:
- 権限:
- 手順:
- 冪等性/重複抑止:
- 冪等性キー（例: `Idempotency-Key`/`dedupeKey`）:
- 重複判定の単位（例: `(taskId, notificationType)`）:
## 永続化/キュー（任意）
- 記録するもの（例: 通知要求、送信結果、試行回数、最終エラー）:
- 状態（例）: pending -> sending -> sent / failed
- DLQ/保管先:
- 保持期間/クリーンアップ:
## 監視/アラート（最小）
- 失敗率:
- 滞留（未送信）件数:
- 遅延時間:
- アラート先/対応SLO:
- 相関ID（トレース）:
## テスト観点（最小）
- 単体: 再試行可否の判定（失敗分類）を純粋関数で守る
- 統合: 失敗時に「再送起点」が記録され、アラート条件を満たすと検知できる