「ミスを許さない手順書」を作ってみた 〜 個人的にはこれ以上できることはあまりなさそう/20260827-ssmjp-operation-procedure-update

ssmonline #53 での発表資料です。

(運用設計ラボ合同会社 波田野 裕一)

Transcript

1. 「ミスを許さない手順書」を作ってみた 〜 個人的にはこれ以上できることはあまりなさそう ssmjponline #53 運用設計ラボ合同会社 シニアアーキテクト 波田野 裕一 2026-04-17 Operation Lab 運用設計ラボ 1
2. あんた誰? 画: ぼへぼへさん https://qiita.com/bohebohechan/items/891120175efc1b3cc7c4 AWS Samurai 2017 (個人) AWS Samurai 2020 (CLI専門支部) AWS Community Hero JAWS-UG CLI専門支部 支部長 JAWS-UG 朝会 運営 JAWS-UG アーキテクチャ専門支部 運営 JAWS-UG IoT専門支部 設立メンバー Operation Lab 運用設計ラボ 2
3. 発表者の運用設計経験と得意領域 自社向け運用 得意な領域 自社情シス運用 自社サービス運用 ネットワーク管理 通信キャリア・ISP UNIXサーバ管理 ASP (ECサイト) 情シス運用 不得意な領域 サービス運用 (経験なし) 公共系Webシステム アウトソーシング MSP 他社向け運用 Operation Lab 運用設計ラボ 3
4. ssmjpで運用手順書のはなし (5年ぶり3回目?) 今日時点でview数が17kくらい 今日時点でview数が1kくらい Operation Lab 運用設計ラボ 4
5. アジェンダ 1. 「正しい」運用手順書とは? 2. 手順書のアンチパターンに対応するための考え方 3. 運用手順書の設計思想 4. 「ミスを許さない手順書」へ 5. まとめ Operation Lab 運用設計ラボ 5
6. 「正しい」運用手順書とは? Operation Lab 運用設計ラボ 6
7. 2018-11-06 「正しい」運用手順書とは? ssmjp 1. 論理的に「正しい」 レベル1: 論理的 2. 実質的に「正しい」 レベル2: 合目的的 3. 読み手にとって「正しい」 レベル3: 伝承的 レベル2までは訓練次第で習得可能 Operation Lab 運用設計ラボ 7
8. 2018-11-06 「正しい」運用手順書 レベル1 ssmjp レベル1: 論理的 論理矛盾や論理的な欠陥が存在しない手順書 • 手順が論理的に正しく、その通りに実施していれば、 論理上の正しい結果になるはずである。 論理矛盾や論理的な欠陥が存在する手順書 • 手順が論理的に正しくなければ、手順書通りに実施して も論理的に正しい結果にはならない。 • 分岐条件や共通手順(パーツ)は、論理矛盾を生みやすい ここでは「目的に合致」(レベル2)までは求めない • 分岐条件の無い手順書や、共通手順(パーツ)を使用し ない手順書は、論理がシンプルで確認しやすい。 まずは、論理的な手順書を書けることが第一歩 • 時間の経緯とともに修正がつみかさなり発生 複雑な分岐や不適切な共通化が事故が生む Operation Lab 運用設計ラボ 8
9. 2018-11-06 「正しい」運用手順書 レベル2 ssmjp レベル2: 合目的的 手順書通りにやれば、本来の目的を果たせる手順書 • 手順が意味論的に正しく、その通りに実施していれ ば、目的に合致した正しい結果になるはずである。 手順書通りにやっても、目的を果たせない手順書 • 手順が意味的に正しくなければ、手順書通りに実施しても 正しい結果(合目的)にはならない。 • 論理的ではない手順書や、アドホックに作成した手順書は 意味的な不整合と致命的な結果を生みやすい。 ここでは「目的に合致」(レベル2)まで求める • 前提条件と完了条件が明確に定義され、両者を適切に 橋渡しされた手順書は、目的から逸れにくい。 合目的的な手順書を書けるようにレベルアップ 「手順通りにやったのに事故が起きる」 Operation Lab 運用設計ラボ 9
10. 2018-11-06 「正しい」運用手順書 レベル3 ssmjp レベル3: 伝承的 読み手が手順書を正確に理解し、 読み手が手順書を正確に理解できず、 記述の真意を容易に把握することができる手順書 記述の真意を把握することが困難な手順書 • 読み手の物理的・精神的コストが適正で、スキルに見合った記述 であれば、概ね正しい意図を安定的に伝達できるはずである。 • 読み手の物理的・精神的コストが過剰で、スキルを想定しない記 述では、意図は正しく伝わらない。 • 読み手が理解しやすい手順書は、引き継ぎも容易になり、更に 現場へ手順書の保守を移管しやすい。 • 読み手が理解できない手順書は、引き継ぎ不可能であり、運用 現場において伝承し続けていくことはできない。 (これがなかなか難しい....) 伝承的な手順書を書けるようにレベルアップ (その手順書を見て学び育つ人が居れば最高) 「わかる人にわかる手順書」は引き継げない わからない人には「さっぱりわからない」 Operation Lab 10 運用設計ラボ
11. 目指す運用手順書のドキュメントとしてのレベル サービス価値 (ビジネス) 2021-08-10 ssmjp ゴール像 1. 論理的に「正しい」 レベル1: 論理的 論理矛盾や論理的な欠陥が存在しない手順書 2. 実質的に「正しい」 レベル2: 合目的的 手順書通りにやれば、本来の目的を果たせる手順書 このあたりを目指している 3. 読み手にとって「正しい」 レベル3: 伝承的 読み手が手順書を正確に理解し、 記述の真意を容易に把握することができる手順書 論理的に「正しくない」手順書は 「手順の途中で迷子」になって事故が起きる 実質的に「正しくない」手順書は 「手順通りにやった」のに事故が起きる 読み手にとって「正しくない」手順書は 「さっぱりわからない」ので引き継げない Operation Lab 11 運用設計ラボ
12. 波田野の考える「手順書作り」 2021-08-10 ssmjp 1. 不安定な運用業務を安定化させるための事業継続活動 2. 暗黙知を「明示的な知識」に変換する知的財産活動 3. ロジックと順序による「論理的な正しさ」を組み上げるプログラミング活動 どんな手順書作成もこの3つの側面を持つ、と考える Operation Lab 12 運用設計ラボ
13. 「運用手順書」の隠れた役割1. ノイズ除去 実は、運用自動化に不要な「ノイズ」の除去 という大きな役割が、運用手順書にはある。 不要となった分岐、曖昧な条件、無意味な確認など 「運用自動化」へのノイズフィルタ 社内制手運用 運用の定型化 運用自動化 標準化レベル 低 標準化レベル 中 標準化レベル 高 個々人が独自 手順書レベル コードレベル Operation Lab 13 運用設計ラボ
14. 「運用手順書」の隠れた役割2. ストーリの保持 運用自動化で失なわれがちな時系列(ストーリ)を残す という大きな役割が、運用手順書にはある。 特に「宣言型の記述をするツール」で失なわれやすい情報 「自動化された業務」を「手動化」するときに必須な情報 「運用自動化」前の時系列情報 社内制手運用 運用の定型化 運用自動化 標準化レベル 低 標準化レベル 中 標準化レベル 高 個々人が独自 手順書レベル コードレベル Operation Lab 14 運用設計ラボ
15. 手順書のアンチパターンに対応するための考え方 Operation Lab 15 運用設計ラボ
16. 手順書のアンチパターン レベル1: 論理的 非論理的 レベル2: 合目的的 非合目的的 手順書通りにやっても、目的を果たせない手順書 論理矛盾や論理的な欠陥が存在する手順書 • 手順が論理的に正しくなければ、手順書通りに実施して も論理的に正しい結果にはならない。 • 手順が意味的に正しくなければ、手順書通りに実施しても 正しい結果(合目的)にはならない。 • 分岐条件や共通手順(パーツ)は、論理矛盾を生みやすい • 論理的ではない手順書や、アドホックに作成した手順書は 意味的な不整合と致命的な結果を生みやすい。 • 時間の経緯とともに修正がつみかさなり発生 複雑な分岐や不適切な共通化が事故が生む 「手順通りにやったのに事故が起きる」 Operation Lab 16 運用設計ラボ
17. 手順書のアンチパターンを避ける: 論理的 レベル1: 論理的 非論理的 「分岐」と「共通化」を混ぜない 複雑な分岐や不適切な共通化が事故が生む 「論理」をシンプルにする 分岐 シナリオ層 共通化 ファンクション層 機能 (task) 機能 (task) 機能 (task) 機能 (task) 機能 (task) Operation Lab 17 運用設計ラボ
18. 手順書のアンチパターンを避ける: 合目的的 レベル2: 合目的的 非合目的的 「目的」を「完了条件」に組込む 「手順通りにやったのに事故が起きる」 「前提」を 「事前条件」に組込む 「前提」を「事前条件」に組込む 機能 (task) 「目的」を 「完了条件」に組込む ホーア論理 関数(f)が常に有限時間に完了する場合、 事前条件と完了条件の間に矛盾が無い 正確な表現(全正当性)は、 「前提条件Pが満たされた状態でプログラムFを実行すると、必ずプログラムは終了し、終了時には事後条件Qが満たされる」 Operation Lab 18 運用設計ラボ
19. まとめ: 手順書のアンチパターンを避ける 「分岐」と「共通化」を混ぜない 「論理」をシンプルにする 分岐 シナリオ層 共通化 ファンクション層 機能 (task) 機能 (task) 「目的」を「完了条件」に組込む 機能 (task) 機能 (task) ホーア論理 機能 (task) 「矛盾」を回避する 「前提」を「事前条件」に組込む Operation Lab 19 運用設計ラボ
20. 運用手順書の設計思想 Operation Lab 20 運用設計ラボ
21. 運用手順書の設計思想 1. 低コンテキスト • 途中で失敗しても最初からやり直す必要がないように、手順全体がハイコンテキストにならないようにする。 • 手順全体は「低コンテキストな個別手順」の集合とする。 2. 個別手順の独立性を高める • 全く同じ手順が実務で必要になることは稀なので、一部を抜き出して利用できるようにする。 • 抜き出して利用する粒度で作成する。 シナリオ タスク 一回のハンズオン (手順全体) ハンズオン内の シナリオ build区分タスク ハンズオンの場合は タスク タスク タスク タスク タスク build & cleanup両方 自社作業の場合は build or cleanupの一方 個別手順 cleanup区分タスク タスクの「並び順」で手順全体のコンテキストを表現している。 (途中で止めても容易に再開できる。) たまに「1本道の手順書の方が良い」という方がいますが、ハイコンテキストになるため中断したり迷子になると詰みます。 Operation Lab 21 運用設計ラボ
22. 運用手順書の設計思想 3. 個別手順は、可能な範囲で同じ構造とする。 • • タスク 構造が標準化された手順は、読み手にとって先の予測が付きやすく読みやすいため、極力揃える。 手順書の読みやすい「リズム」は実務でもかなり有効なため、実務に近いリズムを目指す。 I/O (インプット&アウトプット) ヘッダ 目的 事前条件と完了条件 対象 標準時間 前提条件 変数の確認 変数の確認: インプット コマンド: 設定値の指定 (プロパティ宣言部) 「独立したオブジェクト」 としての手順書 必要なリソース 設定値の指定 設定値の確認 処理の実行 (メソッド実行部) 前処理 事前条件の確認 主処理 後処理 「リズム」を刻む単位 アウトプット 結果(例): 完了条件の確認 Operation Lab 22 運用設計ラボ
23. 運用手順書の3階層 シナリオ 一回のハンズオン (手順全体) シナリオにおける「タスクの並び順」で手順全体のコンテキストを表現。 (途中で止めても容易に再開できる。) タスク 完全版と簡易版の2種類 タスク 完全版と簡易版の2種類 ハンズオン内の個別手順 独立性の高い「手順オブジェクト」で他の手順と疎結合で低コンテキスト。 (ヘッダ、プロパティ宣言部、メソッド実行部の3セクションで構成される。) 一つのタスクは、CRUDの一つしか扱わない I/O シナリオ I/O ハンズオン内の実際の入出力のセット 多様なタスクから呼び出される全ての手順書の基本構成要素。 (手順書の品質と多様性を決定付ける最も重要な要素) Operation Lab 23 運用設計ラボ
24. 参考: タスクの構成要素 (例) s3-bucket-create.rst 人が書くドキュメント 人が更新するドキュメント _aim-s3-bucket-create.txt _what-s3-bucket-create.txt _when-s3-bucket-create.txt _who-s3-bucket-create.txt 目的 Why 対象 What When 前提条件 Who 事前条件と完了条件 ドキュメントディレクトリでシェルスクリプトを実行すると 自動生成されるので、必要なところだけ変更する _condition-s3-bucket-create.txt _display-condition-s3-bucket-create.txt _postcondition-s3-bucket-create.txt _precondition-s3-bucket-create.txt 後処理 前処理 設定値の指定 (プロパティ宣言部) 機械が書くドキュメント s3-bucket-create-body-all.txt s3-bucket-create-body-parameter-task.txt task表示用 (2種類) s3-bucket-create-assumption.txt s3-bucket-create-header.txt ヘッダー表示用 s3-bucket-create-parameter.txt プロパティ宣言部 (表示部) s3-bucket-create-task.txt メソッド実行部 (表示部) 前提条件 Where _parameter-input-s3-bucket-create.txt _parameter-postcheck-s3-bucket-create.txt _resource-s3-bucket-create.txt 設定値の指定 設定値の確認 必要なリソース 処理の実行 (メソッド実行部) _task-s3-bucket-create.txt How 機械が書き換えるドキュメント _de nes-xxx.txt Operation Lab 24 fi 運用設計ラボ
25. 「ミスを許さない手順書」へ Operation Lab 25 運用設計ラボ
26. 目指す運用手順書の構造化レベル 従来 今後 構造化レベル0 構造化レベル1 構造化レベル2 単構造手順 オブジェクト化 手順 自動化仕様手順 一つの手順書に 全ての手順が 書かれている 独立手順 独立手順 独立手順 独立手順 手順関数 パラメータ 手順関数 指定手順 独立手順 独立手順 手順関数 独立手順 独立手順 手順関数 変数がグローバル化する 変数をローカル化しやすい 変数の指定を集約し、レビューしやすい 矛盾が発生しやすい 矛盾を排除しやすい 手順部分の関数化により、自動化しやすい 変数の指定が煩雑になりがち 作成の難度は高い (保守は容易) 途中でターミナルを閉じると やりなおし Operation Lab 26 運用設計ラボ
27. 「パラメータ指定部」と「実行部」の分離 (従来) シナリオ シナリオヘッダ タスク ヘッダ 目的 事前条件と完了条件 対象 標準時間 前提条件 設定値の指定 (プロパティ宣言部) 必要なリソース 設定値の指定 設定値の確認 タスクリスト 処理の実行 (メソッド実行部) 前処理 事前条件の確認 主処理 後処理 完了条件の確認 Operation Lab 27 運用設計ラボ
28. 「パラメータ指定部」と「実行部」の分離 (今後) シナリオ タスク シナリオヘッダ ヘッダ シナリオ全ての設定値指定 (プロパティ宣言部) 作業前日 必要なリソース 目的 事前条件と完了条件 対象 標準時間 前提条件 設定値の指定 設定値の確認 処理の実行 (メソッド実行部) 作業当日 タスクリスト 前処理 事前条件の確認 主処理 後処理 完了条件の確認 Operation Lab 28 運用設計ラボ
29. 「メソッド実行部」のフラグチェック (従来) 処理の実行 (メソッド実行部) 前処理 事前条件の確認 $? が 0(OK) か 0以外(NG) を表示していた 主処理 後処理 プロンプトに 完了条件の確認 Operation Lab 29 運用設計ラボ
30. 「メソッド実行部」のフラグチェック (今後) 処理の実行 (メソッド実行部) 前処理 事前条件の確認 主処理 後処理 全コマンドについてフラグチェックをするようにした。 完了条件の確認 Operation Lab 30 運用設計ラボ
31. 「メソッド実行部」のフラグチェック (今後) 処理の実行 (メソッド実行部) 前処理 事前条件の確認 主処理 後処理 完了条件の確認 全てのフラグが正しくないと コマンドが実行されない オペミスを起こすのが困難 Operation Lab 31 運用設計ラボ
32. これって結局: 「メソッド実行部」= シェル関数 プロパティ宣言部 = シェル関数への引数 処理の実行 (メソッド実行部) 前処理 事前条件の確認 主処理 後処理 = 事実上のシェル関数 完了条件の確認 完了条件チェックの戻り値が全て0だったら、 強制的にターミナルを閉じちゃう = 事実上のシェル関数の戻り値 (シェル変数の汚染によるミス防止目的) Operation Lab 32 運用設計ラボ
33. まとめ Operation Lab 33 運用設計ラボ
34. まとめ サービス価値 (ビジネス) ゴール像 1. 論理的に「正しい」 レベル1: 論理的 論理矛盾や論理的な欠陥が存在しない手順書 2. 実質的に「正しい」 レベル2: 合目的的 手順書通りにやれば、本来の目的を果たせる手順書 このあたりを目指している 3. 読み手にとって「正しい」 レベル3: 伝承的 読み手が手順書を正確に理解し、 記述の真意を容易に把握することができる手順書 「分岐」と「共通化」を混ぜない シナリオで分岐を扱う 「目的」を「完了条件」に組込む タスク(シェル関数)で共通化 「前提」を「事前条件」に組込む ホーア論理 「矛盾」を回避する Operation Lab 34 運用設計ラボ
35. 微妙な悩み 教育効果はこっち 構造化レベル0 構造化レベル1 構造化レベル2 単構造手順 オブジェクト化 手順 自動化仕様手順 一つの手順書に 全ての手順が 書かれている 独立手順 独立手順 独立手順 独立手順 手順関数 パラメータ 手順関数 指定手順 独立手順 独立手順 手順関数 独立手順 独立手順 手順関数 変数がグローバル化する 変数をローカル化しやすい 変数の指定を集約し、レビューしやすい 矛盾が発生しやすい 矛盾を排除しやすい 手順部分の関数化により、自動化しやすい 変数の指定が煩雑になりがち 作成の難度は高い (保守は容易) 途中でターミナルを閉じると やりなおし Operation Lab 35 運用設計ラボ
36. 参考: 過去の発表資料 過去の発表資料は OpsLab.jp というサイトに置いてあります。 https://www.opslab.jp/publish/ Operation Lab 36 運用設計ラボ
37. Operation 運用設計Lab http://www.operation-lab.co.jp/ Operation Lab 37 運用設計ラボ