TL;DR
- 手順書の事故の多くは、操作ミスではなく「成功したか判断できないまま次に進んだ」ことから起きる
- 期待結果は「何を・どこで・どう見れば・何が出るか」まで書いて初めて機能する
- 実務でそのまま使える3パターン(完全一致 / 範囲・状態 / 差分比較)を紹介
「期待結果: 正常に完了すること」問題
手順書レビューで一番よく直すのがこれです。
| 手順 | 操作 | 期待結果 |
|---|---|---|
| 5 | systemctl restart nginx |
正常に再起動されること |
これ、期待結果を何も書いていないのと同じです。深夜2時の作業者はこう悩みます。
「コマンドは通った。…で、"正常"って何を見れば分かるんだ?」
判断材料がないと、人は「エラーが出てないからヨシ」で次に進みます。実はプロセスが上がっていなくても、です。そして3手順先で発覚し、どこまで戻ればいいか分からなくなる——期待結果の欠陥は、発生地点と発覚地点がズレるのが厄介なところです。
期待結果の4要素
機能する期待結果には、この4つが入っています。
- 何を: 確認対象(プロセス、ログ、ステータスコード、画面)
- どこで: 確認コマンド or 確認画面(コピペできる形で)
- どう見れば: 出力のどの部分に注目するか
- 何が出るか: 具体的な値・文字列(できれば実機の出力例を貼る)
先ほどの例を直すとこうなります。
| 手順 | 操作 | 期待結果 |
|---|---|---|
| 5 | systemctl restart nginx |
systemctl status nginx で Active: active (running) と表示される。since が作業時刻以降に更新されている |
「作業者が今この場でYes/Noを判定できるか」が合格ラインです。
コピペで使える3パターン
パターン1: 完全一致型(コマンド出力)
【操作】systemctl restart nginx
【期待結果】
確認コマンド: systemctl status nginx
期待値: Active: active (running)
注目点: since の時刻が作業時刻以降であること
一番基本の型。ポイントは確認コマンドを操作と分けて書くこと。操作コマンドの終了コードだけでは「起動しかけて即死んだ」を検出できません。
パターン2: 範囲・状態型(数値やリソース)
【操作】アプリケーションサーバ再起動後、5分間経過観察
【期待結果】
確認コマンド: curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health
期待値: 200(503や接続エラーはNG)
補足: CPU使用率が定常時レンジ(10〜30%)に収まっていること。80%超が5分続く場合は異常
「正常範囲」をレンジで書くのがコツです。定常時の値は作業前(事前確認)に採取しておくと、この期待結果が書けるようになります。
パターン3: 差分比較型(設定変更・バージョンアップ)
【操作】パッケージ更新: dnf update openssl -y
【期待結果】
確認コマンド: rpm -q openssl
期待値: openssl-3.2.2-x.el9(更新後バージョン)
比較元: 事前確認で採取した openssl-3.0.7-x.el9 から変わっていること
併せて確認: 依存サービス(httpd)が Active: active のままであること
変更系の作業は「変わったこと」と「壊れていないこと」の2つセットで期待結果になります。片方だけだと、更新は成功したがサービスが巻き添えで落ちた、を見逃します。
アンチパターン集
- ❌ 「正常に完了すること」— 判定基準ゼロ
- ❌ 「エラーが出ないこと」— 何も出ない=成功とは限らない(サイレント失敗)
- ❌ 「問題ないことを確認」— "問題"の定義が作業者任せ
- ❌ 期待結果に操作コマンドの出力だけを書く — 確認コマンドを別に用意する
- ❌ 出力例が古いバージョンのまま — 実機で採取し直す
期待結果を書く習慣をつける一番の近道
「操作と期待結果をセットで書く」を強制される型で書き始めることです。
この型に沿って入力するだけで手順書ができるWebツールを作りました。手順ごとに「操作」と「期待結果」が必ずペアになる構造で、埋めていくだけで上の3パターンが自然に書けます。無料で、データはブラウザの外に出ません(手順書は機密の塊なので、ここは徹底しました)。
👉 手順書メーカー: https://kazu-apps.github.io/tejun-maker/
Markdown出力にも対応しているので、生成した手順書はそのまま社内Wikiに貼れます。感想・改善要望お待ちしています。