商用リリース手順書作成をハックする — openpyxlでの構造解析と「当日作業だけ」を抽出する設計

はじめに

商用リリースの手順書作成って、地味な割に事故ったら一発で延期になる、リスクと労力が釣り合わない工程です。

• STG検証は完璧に通した
• でも当日手順書を書く段階で疲弊して、書式合わせや切り戻し手順がおざなりになる
• レビューで「フォーマットが標準と違います」「切り戻しが薄いです」と差し戻し

何より辛いのが、**「書式の体裁を合わせるために何時間も溶ける」**こと。これを openpyxl による構造解析と、AI を使った「当日作業だけの抽出」という2軸でハックした記録を共有します。

軸は1つだけ。「書式合わせより、抽出ルールこそが品質を決める」。

Part 1: STG手順から「当日作業だけ」を抽出する

問題発見: STG手順をそのまま流用すると事故が起きる

STG検証で動かした手順書をベースに当日手順書を作るのが普通の流れですが、ここに罠があります。STG手順には、

• スキーマ作成
• IAMロールやサービスアカウントの権限設定
• バケットや Datastream リソースの作成
• 検証用テストデータの投入

など、商用環境ではリリース時点で既に整っているはずの事前準備が大量に混ざっています。これを当日手順書に残したまま流すと、

• 「あれ、このスキーマもう作ってあるはずなのに、CREATE文流していいの？」と当日判断を迫られる
• 「権限変更の手順、本当に今日やるんですか？」と現場で迷う
• 既存リソースを上書きして事故る

という事態になります。

解決: 「商用環境に既に存在するか」軸でふるい分け

抽出ルールはシンプルに1軸で機械的にやります。

ステップの性質	商用環境で既に存在する？	当日手順書への扱い
スキーマ／DB作成	YES（事前構築済み）	除外
IAM ロール／権限設定	YES（事前構築済み）	除外
バケット作成	YES（事前構築済み）	除外
dump 取得・投入	NO（当日のデータ）	採用
Datastream／Dataflow 実行	NO（当日のジョブ）	採用
タイムスタンプ補正	NO（移行データへの後処理）	採用
shadow テーブル削除	NO（移行ツール生成物の片付け）	採用
sequences 投入	NO（移行データに紐づく後処理）	採用

このふるいだけで、STG手順から当日実施は16ステップまで圧縮できました。

各ステップに必ず付ける「3点表記」

抽出した当日ステップには、必ず以下3点をセットで書きます。

• 実行順序: 前ステップとの依存関係（並列可か直列か）
• 実行場所: どの環境・どの端末から実行するか（ローカル？踏み台？Cloud Shell？）
• 確認ポイント: 成功判定はどのコマンド・どの画面・どの値で行うか

特に確認ポイントを書いていない手順は、当日に「これ、進めていいんですかね…」と詰まる原因No.1です。例えば「Dataflow ジョブを起動」だけだと、ジョブが起動したことをどう確認すればいいのか曖昧。「ジョブステータスが Running で、ステージ別の処理件数が増加していること」まで書いて初めて手順として完結します。

Part 2: openpyxl で既存Excelテンプレを構造解析する

問題発見: 手動でフォーマットを合わせると100%崩れる

チームには「Secret Manager 更新手順書」のような社内標準テンプレが既にあります。書式・列幅・結合セル・色塗り・罫線まで決まっていて、これに合わせないとレビューが通りません。

最初は手動でテンプレをコピーして、新規ステップを書き換えて…とやっていましたが、列幅がずれる・結合セルが解除される・フォントが微妙に違うという事象が必発。レビュアに「マージセルが3行目だけ違いますね」と指摘される度に虚無に襲われます。

解決: openpyxl で「解析」と「生成」を 2フェーズに分離する

突破口は、openpyxl でテンプレを構造データに分解し、中間JSON化してから生成スクリプトに渡すという2フェーズ設計でした。

[フェーズA: 解析]
  サンプルExcel ─ openpyxl ─→ template_structure.json
                              （セル位置・マージ範囲・列幅・書式）

[フェーズB: 生成]
  template_structure.json + 手順データ
  ─ openpyxl ─→ 完成版Excel

この中間JSON化が重要です。生成スクリプトをテンプレに直接依存させると、テンプレが少し変わるたびに生成スクリプトを書き換えることになります。中間JSONを噛ませると、テンプレ変更時は解析スクリプトだけ流し直せばよく、生成スクリプト側は触らずに済みます。

openpyxl で押さえる4要素

テンプレ再現で必ず抽出すべき要素は4つです。

要素	openpyxl での取得	取りこぼすと何が起きるか
マージセル範囲	ws.merged_cells.ranges	「項目名」セルが分割されてレイアウトが崩れる
列幅	ws.column_dimensions[col].width	列がはみ出して印刷時に切れる
書式（フォント・塗り・整列・罫線）	cell.font / cell.fill / cell.alignment / cell.border	見た目の統一感がなくなり「別物」扱いされる
行高	ws.row_dimensions[row].height	折り返し前提のセルで内容が見切れる

逆に言うと、この4つさえ押さえれば社内標準テンプレはほぼ完全再現できます。書式の Style をいじり始めると沼ですが、上記4要素の「コピー」だけで済ませると工数が劇的に減ります。

なぜ「バイナリExcelを直接いじらない」のか

.xlsx の正体は zip + XML なので、頑張れば直接編集できます。実際試しました。が、すぐに諦めました。理由は3つ。

1. 意図せぬ破損のリカバリコストが高い: Excelが「ファイルが破損しています」と言い出すと、社内テンプレの差分原本を探すところからリカバリが始まる
2. マージセルやスタイルの参照関係がXML上で分散: 1つの書式変更が複数XMLファイルに波及することがあり、追跡が辛い
3. openpyxl の方が結局速い: 一度2フェーズ設計を組めば、テンプレが変わってもJSON再生成で済む

「便利そうだから直接いじる」より、ライブラリに乗っかったほうが最終的な工数が少ないケースの典型です。

Part 3: AIで「テキスト手順 → 7カラム構造化 → Excel」を回す

問題発見: LLMに「Excelにして」と頼むだけだと崩れる

テキストで書いた手順を LLM に渡して「Excel化して」と言うと、構造がふわっとした出力が返ってきます。コードブロックに無理やり書式を再現しようとして、結局openpyxlに食わせる前にもう一度整形が必要になる、というのを何度かやりました。

解決: 中間に「7カラム構造化テーブル」を必ず挟む

LLM にはExcel化を頼まない。代わりに、テキスト手順を以下の7カラムに分解する仕事だけを頼みます。

カラム	内容	抜けると何が起きるか
No	通し番号	順序逆転事故
手順サマリ	1行要約	目次が作れない
実施ユーザ	誰が実行するか	「これ自分の作業？」が当日発生
目的	なぜこのステップが必要か	飛ばしていいかの判断ができない
手順詳細（実行コマンド）	実行する具体コマンド／操作	コピペで動かない
結果想定	成功時に何が見えるべきか	成功判定が現場依存になる
備考	注意事項・前提条件	罠が暗黙知化する

このテーブルさえ作れれば、openpyxlの生成スクリプトに機械的に流し込めるようになります。LLMは構造化に強く、openpyxlは書式再現に強い。役割分担がきれいに切れます。

「結果想定」カラムは絶対に手を抜かない

経験上、現場で詰むのは99%「結果想定」が薄いステップです。

[Before] 結果想定: 「正常終了すること」
[After]  結果想定: 「ジョブステータスが Succeeded、出力ファイルが
                    gs://bucket/path/output.avro として作成されている、
                    ログに ERROR レベルの行が0件」

ここを書ききれていれば、当日「進めていいか」の判断は手順書を見るだけで完結します。LLM に分解させる段階で「結果想定が抽象的な場合は具体化して」と必ず指示するのがコツです。

AI出力を信用しすぎないためのチェック観点

LLM の構造化出力をそのまま Excel に流すと、たまにこんな事故があります。

• 実施ユーザ列が「運用者」「担当者」「オペレータ」と表記揺れ
• 手順詳細のコマンドが、もっともらしい架空のフラグになっている
• 結果想定が「成功すること」のような抽象トートロジー

これを潰すために、AI出力を Excel に流し込む前に人間が以下3点だけ確認します。

1. 実施ユーザの表記が統一されているか
2. 手順詳細のコマンドが、実際に STG で叩いたコマンドと一致しているか（履歴と突合）
3. 結果想定に具体的な値・ステータス名・ファイルパスが含まれているか

Part 4: 失敗できないリリースの最後の砦 — 切り戻し手順を「同じ粒度」で作る

問題発見: 切り戻し手順が薄いと、失敗時に詰む

対応手順だけ充実させて、切り戻し手順を「最悪はDB再構築でいいよね」みたいに雑に扱う現場は意外と多いです。が、当日の限られた停止枠で「再構築」を選んだらそのままSLA違反になります。

解決: 同じ7カラム構造で切り戻しも作る

今回は対応手順 19ステップに対し、切り戻し手順を 7ステップで作りました。同じ7カラム構造・同じExcelテンプレで生成しているので、レビュアの負担も対応手順とほぼ変わりません。

「対応手順より切り戻しが短い」のは、各ステップが戻すべき変更単位にまとまっているからです。例えば「Dataflow ジョブ起動 → ジョブ取消し」「PDML補正実行 → 逆方向のPDMLで再補正」のように、対応のN個のステップが、切り戻しのM個（M<N）にマッピングされる設計になります。

副次効果: 「戻せない作業」が浮き彫りになる

切り戻し手順を作る過程で、対応手順側の戻せない作業が必然的に浮き彫りになります。

• shadow テーブルの DROP は、戻すには再投入が必要
• sequences の INSERT は、現在値を変えると後続トランザクションに影響
• PDML 補正は、再度逆方向 PDML が必要だが冪等性に注意

これらは「切り戻し手順を書こうとして初めて気付く」タイプの設計課題で、対応手順だけ作っていると気付けません。切り戻し設計が対応手順設計のレビューフィードバックとして機能する、というのが副次効果です。

おわりに

商用リリース手順書の作成は、見方を変えると 3レイヤに分解できる作業です。

レイヤ	何をする	誰が一番強いか
抽出	STG手順から当日作業だけをふるい分け	人間（抽出ルール設計）
構造化	テキスト手順を7カラム表に分解	LLM
フォーマット再現	社内標準Excelテンプレに流し込む	openpyxl

それぞれが得意な箇所だけ担当するように分業させると、

• 体裁合わせの消耗 → openpyxl に任せて消滅
• テキスト→構造化の単純作業 → LLM に任せて圧縮
• 抽出ルール設計と最終チェック → 人間が集中

という分担になり、手順書作成の総工数を大幅に減らしつつ、品質はむしろ上がります。

最後にもう一度、この記事の縦軸を置いて締めます。

書式合わせより、抽出ルールこそが品質を決める。

商用リリース手順書で消耗している方の参考になれば幸いです。