Software Engineering Guide
12.3

View in English

12.3 テンプレート

これらのテンプレートは、コピー&ペーストですぐに使える出発点です。どのテンプレートもwiki、リポジトリ、チケットシステムに持ち込み、括弧付きのプレースホルダーを埋めてください。斜体の注記とインラインのコメントは、各セクションに何が属するかを説明します。セクションを埋めたら削除してください。テンプレートを軽量に保ちます。完成させるより飛ばすほうが速いテンプレートは使われません。見出しとセクションを組織に合わせて調整してよいですが、各部分の意図は保ってください。

以下で使う慣習がいくつかあります。

  • [角括弧]内のテキストは、置き換えるプレースホルダーです。
  • 斜体あるいは<!-- コメント -->のテキストは、削除する指針です。
  • 完成した文書を、その問いに答えながら、できるだけ短く保ちます。

アーキテクチャ決定記録(ADR)

# ADR [NNNN]: [決定の短いタイトル]

- ステータス: [提案 | 承認 | 非推奨 | ADR-XXXXに置き換え]
- 日付: [YYYY-MM-DD]
- 決定者: [名前あるいは役割]
- 相談先: [名前あるいは役割]

## 文脈

<!-- この決定を駆動している問題、力、制約は何か。
     事実と要件を中立に述べる。決定がなぜ必要だったかを
     将来の読み手が理解するのに必要なものだけを含める。 -->

## 決定

<!-- 選択を一、二の明確な文で述べる。「私たちは…する」 -->

## 検討した代替案

<!-- 比較した現実的な選択肢と、それぞれが選ばれた、あるいは
     選ばれなかった理由を挙げる。少なくとも二つの代替案が
     ここに現れるべき。 -->

- 選択肢A: [要約]。[理由]のため却下。
- 選択肢B: [要約]。[理由]のため却下。
- 選んだ選択肢: [要約]。[理由]のため選択。

## 帰結

<!-- 決定の誠実な結果。良い面も悪い面も。 -->

- 良い面: [得られる利益]
- 悪い面: [受け入れるコスト、リスク、限界]
- 後続: [これが引き起こす移行、新しい仕事、決定]

## 関連

<!-- 関連する先行のADR、RFC、チケット、文書へのリンク。 -->

RFC/設計文書

# RFC: [タイトル]

- 著者: [名前]
- ステータス: [下書き | レビュー中 | 承認 | 却下 | 実装済み]
- レビュアー: [名前あるいは役割]
- 作成日: [YYYY-MM-DD]
- 最終更新日: [YYYY-MM-DD]
- チケット/追跡: [リンク]

## 概要

<!-- 一段落。何を提案し、なぜそれが重要か。読み手がこの
     セクションだけで本質を把握できるべき。 -->

## 問題と動機

<!-- 何の問題を解くのか。誰が影響を受けるか。何もしなければ
     何が起こるか。関連する背景と制約を含める。 -->

## 目標と非目標

- 目標: [成功がどう見えるか。可能な所は測定可能に]
- 非目標: [スコープクリープを防ぐため、明示的に範囲外のもの]

## 提案する設計

<!-- 文書の核心。アプローチ、アーキテクチャ、データモデル、
     インターフェース、主要な流れを述べる。明確にする所では
     図を使う。何であるかだけでなく、どう働くかを説明する。 -->

## 検討した代替案

<!-- 他のアプローチと、選ばれなかった理由。設計の空間が
     探索されたことを読み手に示す。 -->

## 影響とリスク

- セキュリティとプライバシー: [含意と緩和策]
- パフォーマンスと規模: [期待される負荷と挙動]
- 運用性: [監視、失敗の様式、展開、ロールバック]
- コスト: [インフラストラクチャあるいはライセンスへの影響]
- 後方互換性: [移行と廃止]

## テストと展開の計画

<!-- 変更がどう検証され、安全にリリースされるか。 -->

## 未解決の問い

<!-- レビュアーに検討してほしい未解決の問題。 -->

ポストモーテム/インシデントレビュー(責めない)

# ポストモーテム: [インシデントのタイトル]

- インシデントID: [ID]
- インシデントの日付: [YYYY-MM-DD]
- 著者: [名前]
- ステータス: [下書き | 最終]
- 深刻度: [SEV1 | SEV2 | SEV3]

> このレビューは責めないものです。個人ではなく、システムと
> 寄与した要因に焦点を当てます。目標は学ぶことと、再発を
> 防ぐことです。

## 要約

<!-- 二、三の文。何が起こり、影響は何で、どう解決したか。
     専門家でない人にも読めるように。 -->

## 影響

- 期間: [開始時刻から復旧時刻、タイムゾーン付き]
- 影響を受けたユーザー: [範囲と数]
- 事業への影響: [収益、SLA、評判、その他]

## タイムライン

<!-- タイムスタンプ付きの事実に基づく出来事の連なり。
     検知、エスカレーション、主要な行動、復旧を含める。 -->

- [HH:MM] [出来事]
- [HH:MM] [出来事]

## 寄与した要因

<!-- インシデントに至った条件の連鎖。単一の根本原因より
     「寄与した要因」を好む。 -->

## 検知と対応

- どう検知されたか。[アラート、顧客の報告など]
- 何が対応を助けたか。
- 何が対応を遅くしたか。

## うまくいったこと

<!-- 効果的だった行動と、機能した安全装置を認める。 -->

## 行動項目

<!-- 具体的で、所有者があり、日付がある。予防、検知、緩和に
     対処する。通常の積み残しで追跡する。 -->

| 行動 | 所有者 | 期限 | 種類(予防/検知/緩和) | チケット |
|------|--------|------|----------------------|----------|
| [行動] | [名前] | [日付] | [種類] | [リンク] |

## 得られた教訓

<!-- より広い組織が持ち帰るべきこと。 -->

脅威モデル(STRIDEベース)

# 脅威モデル: [システムあるいは機能の名前]

- 著者: [名前]
- 日付: [YYYY-MM-DD]
- レビュアー: [セキュリティの窓口、所有者]
- 範囲: [カバーするものとしないもの]

## システムの概要

<!-- システム、その目的、ユーザーの簡潔な説明。 -->

## 資産

<!-- 守る価値のあるもの。データ、資格情報、機能、評判。
     それぞれの機微さに注意する。 -->

## 信頼の境界とデータフロー

<!-- コンポーネント、データストア、外部の実体、信頼が変わる
     境界を記述あるいは図示する。 -->

## 脅威(STRIDE)

<!-- 各要素について、STRIDEの分類を検討する。信頼できる各脅威、
     そのリスク、緩和策あるいは受け入れたリスクを記録する。 -->

| 脅威 | STRIDEの分類 | 影響を受ける要素 | リスク(低/中/高) | 緩和策 | ステータス |
|------|--------------|------------------|------------------|--------|------------|
| [脅威] | なりすまし(Spoofing) | [要素] | [リスク] | [統制] | [未対応/緩和済み/受け入れ] |
| [脅威] | 改ざん(Tampering) | [要素] | [リスク] | [統制] | [ステータス] |
| [脅威] | 否認(Repudiation) | [要素] | [リスク] | [統制] | [ステータス] |
| [脅威] | 情報漏えい(Information disclosure) | [要素] | [リスク] | [統制] | [ステータス] |
| [脅威] | サービス拒否(Denial of service) | [要素] | [リスク] | [統制] | [ステータス] |
| [脅威] | 権限昇格(Elevation of privilege) | [要素] | [リスク] | [統制] | [ステータス] |

## 前提と依存関係

<!-- 頼っているセキュリティの前提と、信頼している外部の統制。 -->

## 未解決の問題と後続

<!-- さらなる作業が必要な脅威。チケットとして追跡する。 -->

ランブック

# ランブック: [タスクあるいはシナリオの名前]

- サービス: [サービス名]
- 所有者: [チーム]
- 最終レビュー: [YYYY-MM-DD]
- 関連するアラート: [アラート名]

## 目的

<!-- このランブックをいつ使い、何を達成するか。 -->

## 前提条件

<!-- 始める前に必要なアクセス、ツール、権限。 -->

## 検知/症状

<!-- オペレーターが観察するもの。アラート、エラーの特徴、
     ダッシュボード。 -->

## 診断

<!-- 問題を確認して原因を絞り込む段階的なチェック。正確な
     コマンド、クエリ、ダッシュボードのリンクを含める。 -->

1. [ステップと期待される結果]
2. [ステップと期待される結果]

## 解決

<!-- 修正あるいは緩和する具体的で順序のあるステップ。リスクが
     ある、あるいは不可逆なステップと、成功の検証方法に注意する。 -->

1. [ステップ]
2. [復旧の検証]

## ロールバック

<!-- 解決が事態を悪化させた場合に、行動を元に戻す方法。 -->

## エスカレーション

<!-- 誰に連絡し、いつエスカレーションするか。二次のオンコール、
     所有するチーム、ベンダーの連絡先。 -->

## 参考

<!-- ダッシュボード、関連するランブック、アーキテクチャの文書。 -->

サービスREADME/サービスカタログのエントリ

# [サービス名]

- 所有チーム: [チーム]
- オンコール: [ローテーションのリンク]
- 階層/重要性: [階層1 | 2 | 3]
- リポジトリ: [リンク]
- ステータス: [稼働中 | 非推奨]

## 何をするか

<!-- サービスの責任とその利用者についての一段落。 -->

## アーキテクチャ

<!-- 主要なコンポーネント、依存関係(上流と下流)、設計文書
     あるいは図へのリンク。 -->

## インターフェース

- API/エンドポイント: [仕様へのリンク]
- 発行/消費されるイベント: [トピック]
- データストア: [データベース、キャッシュ、バケット]

## 実行時とデプロイ

- 環境: [開発、ステージング、本番]
- デプロイの方法: [パイプラインのリンクとプロセス]
- 設定とフィーチャーフラグ: [場所と方法]

## オブザーバビリティ

- ダッシュボード: [リンク]
- アラート: [リンク]
- ログ: [見つけられる場所]
- SLO: [リンク]

## 運用

- ランブック: [リンク]
- 一般的なタスク: [スケーリング、再起動、バックフィル]
- 既知の問題と限界: [注記]

## はじめに(新しい貢献者向け)

<!-- ローカルでビルド、テスト、実行する方法。 -->

## 連絡先

- Slack/チャットのチャンネル: [リンク]
- エスカレーション: [経路]

SLO/エラーバジェットの方針

# SLOとエラーバジェットの方針: [サービスあるいは旅の名前]

- 所有者: [チーム]
- 発効日: [YYYY-MM-DD]
- 見直しの周期: [たとえば四半期ごと]

## サービスレベル指標(SLI)

<!-- 各SLIを正確に定義する。測定される量、どう測定されるか、
     どこから(理想的にはユーザーの視点から)。 -->

| SLI | 定義 | データ源 |
|-----|------|----------|
| 可用性 | [たとえば成功したリクエスト/総リクエスト] | [源] |
| レイテンシ | [たとえばXミリ秒未満のリクエストの割合] | [源] |

## 目標(SLO)

| SLI | 目標 | 測定の窓 |
|-----|------|----------|
| 可用性 | [たとえば99.9%] | [たとえば28日間のローリング] |
| レイテンシ | [たとえば95%が300ミリ秒未満] | [28日間のローリング] |

## エラーバジェット

<!-- 許容される不信頼性。窓にわたる100%から目標を引いたもの。
     バジェットを具体的な言葉で述べる(たとえば月あたりの分)。 -->

- バジェット: [導かれた許容量]

## バジェットが尽きたときの方針

<!-- 合意された帰結。具体的で徹底できるものにする。 -->

- [たとえば、バジェットが回復するまで重要でない機能のリリースを凍結する。]
- [たとえば、次の計画サイクルで信頼性の仕事を優先する。]
- [たとえば、二つの窓連続で違反した場合、エンジニアリングのリーダーシップにエスカレーションする。]

## バジェットが健全なときの方針

<!-- チームが取ってよい追加のリスク。たとえばより速い展開。 -->

## アラート

<!-- このSLOに結びついたバーンレートのアラートと閾値。 -->

リスク登録簿のエントリ

## リスク: [リスクの短いタイトル]

- リスクID: [ID]
- 提起日: [YYYY-MM-DD]
- 所有者: [このリスクの管理に責任を負う名前あるいは役割]
- 区分: [セキュリティ | 運用 | コンプライアンス | 財務 | デリバリー | ベンダー]
- ステータス: [未対応 | 緩和中 | 受け入れ | 完了]

### 説明

<!-- リスクを、原因 -> 出来事 -> 結果として述べる。何が起こりえて、
     なぜそれが重要か。 -->

### 評価

- 可能性: [低 | 中 | 高]
- 影響: [低 | 中 | 高]
- 総合評価: [可能性 x 影響から導く]

### 現在の統制

<!-- 今日すでにこのリスクを減らしているもの。 -->

### 緩和計画

<!-- 可能性あるいは影響を減らす計画された行動。所有者と日付を
     伴う。リスクを受け入れる場合は、誰がなぜ受け入れたかを
     記録する。 -->

| 行動 | 所有者 | 期限 | ステータス |
|------|--------|------|------------|
| [行動] | [名前] | [日付] | [ステータス] |

### 見直し

- 次の見直し日: [YYYY-MM-DD]
- 決定/注記: [受け入れの承認や変更]

プロジェクトの一枚紙/プロダクトの概要

# [プロジェクトあるいはプロダクトの名前]: 一枚紙

- スポンサー: [名前]
- リード: [名前]
- 日付: [YYYY-MM-DD]
- ステータス: [アイデア | 承認 | 進行中 | 出荷済み]

## 問題

<!-- 一段落。顧客あるいは事業の問題と、それが本物で解く価値が
     あるという証拠。 -->

## 対象

<!-- この問題を誰が抱え、解決から誰が利益を得るか。 -->

## 提案する解決策

<!-- 築く、あるいは変えるものの短い説明。実装の詳細ではなく、
     意図の水準に保つ。 -->

## なぜ今か

<!-- 後ではなく今これを行う理由。 -->

## 成功の指標

<!-- うまくいったことをどうやって知るか。測定可能な成果を好む。 -->

- [指標と目標]

## 範囲

- 範囲内: [行うこと]
- 範囲外: [行わないこと]

## リスクと未解決の問い

<!-- 主な不確実性と依存関係。 -->

## 大まかな計画とマイルストーン

<!-- 高い水準の段階とおおよそのタイミング。 -->

## コストと資源

<!-- 必要な人、時間、予算。 -->

オンコールの引き継ぎノート

# オンコールの引き継ぎ: [YYYY-MM-DD]

- 退出する人: [名前]
- 引き継ぐ人: [名前]
- サービス: [名前]

## 全体の状況

<!-- 一行。静か、騒がしい、あるいは進行中の問題。 -->

## 開いているインシデント

<!-- 次の対応者が知るべき、アクティブあるいは最近解決した
     インシデント。リンクを伴う。 -->

- [インシデント、ステータス、残っていること]

## 進行中あるいは計画された変更

<!-- アラートを引き起こしうる、進行中のデプロイ、移行、
     メンテナンスの窓、実験。 -->

## うるさい、あるいは不安定なアラート

<!-- 発火したアラートとその本当の意味。次の人が誤解しない
     ように。一時的な無音化とその期限に注意する。 -->

## 注視する項目

<!-- 懸念される方向へ傾向している指標あるいはシステム。 -->

## 保留の後続

<!-- 次のシフトに渡すタスク。チケットへのリンクを伴う。 -->

## 注記

<!-- その他の有用なこと。アクセスの癖、ベンダーの問題、文脈。 -->

変更要求(規制対象の変更管理向け)

# 変更要求: [変更のタイトル]

- 変更ID: [ID]
- 要求者: [名前]
- 提出日: [YYYY-MM-DD]
- 種類: [標準 | 通常 | 緊急]
- 優先度: [低 | 中 | 高]
- ステータス: [提出済み | 承認 | 却下 | 実施済み | 完了]

## 変更の説明

<!-- 何が、なぜ変わるか。チケットあるいは要件を参照する。 -->

## 影響を受けるシステムとコンポーネント

<!-- 影響を受けるサービス、データ、環境、ユーザー。 -->

## 正当化と事業への影響

<!-- 変更の理由と、行わない場合の影響。 -->

## リスク評価

- リスク水準: [低 | 中 | 高]
- 変更が失敗した場合の潜在的な影響: [説明]
- セキュリティ、プライバシー、コンプライアンスへの影響: [説明]

## 実施計画

<!-- 順序のあるステップ、責任者、タイミング。 -->

## テストと検証の計画

<!-- 変更の前後に、成功をどう検証するか。 -->

## 巻き戻し/ロールバックの計画

<!-- 失敗した場合に変更を取り消す方法と、復旧時間。 -->

## スケジュール

- 提案する窓: [開始と終了、タイムゾーン付き]
- 予期される停止時間: [期間あるいはなし]

## 承認

| 役割 | 名前 | 決定 | 日付 |
|------|------|------|------|
| 変更の所有者 | [名前] | [承認/却下] | [日付] |
| 技術レビュアー | [名前] | [承認/却下] | [日付] |
| 変更諮問委員会 | [名前] | [承認/却下] | [日付] |

## 実施後のレビュー

<!-- 結果、遭遇した問題、巻き戻しが必要だったか。 -->

データ保護影響評価(DPIA)の概要

# データ保護影響評価: [処理活動の名前]

- 評価者: [名前]
- 日付: [YYYY-MM-DD]
- レビュアー: [DPO/プライバシーの窓口]
- ステータス: [下書き | レビュー済み | 承認]

## 1. 処理の説明

<!-- どんな個人データが、どう、誰によって、何の目的で処理される
     か。収集から削除までのデータフローを含める。 -->

- データ主体: [データが誰についてのものか]
- データの区分: [個人データの種類、特別な区分に注意]
- 目的: [データがなぜ処理されるか]
- 受領者と処理者: [誰がデータを受け取る、あるいは扱うか]
- 保持期間: [データがどれだけ保たれ、削除の方法]
- 国際的な移転: [送り先と移転の仕組み]

## 2. 必要性と比例性

<!-- 処理は目的に必要か。最も侵襲の少ない選択肢か。適法な
     根拠あるいは権限は何か。 -->

- 適法な根拠/権限: [各目的の根拠]
- データの最小化: [各項目がなぜ必要か]
- 正確性と保持の正当化: [注記]
- データ主体の権利がどう支えられるか: [アクセス、削除など]

## 3. 協議

<!-- 協議した利害関係者と、該当する場合はデータ主体。 -->

## 4. 個人へのリスク

<!-- プライバシーのリスクを特定し、それぞれを評価する。 -->

| 個人へのリスク | 可能性 | 重大性 | 総合 |
|----------------|--------|--------|------|
| [たとえば機微なデータへの不正アクセス] | [低/中/高] | [低/中/高] | [評価] |

## 5. リスクを減らす措置

<!-- 各リスクについて、緩和策と、それを講じた後の残余リスク。 -->

| リスク | 措置 | 残余リスク | 受け入れ者 |
|--------|------|------------|------------|
| [リスク] | [統制] | [低/中/高] | [名前] |

## 6. 結果と承認

- 残余リスクは許容できるか: [はい | いいえ]
- 措置の承認者: [名前、役割]
- 監督機関との協議が必要か: [はい | いいえ]
- 見直し日: [YYYY-MM-DD]