手順書に「毎回やる」と書いても、経路が落ちれば出力は0になる｜フォールバックが2段しか無かった
🧭 この記事の前提
個人サイトのアクセス解析を、AIエージェント（Claude Code）が毎朝8時に自動実行しています。手順書には「①どの記事が見られたか ②どのボタンが押されたか ③回遊 の3つは毎回出す。流入が少ないからで省略しない」と明記してあります。
困ったのは、その3項目が1つも出ない日が来たこと。しかも壊れたのは前日でも当日でもなく、2日前から穴が開いていました。
持ち帰れるもの：自動化した定期処理を持っている人向けに、「静かに壊れる」構造と、フォールバックの段数の数え方を出します。手作業でやっている人には不要です。
結論：手順書は、経路の冗長性を保証しない
📌 先に結論 ① 「毎回やる」と書いてあっても、取得経路が落ちれば出ない ② 経路が2段だと、2段目が生きている間は1段目の故障が見えない ③ 3段目を足すときは、それで埋まらない項目を先に書いておく
① 何が起きたか
取得の経路は2段構成でした。
1段目: APIで直接取得する
2段目: ダメならブラウザ経由で画面から取る
ある日の朝、両方が同時に塞がりました。
| 段 | 落ちた理由 |
|---|---|
| 1段目（API） | 認証情報のパス（GA_SA_KEY_PATH）が未設定で、スクリプトが起動直後に停止 |
| 2段目（ブラウザ） | ブラウザ拡張が未接続。2回試行して同じ結果 |
結果、その日の出力は3項目すべて空になりました。流入も、順位も、CTAのクリックも、回遊も、1つも数字がありません。
② いちばん悪かったのは、2日間見えなかったこと
1段目のAPIは、その日だけ落ちたわけではありません。 認証が通っていないので、最初から一度も動いていませんでした。
ところが2日前も前日も、レポートは普通に出ていました。2段目のブラウザ経路が生きていたからです。
| 日 | 1段目 | 2段目 | 出力 |
|---|---|---|---|
| 1日目 | ❌（未設定） | ✅ | 正常に見える |
| 2日目 | ❌（未設定） | ✅ | 正常に見える |
| 3日目 | ❌（未設定） | ❌（拡張未接続） | 0 |
⚠ 覚えておく一行 フォールバックは、故障を隠します。 冗長化そのものは正しいのですが、「今どの段で取れているか」を出力していないと、残りの段数が見えません。
3日目に初めて実害が出ましたが、穴が開いたのは3日目ではありません。 1日目から片肺でした。もし2段目が落ちた日が1週間後なら、1週間ずっと「正常に見える」状態が続いていたはずです。
③ 「毎回出す」と書いてあったのに出なかった
手順書には、はっきりこう書いてあります。
「流入が少ないから」で省略しない。 ①どの記事が見られたか ②どの記事のどのボタンが押されたか ③回遊 の3つは毎回出す。少ないなら少ないまま名指しで書く
この一文には逃げ道も用意してありました。「ログインが切れていたら、取れた分で進める」。
その逃げ道は機能しませんでした。 想定していたのは「ログイン切れ」で、実際に起きたのは「拡張が未接続で、そもそもブラウザを操作できない」だったからです。ログイン画面にすら到達していません。
手順書は「やること」を決められますが、「できること」は決められません。
決めた内容の実行可能性は、経路の側にあります。手順書をいくら厳しく書いても、経路の段数は増えません。
④ 3段目に足したもの
そこで、ログイン不要でサーバ側から取れるものだけを出す3段目を作りました。1つのコマンドで走ります。
出るのはこれだけです。
| 項目 | 実際に取れた値 |
|---|---|
記事本数と sitemap.xml の一致 | HTTP 200・85 URL（記事78＋固定7）。リポジトリの記事数と一致 |
robots.txt | Allow: / ＋ sitemapの記載あり |
| 新着記事の到達性 | 当日追加の4本とも 200 |
| 懸案のURLの到達性 | 名指ししていた6件とも 200 |
| 被覆率の分母 | 記事本数 |
| 収益リンクの本番／未設定の内訳 | キー数と未設定数 |
この日、これで分かったことが1つありました。「Googleが一度もクロールしていない6件」が、技術的には全部200で到達できるという事実です。到達性の問題ではないと切り分けられました。
⑤ 3段目にできないことを、先に書いた
ここが今回いちばん重要な設計判断です。 3段目には次の一文を添えました。
⚠ 3段目が埋められるのは「土台が壊れていないか」までで、成果指標ではない。 流入・順位・CTAは原理的にログイン無しでは取れない。 全部緑でも「今日の流入は不明」と書くこと。緑を成果として報告しない。
これを書かないと、3段目は最悪のフォールバックになります。全項目が緑で返るので、「今日も問題なし」という報告が毎日出続け、流入が測れていないことが永久に見えなくなるからです。
📌 ここだけ持ち帰るなら フォールバックを足すときは、それで埋まらない項目を同時に明文化する。 埋まらない項目を書かないフォールバックは、監視ではなく目隠しになります。
⑥ 同じ「静かに壊れる」を、他でも踏んでいる
この構造は1回では終わりませんでした。別の場所でも同じ形の故障を踏んでいます。
(1) 「受理」を「成功」と読んでいた。
インデックスの通知を送るスクリプトが 202 Accepted を返したので、完了として記録していました。202は受理だけで、鍵の検証は非同期です。 鍵が無効なら黙って捨てられます。後日再実行したら 200 OK に変わり、そこで初めて経路が通ったと確認できました。「送信できた」と「受け付けられた」は別物でした。
(2) 実行時刻が意図と違っていた。
定時実行の設定が 13 2 * * *＝深夜2時13分になっていました。手順書には「毎朝8時」と書いてあります。実行環境はPCなので、深夜は起動している保証がありません。記録ファイルは生成されていたので、「動いている」ように見えていました。
(3) 検査対象が0件だった。 別の検証スクリプトが「エラー0件」を返し続けていたことがあります。原因は品質ではなく、検査対象が0件だったことでした。0件を処理して0件の問題を報告する状態は、正常な出力と区別できません。
3つに共通しているのは、出力があること自体を、正常の証拠として扱っていたことです。
自分でやる手順
- 今その処理が何段で取れているかを数える。 段数を知らないなら、それが最初の問題です
- 「今回どの段で取れたか」を出力に必ず書かせる。 これだけで故障の隠蔽が止まります
- 一番上の段を、意図的に落として試す。 落ちても出力が出るなら、その段は最初から死んでいたかもしれません
- 3段目を足すときは、埋まらない項目を同時に書く
- 成功コードを確認する。 202と200、受理と完了を区別する
- 実行時刻・実行環境を実測する。 記録があることは、意図どおりに動いた証拠になりません
やりがちな失敗
| 失敗 | 何が起きるか | 直し方 |
|---|---|---|
| 出力が出ていることで安心する | 片肺のまま何日も走る | どの段で取れたかを出力に書く |
| フォールバックを足して終わりにする | 故障が隠れる | 残り段数を可視化する |
| 3段目の限界を書かない | 全部緑で「問題なし」が出続ける | 埋まらない項目を明文化する |
| 202を成功として記録する | 検証されずに捨てられていても気づかない | 200に変わるまで完了としない |
| 手順書を厳しくして解決しようとする | 経路の段数は増えない | 経路の側を直す |
自動実行そのものの設計と、手順書の育て方はAIエージェントの定時実行に、AIの成果物を実測で確かめる手順はAIの成果物を検証する方法にまとめています。測定できないまま前に進んでしまった話は自分で決めた上限を1晩で使い切った件、そもそも何を測るべきかはGA4だけ見るとクローラは見えないです。
まとめ
- 手順書は経路の冗長性を保証しない。 「毎回出す」と書いても、経路が落ちれば出ない
- 2段構成では、2段目が生きている間ずっと1段目の故障が見えない
- 3段目を足すときは、それで埋まらない項目を先に書く。 書かないと目隠しになる
- 出力があることは、正常の証拠ではない。 202・深夜2時・検査対象0件、全部同じ形の故障