『動くはず』を実測する習慣 — 文書は計画、現物が状態

📄文書は計画、現物が状態

文書に「対応済み」とあっても、それは計画の痕跡。いま現物がどう動くかは、見るまで分からない。

人でも AI でも、状態を訊かれると、つい手元の文書を根拠に答えてしまう。

README に「対応済み」とある。Issue が Close されている。スタンドアップのメモに「完了」と残っている。どれも、もっともらしい。

でも、これらは全部「そうするつもりだった」という計画の痕跡です。いま本番がどう動いているかを、保証してはくれません。

社内では、これを短く「文書 = plan、live = state」と呼んでいます。

文書を読んで状態を推し量るのは、地図だけ見て「渋滞していないはず」と言うのに近い。実際の道路は、現地を見るまで分からない。――当たり前です。でも、忙しいときほど、この当たり前を飛ばしてしまう。

🚧merged は「してもいい」であって「した」ではない

マージは「反映してよい」という許可にすぎない。修正が取り込まれても、本番の画像はまだ直っていなかった。

この規律が生まれたきっかけは、自社サイトでの取りこぼしでした。

画像が表示されない不具合、いわゆる 404。その修正を用意して、プルリクエストをマージしました。git のログ上では、確かに main に入っている。ふつうなら、ここで「直りました」と言いたくなる。

ところが本番の画面を開くと、画像はまだ出ていませんでした。

マージは「本番に反映してよい」という許可が下りただけ。「本番に反映された」とは、別物だったんです。merge は計画側の出来事。実際にデプロイが走って現物が入れ替わるまで、状態は何も変わっていなかった。

⚙️自動で上がると思い込んでいた落とし穴

マージで自動デプロイされる、が思い込みだった。前提はホスティングごとに違う。実測で裏を取る。

なぜ反映されなかったのか。

当社サイトのホスティングは、マージしたら自動でビルドが始まる設定になっていませんでした。デプロイは別の CI ジョブが担う構成です。

しかもそのとき、変更を含むプルリクエストを続けて重ねたせいで、先行のデプロイ処理が後続に打ち消され、どちらも上がらない、という噛み合わせが起きていました。

厄介なのは――この手の「自動で上がるはず」は、正しく動いているうちは一度も表面化しないこと。

デプロイの前提は、製品やホスティングごとに違います。だから私はこの一件のあと、ビルドやデプロイの前提を思い込みで語らず、公式ドキュメントか実測で裏を取るようにしました（たとえば Next.js の デプロイに関する公式ドキュメントのように、まず一次情報にあたります）。

🔍「完了」と言う前に、一次情報を一つ触る

状態を報告する前に、本番を開く・ジョブを見る・応答を叩く。直前にその場で一度、現物に触れる。

この経験から当社が決めたのは、拍子抜けするほど地味なルールです。

残タスク・デプロイ状況・サービスの死活・進捗――こうした「状態」を報告する前に、必ず一次情報を一つ実測する。

本番 URL を実際に開いて中身を確かめる。デプロイのジョブが本当に走ったかを一覧で見る。API を叩いて応答を確かめる。それだけです。

大事なのは、報告文に「実測した」と書くことではありません。報告する直前に、その場で一度、手を動かすこと自体です。

「前に確認したことがある」は、「いま確認した」の代わりにはならない。そのあいだに状態が変わっていれば、過去の観測はもう計画側の情報に戻ってしまうから。だから URL や番号を一覧にまとめる、その直前にもう一度だけ叩く。この数秒の手間を、惜しまないようにしています。

🧭一人会社だからこそ、思い込みを機械の目で埋める

一人会社では、作った本人が最後の確認者。「はず」で止めず、現物を一つ触ってから話す。

大きな組織なら、誰かが「本番、ほんとに上がってる?」と横から確かめてくれます。

けれど一人会社では、作った本人が、最後の確認者を兼ねる。人の目がないぶん、思い込みがそのまま報告になり、報告がそのまま意思決定になってしまう。――ここが、一番こわい。

だから私は「動くはず」という言葉を、自分に対してこそ信用しないことにしました。

はず、で止めない。現物を一つ触ってから話す。手間は数秒から数十秒。その数十秒をケチって、直したつもりの不具合が本番に残り続けるほうが、よほど高くつきます。

あなたが最後に「できてます」と報告したもの――それ、いま現物を見て言いましたか?

文書は計画、現物が状態。この短い区別を、これからも自分のループに刻んでおきます。