「自動化したいから現状を整理する」をやめて、「まず現状をそのまま見る」に書き換えた話

組織のリリース手順書を200件以上分析して、デプロイパターンを可視化するというドキュメントを書いていました。

最初は「自動化したいから、その前段として現状を整理する」というスタンスで書き始めたのですが、途中で違和感が出てきて、本体ドキュメントから自動化文脈を丸ごと削除しました。「現状こうなっている」だけのドキュメントに作り直した、という話です。

技術的な作業ログでもありますが、ドキュメント設計のスタンスをいったん書き換えた記録、として読んでいただければと思います。

背景：手順書がたまっていく状況

私が所属する開発組織では、リリースのたびに手順書が1件起こされる運用になっています。テンプレート（雛形）から作成し、実際の作業内容を書き込んでから実行する、という形です。

これが、半期で40〜45件くらいのペースで蓄積されていきます。1件ごとには、それなりの考えと判断が詰まっているのですが、件数が積み上がってくると、組織として「どんな種類のリリースをどのくらいの頻度でやっているのか」「どこが定型でどこが非定型なのか」が見えづらくなってきます。

最近、このあたりを整理してできるところから自動化していきたい、という話が組織課題として浮上してきました。私はその検討の最初の段階として、まず手順書を全件読んでデプロイのパターンを可視化する、という作業を担当することになりました。

この記事は、その作業の中で起きた方針転換の記録です。

前提条件

最初の躓き：Windows非互換のファイル名

本筋ではないのですが、最初の一歩で地味につまずいたので残しておきます。

リポジトリをクローンしようとしたら、1ファイルだけcheckoutに失敗しました。原因はファイル名に > が含まれていたこと。WindowsのNTFSでは予約文字に当たるため、ローカルに展開できません。

最終的には sparse-checkout でその1ファイルだけ除外し、残り全件を取得しました。

git sparse-checkout init --no-cone
git sparse-checkout set '/*' '!<該当ファイルのパターン>'

毎回新鮮にくらう細部です。本題から逸れる作業に時間を溶かすのは、こういうところからだなと改めて思いました。

分析アプローチ：AIに任せる範囲と、人間が確認する範囲

200件超を読んで分類する、というのは、人間がやると数日コースの作業です。今回はClaude Codeに分析を任せることにしました。

進め方は次のような流れです。

最初に数件のサンプルを読んで、手順書の構造のバリエーションを把握しました。テンプレートから派生したバリエーションが思った以上に多様化していたので、いきなり全件を投げる前にここを通したのは正解だったと思います。

その上で、エージェントに全期間の手順書を分類してもらう。出てきた分類について、各パターンに紐付けられた代表的な手順書を人間側で抽出して、本当にそのパターンに当てはまるかを突き合わせる。ズレていれば再分類を依頼する。これを繰り返しました。

ここで感じたのは、AIに任せる部分と人間が判断する部分の境界が、思っていたよりはっきりしていたことです。

このバランスが取れるなら、こういう大量ドキュメント分析は、現実的なオプションになってきたなと感じました。

抽出されたパターン

最終的には9カテゴリ × 20パターンに整理されました。全体像は次のような構造になりました（簡略版です）。

二大頻出パターンは:

この2つで全体の3〜4割を占めていました。半年分のリリースの大半は、特殊なものではなく、「いつもの単一コンポーネントのリリース」だということです。

もう一つ重要な発見は、ほぼ全件で実行される横断的な「共通後処理」パターンがあったことです。タグ付与、デプロイ表の更新、リリースノートの追記、関係者へのアナウンス。こういう一連の作業が、リリース種別を問わず全件で実行されていました。

このあたりまでは、想定通りの分析作業として進んでいました。

方針転換のきっかけ：書きながら違和感が出てきた

最初、私は本体ドキュメントの中に「自動化優先度マトリクス」というセクションを作っていました。各パターンについて、次のような列を並べた表です。

「全体の何%を占めるか」「自動化しやすいか」「ロールバックのリスクはどのくらいか」を組み合わせて、「ここから自動化に着手すべき」という提案まで踏み込んでいました。

ここまで書き進めて、ふと違和感が出てきました。

このドキュメント、目的が混ざっていないか?

「現状こうなっている」を伝えるドキュメントなのか、「だからこうすべき」を提案するドキュメントなのか。両方を同じドキュメントに詰め込んだ結果、どちらにとっても中途半端になっていました。現状把握としては戦略提案のノイズが混ざるし、戦略提案としては分析的記述が分厚すぎる。

迷いはしましたが、結局、本体は「現状こうなっている」だけに絞ることにしました。自動化適性、優先度、着手フェーズの議論は、丸ごと削除しました。本体の中から自動化文脈を消して、観察事実だけのドキュメントに作り直したわけです。

書きながら、自分でも「えっ、ここまで書いて消すのか」という気持ちはありました。ただ、消した方が筋が通る、というのは違和感のレベルで明確だったので、思い切りました。

なぜ分けたかったのか

ここからは内省寄りの話になります。なぜ「現状把握」と「戦略提案」を別ドキュメントに分けたかったのか。書きながら整理していた理由を、4つに分けて残しておきます。

理由1: ドキュメントの「寿命」が変わる

現状把握は、事実をまとめたものです。新しいリリースが追加されない限り、書いた時点の内容はそのまま正確であり続けます。

一方、戦略提案は前提が変わると古くなります。組織の優先順位、技術選択、人員配置、ビジネスの状況。こういうものが少し変わるだけで、「だからこの順に着手すべき」という結論はすぐに揺らぎます。

両者を同じドキュメントに混ぜると、提案部分のせいで全体が陳腐化します。寿命の短い情報が、寿命の長い情報を引きずり下ろすような形になる。

分けておけば、現状把握ドキュメントは長く使える資産になりますし、戦略提案ドキュメントは「これは今の状況に対する提案」だと明示できます。

理由2: 読み手の脳の使い方が変わる

「現状はこうだ」という情報は、読み手が自分の頭で判断するための材料です。読み手は事実を受け取って、自分のコンテキストでそれをどう使うかを考えます。

「だからこうしよう」という提案は、書き手の判断を読み手に渡すものです。読み手は、その判断を採用するか・修正するか・拒否するかを考えることになります。

同じドキュメントに両方が混ざると、読み手は「事実」と「主張」の境界を意識せず読んでしまいがちです。書き手の意見が、「事実」のような顔をして受け取られてしまうリスクがある。これは、書く側の責任として、避けたいなと思いました。

理由3: 議論の対象が違う

現状把握に対する議論は、「事実認識が合っているか」が中心になります。「この分類は実態と合うか」「件数のカウントは妥当か」といった、認識のすり合わせです。

戦略提案に対する議論は、「優先順位や方法論が妥当か」が中心です。「なぜそこから着手するのか」「他に取りうる選択肢はないか」といった、判断のすり合わせです。

これらは別レイヤーの議論で、同じ場で混ぜるとどっちつかずになります。事実認識の議論をしているはずなのに、いつの間にか戦略の話に流れてしまうような形になる。

別ドキュメントに分けることで、それぞれの議論を、それぞれにふさわしい深さでやれるようになります。

理由4: 自分の思考の自由度が変わる

これが個人的に一番大きい理由でした。

「自動化したいから現状を整理する」というスタンスでドキュメントを書いていると、分析が「自動化の根拠探し」になりがちです。自動化に向かない領域や、そもそも自動化以外の改善余地は、視野からだんだん外れていく。

いったん自動化文脈を消して、現状を中立に見たときに、すっと体に入ってきた発見もありました。「全件横断で実行される共通後処理」が一つの強いパターンとして見えてきたのは、自動化前提をいったん外してから、現状をフラットに眺め直してからだった気がします。

書き手としての自分の前提が、分析の解像度を下げていた。それを途中で外せたのは、たぶん運がよかったです。

修正後のドキュメント構造

最終的に、ドキュメント構造はこんな形に落ち着きました。

documents/release/
├── deployment_patterns.md       ← 本体（中立な現状把握資料）
└── deployment_patterns/         ← 個別パターンの詳細
    ├── パターン1.md
    ├── パターン2.md
    └── ...

本体には、観察できる事実だけが入っています。分類図、パターンの要約表、トレンド（半期推移）、分析の根拠と限界。これだけです。

戦略提案については、別ドキュメントとして起こす予定です。「現状こうなっている」を共有してから、「だからこうしたい」を別に書く、という二段構えにします。

次にやろうとしていること

自動化戦略の検討は、これからです。

着手の有力候補は、全件横断で実行される「共通後処理」パターンだと考えています。リリース種別を問わず必ず実行されるので、効果が広く効く。一方で、形式化しにくい人間判断も混ざっているので、どこまでをCI/CDジョブにして、どこまでをAIエージェントに任せて、どこを人間が判断するか、の設計はこれから詰めていきます。

具体的なジョブ仕様まで詰まったら、また別の記事として残せればと思います。

振り返り

今回の作業で、自分にとって一番学びだったのは、AIに大量ドキュメントを読ませる作業そのものよりも、「自分はこのドキュメントを何のために書いているのか」を途中で問い直したことでした。

「自動化したいから現状を整理する」と「まず現状をそのまま見る」は、似ているようで、出てくる成果物の性格がまるで違ってきます。前者はどうしても「自動化の根拠探し」に引きずられるし、後者は中立な観察に集中できる。

書きながらズレに気づけたのは、たぶん運がよかったところがあります。最初から「分けるべきだ」と決めて書き始めていれば、たぶん気づかなかった。混ぜて書いて、混ざりすぎて違和感が出て、はじめて分けることの意味がわかった、という順番でした。

ドキュメントを書くときに、「これは何のためのドキュメントか」を途中で問い直す。一度書いたものをごっそり消す勇気を持つ。こういうのは毎回ちょっと痛みを伴いますが、消した方が筋が通るときは、消した方が結果的に早い、というのは、今回の作業を通じて改めて体に落ちた感覚でした。

遠回りに見えて、いったん戻ったほうが、結局は早く進める。こういう感覚を、もう少し早めに思い出せるようになりたいなと思いました。

関連書籍

今回のような ドキュメント設計・AI を活用した大量分析・リリースの自動化について、さらに学びたい方におすすめの書籍です。