ベストプラクティスの全体像
運用ドキュメントのベストプラクティスは「ツール」「プロセス」「文化」の3層で考えます。 ツールだけ整えても文化が伴わなければ継続しません。文化だけあってもツールとプロセスがなければ属人的になります。
| 層 | 内容 | 本記事での対応箇所 |
|---|---|---|
| ツール層 | Gitリポジトリ・CIパイプライン・Pythonスクリプト | § Git管理 / § CI統合 |
| プロセス層 | PR文化・レビューチェックリスト・更新トリガー | § ピアレビュー文化 / § ヒヤリハット習慣化 |
| 文化層 | 「ドキュメントは誰でも更新できる」「Draft OK」の認識 | § チームへの段階的導入 |
Git によるバージョン管理
手順書をGitで管理する最大のメリットは「変更履歴が自動的に残る」ことです。
更新履歴をMarkdown内に手書きする必要がなく、git logで誰がいつ何を変えたかが追跡できます。
また誤った手順書を誤ってマージしてしまった場合でもgit revertで元に戻せます。
手順書はアプリケーションコードと同じリポジトリに含めることを推奨します。 理由は「コード変更と手順書更新を同一PRにまとめられる」ためです。 インフラ変更のPRが「手順書の更新を含む」ことをマージ条件にすることで、陳腐化を防げます。
コミットメッセージの規約例：
| プレフィックス | 用途 | 例 |
|---|---|---|
docs(手順書名): |
手順書の内容更新 | docs(deploy): ロールバック手順を追加 |
fix(手順書名): |
誤りの修正 | fix(backup): DB名の命名規則を修正 |
feat(手順書名): |
新しい手順書の追加 | feat(incident): インシデント対応手順を追加 |
chore(docs): |
ヒヤリハット記録・更新履歴の記入 | chore(docs): ヒヤリハット記録を追記 (2026-06-27) |
ピアレビュー文化の醸成
コードレビューの文化がチームに定着しているのと同様に、 ドキュメントレビューもプロセスとして組み込む必要があります。 「完成したら共有する」ではなく「DraftでもPRを作る」習慣が重要です。
⚠️ 「レビューを依頼する敷居」を下げることが最重要
「完璧でないと見せてはいけない」という心理が手順書のレビュープロセスを止めます。[WIP] や [Draft] というPRラベルを使い、「まだ完成していないけどフィードバックを求めている」状態でPRを出せる文化を作ることが先決です。
ピアレビューを定着させるための施策：
- レビューを評価指標に含める — コードレビューと同様に、ドキュメントレビューも業績評価の一要素とする
- 「初めて読む人」がレビュアーになるローテーション — 毎回同じ人がレビューすると、共通の暗黙知が省略されやすくなる
- ドライランをレビューの必須条件にする — 重要な手順書はステージング環境でのドライラン結果をPRのコメントに含める
- PRテンプレートにレビューチェックリストを含める —
.github/PULL_REQUEST_TEMPLATE/docs.mdに自動的にチェックリストが挿入されるようにする
CI による品質保証の自動化
前記事「Python で手順書を自動化する」で解説した5つのスクリプトをCI/CDパイプラインに組み込むことで、 手動レビューが担う範囲を明確に絞り込めます。 CIが自動的にチェックする項目は、レビュアーが人間として確認すべき「内容の正確さ・わかりやすさ」に集中できます。
| チェック種別 | CI自動化 | 人間のレビュー |
|---|---|---|
| 必須セクションの有無 | ✅ validate.py で自動検出 | 不要 |
| リンク切れ | ✅ check_links.py で自動検出 | 不要 |
| コマンドの正確さ | ❌ 自動化困難 | ドライランで確認 |
| 内容の理解しやすさ | ❌ 自動化困難 | 「初めて読む人」がレビュー |
| ロールバック手順の存在 | ✅ セクション検証で自動確認 | 内容の妥当性は人間が確認 |
ヒヤリハット記録の習慣化
ヒヤリハット記録を仕組みとして手順書に組み込んでも、 記録する文化がなければ記録欄は空白のままです。 「記録することへの心理的ハードル」を下げる工夫が必要です。
ヒヤリハット記録を習慣化するための施策：
| 施策 | 内容 | 効果 |
|---|---|---|
| 「作業が完了したらヒヤリ欄を確認する」というリマインダー | 手順書の末尾に「作業完了後、ヒヤリハット記録欄を確認してください」と明記 | 記録のタイミングが明確になる |
| 「件数が多くても問題ない」という認識共有 | ヒヤリハット記録は「失敗の証拠」ではなく「改善の材料」であることをチームで共有 | 記録への心理的ハードルが下がる |
| ヒヤリハット対応の可視化 | 週次集計レポートで「対応済み件数」を明示。記録が改善に繋がることを実感できる | 記録することの意義を体感できる |
| ヒヤリハット起因の改善を称える | 「このヒヤリハット記録のおかげで手順書が改善された」事例を共有する | 記録が評価される文化ができる |
✅ ヒヤリハット記録は「証言者保護」の文化と同じ
ヒヤリハットを記録した人を責めるのではなく、「記録してくれたことで皆が安全になった」と捉える文化が必要です。記録者を評価し、記録しないことをリスクとして認識する組織になることが、ハインリッヒの法則を実践的に活用することです。
チームへの段階的導入ロードマップ
手順書文化を一気に導入しようとすると、抵抗感から定着しません。 以下の4ステップで段階的に導入することを推奨します。
Week 1-2: まず一つ書く
チームで「一番よく実行する作業」を一つ選び、担当者が手順書を書く。完璧でなくてよい。Draftとして共有してフィードバックを受ける。ここで「書ける」という自信と「便利だ」という実感を得ることが目的。
Month 1: レビュープロセスを確立する
手順書のレビューをコードレビューと同じPRプロセスに乗せる。レビューチェックリストを作成し、最初の数件は手厚くサポートする。CIへの①②スクリプト組み込みもこの段階で行う。
Month 2-3: カバレッジを広げる
重要な運用作業の手順書を網羅する。「手順書なしでは本番作業禁止」というルールを段階的に導入する。ヒヤリハット記録欄を追加し、集計④スクリプトを週次で動かし始める。
Month 4 以降: 改善サイクルを回す
ヒヤリハット記録を元に定期的な改善を行う。四半期レビューを定例化する。ドキュメント成熟度を定期的に評価し、次のレベルへの改善目標を設定する。
ドキュメント成熟度モデル
組織のドキュメント文化の現在地を把握し、次のステップを明確にするために、 5段階の成熟度モデルを定義します。
| レベル | 状態 | 特徴 | 次へのアクション |
|---|---|---|---|
| Lv.1 なし | 手順書が存在しない | すべてが担当者の頭の中。作業の再現性がない | まず一つの作業に対して手順書を作成する |
| Lv.2 個人管理 | 個人が手順書を持っている | 個人のPC・ローカルフォルダに保存。共有されていない | Gitリポジトリまたは共有ツールで一元管理する |
| Lv.3 共有済み | チームで手順書を共有している | 共有されているが更新が不定期。レビューがない | PRベースのレビュープロセスと更新トリガーを導入する |
| Lv.4 プロセス化 | レビュー・更新が仕組み化されている | PRレビュー・CIチェック・更新トリガーが整備されている | ヒヤリハット記録を習慣化し、改善サイクルを動かす |
| Lv.5 自律改善 | ドキュメントが自律的に改善される | ヒヤリハット→改善→手順書更新のサイクルが自動的に動く | 他チームへの展開・自動化の拡張 |
💡 現在のレベルを正直に評価する
「うちはLv.3くらいかな」と感じた場合、Lv.5を目指すのではなくLv.4に上がるための一つのアクションだけを設定します。成熟度を一段階上げることに集中することが、長続きするアプローチです。
シリーズ全体のまとめ
本シリーズ「運用ドキュメント」では6つの記事を通じて、 運用手順書の必要性から実装、そしてチームへの定着まで解説しました。
| 記事 | 主な内容 |
|---|---|
| ヒヤリハット法則 | ハインリッヒの法則（1:29:300）と手順書改善サイクルの関係 |
| なぜ手順書を作るのか | 属人化・インシデント・コンプライアンス・継続改善の4つの理由 |
| 手順書の8つの要素 | 目的〜更新履歴まで、手順書を構成する要素とMarkdownテンプレート |
| 手順書の重点ポイント | ピアレビュー・陳腐化防止・Git管理・CIによる品質自動チェック |
| Python 自動化ツール | リンクチェック・セクション検証・テンプレート生成・ヒヤリハット集計の実装 |
| ベストプラクティス（本記事） | 3層（ツール・プロセス・文化）と段階的導入ロードマップ |