ドキュメント定義マトリクス
図1: 開発フェーズの成果物・担当・更新タイミング
| ドキュメント | 何を定義するか | 誰が使うか | 変更コスト | 最重要度 |
|---|---|---|---|---|
| 変更管理記録 | 全変更要求の内容・申請者・影響評価・承認者・実施日の記録 | PM・PMO・監査時・ポストモーテム時 | 高 | ◎ 最重要 |
| マイグレーションスクリプト | DB状態の変更定義（スキーマ変更・データ変換・ロールバック） | DBA・BE・インフラ・本番リリース時 | 高 | ○ 重要 |
| IaCコード（Terraform等） | インフラ構成の宣言的定義（サーバ・NW・ストレージ・権限） | インフラ・全環境構築時 | 中 | ○ 重要 |
| CI/CDパイプライン定義 | ビルド・テスト・デプロイの自動化フロー | 全開発者・インフラ | 中 | ○ 重要 |
| ログ設計書（実装仕様） | ログレベル・フォーマット・出力先・含めるフィールド定義 | BE（実装）・インフラ（収集）・運用（参照） | 中 | ○ 重要 |
| 進捗報告書（定期） | 進捗状況・課題・予測完了日 | PM・ステークホルダー | 低 | △ 記録 |
| 課題エスカレーション記録 | エスカレーション経緯・判断根拠・対応結果 | PM・PMO | 低 | △ 記録 |
◎最重要ドキュメントの詳細
変更管理記録
何を定義するか：プロジェクト期間中に発生したすべての変更要求を追跡可能な形で記録する。変更の内容・申請者・申請日・影響評価（工数・スコープ・スケジュールへの影響）・承認者・承認日・実施結果の7項目が最低限必要だ。
なぜ変更コストが高いか：記録のないまま実施された変更は「なぜその機能が存在するのか」「誰が承認したのか」を後から追跡できなくなる。プロジェクト後半でスコープが膨らんだとき、変更管理記録がなければ誰も責任を取れない状態になる。
⚠️ 「小さな変更」こそ必ず記録する
スコープクリープは常に「小さな変更のつもり」から始まる。「ちょっとUIを変えるだけ」「フィールドを1つ追加するだけ」という変更が記録されず積み重なり、開発フェーズ後半で工数が跳ね上がるのが典型的なパターンだ。規模に関係なく全変更要求を変更管理記録に残す習慣を徹底する。
ログ設計は「ドキュメント」である
ログ設計書は「コードに埋め込まれる仕様」として、開発フェーズで必ず文書化する必要がある。
| 定義項目 | 内容 | なぜ重要か |
|---|---|---|
| ログレベル定義 | ERROR/WARN/INFO/DEBUGの使い分け基準 | レベルが統一されないと運用時にアラートが機能しない |
| 出力フォーマット | JSON構造・タイムスタンプ形式・文字コード | ログ収集ツール（Fluentd等）の設定に影響 |
| 必須フィールド | リクエストID・ユーザーID・処理時間・エラーコード | 障害時のトレーサビリティに直結 |
| 出力先 | ファイル/標準出力/ログサービス（CloudWatch等） | インフラの収集設定に影響 |
| 保持期間 | ログの保存期間・アーカイブポリシー | 法令・コンプライアンス要件と連動 |
💡 ログ設計をコードより先に書く
「ログは実装しながら考える」というアプローチは失敗する。実装者によってログの粒度・フォーマット・フィールドがバラバラになり、運用フェーズで障害解析に使えないログが大量に出力される。ログ設計書を先に書き、実装者が参照しながらログを埋め込む順序を守る。
IaCとCI/CDはなぜ◎でないか
IaCコードとCI/CDパイプライン定義は「○重要」に分類している。変更管理記録ほど変更コストが高くない理由は、これらはコードレビューのサイクルの中で自然に改善される性質があるためだ。一方、変更管理記録は「その時点での意思決定の根拠」を記録するものであり、後から補完できない。
| ドキュメント種別 | 後から補完できるか | 理由 |
|---|---|---|
| 変更管理記録 | ❌ できない | 「誰が・いつ・なぜ決定したか」はその時点でしか記録できない |
| IaCコード | △ 部分的に可能 | 現状の構成はコードで復元できるが、過去の変更経緯はgit logに依存 |
| CI/CDパイプライン | ○ 可能 | 現在のパイプラインを定義すれば再現可能。ただし過去の設計判断は失われる |
| ログ設計書 | △ 一部可能 | コードを読めばログの出力先・フォーマットはわかるが、「なぜそう設計したか」は失われる |
✅ 次のPARTへ