Claude Code や Cursor などのコーディングエージェントに作業記録（一次ログ）を出力させ、それを下敷きにして技術ブログや手順書、社内レポートを作成するワークフローが日常的になってきました。ターミナルで実行したコマンドやテスト結果が克明に記録されるため、ドキュメント作成の工数は大幅に削減されます。

しかし、AI が出力したログを完全に信用して記事や手順書を公開した直後、「記載された手順通りに実行しても動かない」「必要な前提条件や認証設定が抜けている」と判明し、慌てて修正を余儀なくされた経験はないでしょうか。

AI の一次記録における 「手作業の欠落（Observability Gap）」 とは、AI がアクセス可能な CLI や Git などの境界内（In-band）の記録に、人間が外部で行った GUI 設定やクラウド認証などの帯域外操作（Out-of-band）が構造的に含まれない現象です。AI から見れば「何も操作されていないのに状態が好転した」ようにしか観測できず、完全に見える実行ログほど手動操作の抜け穴が不可視化されます。

当ブログの執筆・公開パイプラインにおいても、公開当日に記録に無かった設定場所の抜けが発覚し、初版公開から証言の追記、フル再レビュー、再公開まで 54 分 53 秒 の手戻りが発生した事例がありました。本記事では、この生々しい手戻り実測データを起点に、なぜプロンプト指示ではこの欠落を防げないのか、そして記録に無い手作業をどの工程で訊けば最小 1 往復で済むのかという工程設計の判断基準を論じます。

公開当日に 3 段の手戻りを起こした「抜けた手作業」の実例

当ブログでは、AI エージェントを活用して検証から執筆、校閲までを自動化するパイプラインを運用しています。その中で起きた手戻りの一次実測データを振り返ります。

macOS 27 の fm コマンド記事で起きた「いつのまにか」問題

2026 年 9 月下旬、当ブログで公開した macOS 27 の fm コマンド検証記事 の執筆過程において、初期の動作検証で不可解な記録が残っていました。

検証の初期段階では、ターミナルで fm コマンドを実行してもモデルの準備が整っておらず、エラーが返されていました。

当時のセッション記録には、次の出力が残っています。

→ fm chat
Error: The model is not available. Try again later.

→ fm available
System model unavailable: modelNotReady

ところが数十分後、書き手である開発者から「いつのまにか行けるようになった」という報告とともに、コマンドのステータスが利用可能状態に好転しました。

いつのまにか行けるようになった。

→ fm available
System model available

このとき、エージェントが採取していたセッショントランスクリプトには「利用不可だった状態」と「利用可能になった状態」の 2 つのスナップショットしか存在しませんでした。その間に人間がどのような操作を行ったのかは 1 行も記録されていませんでした。

そのため、翌未明に作成された初期の一次計測ログには、次のような注記が残されることになりました。

書けること: 23:31 JST の報告では modelNotReady、00:05 JST の報告では System model available。その間に使えるようになった。ユーザーの言葉では「いつのまにか」。 書けないこと: 正確な切り替わり時刻、ダウンロードにかかった時間、その間にユーザーが何かをしたかどうか（記録に無い）。

初回公開から 17 秒後の証言と、54 分 53 秒の再レビュー・再公開

この空白は一次ログの段階では埋まらないまま、パイプラインは下流に進みました。「Siri を有効にした」という操作そのものは、初版公開の約 9 分前に書き手が会話の中で述べ、本文にも反映されました。しかし、どこで有効にしたかという設定場所は訊かれないまま、記事は初版として公開されました。手戻りの連鎖はその直後に始まります。

初版公開コミット（11:42:47）の直後、エージェントが設定場所を書き手に確認し、コミットの 17 秒後に書き手から「設定は、システム設定の『Siri』になっていた。アップデートしてシステム設定がいくつか変わった気がする」という答えが返りました。

この証言を受けて、公開当日中に 3 段階の修正コミットが行われました。内訳は次のとおりです。

  1. 第 1 段（初回公開から 32 秒後 / 11:43:19）: 証言追記コミット 一次計測ログの追補欄に、証言として「有効にした設定の場所（システム設定の Siri）」を 8 行追記（1 file changed, 8 insertions(+)）。
  2. 第 2 段（初回公開から 2 分 26 秒後 / 11:45:13）: 本文反映コミット 設計書（design.md）および記事草案（draft.md）にシステム設定の記述を反映（2 files changed, 4 insertions(+), 3 deletions(-)）。
  3. 第 3 段（初回公開から 54 分 53 秒後 / 12:37:40）: 再レビュー・再公開コミット 校閲（proofreader）、読者視点レビュー（reader-reviewer）、脚注整合性検証の 3 つのサブエージェントによるフルレビューを再実行し、公開記事へ反映して再公開（3 files changed, 73 insertions(+), 35 deletions(-)）。

初版公開と最終的な再公開のあいだの差分（コミットごとの合計ではなく、両時点の比較）は、5 ファイルにわたり 83 行追加・36 行削除、所要時間は 54 分 53 秒 に達しました。

後の週次振り返りでは、記録に無い書き手の操作を訊く手順が一次ログの段階にあれば、この 1 往復は公開前に済んでいたと振り返り、その手順を足す工程改善課題を起票しました。

なぜ AI の一次記録には「手動操作」が入らないのか（構造的限界）

この手戻りは、AI エージェントの性能不足や人間の不注意によって生じた単なる偶発的なミスではありません。AI エージェントの観測境界に起因する構造的限界です。

AI の観測境界（In-band と Out-of-band）

AI エージェントが観測できる領域は、自身に権限が与えられているインバンド（In-band）の空間に限られます。具体的には、CLI コマンドの標準入出力、Git のコミットログや差分、および指定されたワークスペース内のファイルシステムです。

一方で、人間が環境構築やトラブルシューティングの過程で行う操作の多くは、エージェントの観測境界の外側（Out-of-band）で行われます。macOS のシステム設定ダイアログ、クラウドプロバイダの Web コンソール、外部ブラウザでの OAuth 認証、2FA の承認、別ターミナルウィンドウでの環境変数の export などがこれに該当します。

Partnership on AI が 2026 年に発表したエージェントのテレメトリに関するレポートでも、エージェントの観測可能性には 6 つの構造的ギャップが存在すると指摘されています1。その 1 つが Human intervention（人間の介入）で、なぜレビューが発火したのか、誰がどのような権限で承認したのかという文脈がフレームワークの記録に残らないとされています。

「監査証跡の錯覚」と「自信満々の誤答（The Confident Wrong Answer）」

エージェントが作成したログは、実行されたシェルコマンドやタイムスタンプが整然と並んでいるため、人間は「すべての作業が完全に記録されている」と錯覚しがちです。これが「監査証跡の錯覚」です。

しかし、オブザーバビリティ企業の OneUptime が指摘するように、従来の決定論的なログやメトリクス監視はエージェント特有の失敗パターンに対して盲目になります2。OneUptime はその典型として、エラーも例外も出さず、HTTP 200 の正常応答のまま完全に誤った回答を返す The Confident Wrong Answer（自信満々の誤答）を挙げています。これを文書作成に当てはめると、正常終了したセッションのログから、前提手順の抜けたドキュメントが何の警告もなく出てくることになります。

Braintrust はエージェントトレースを 4 本柱（Tool calls, Reasoning steps, State transitions, Memory operations）で整理しています3。この枠組みに当てはめて考えると、帯域外で行われた手動操作はエージェントのトレース上に現れず、State transitions 上で「入力コンテキストに存在しない突然の状態好転」としてしか観測できません。ログの見た目がどれほど完全であっても、観測境界の外側で起きた事実は、ログ上には初めから存在しないのです。

プロンプト指示（予防）で手作業の欠落を塞げない理由

「それなら、システムプロンプトに『前提となる手動設定や GUI の変更があれば必ず手順に含めよ』と強く指示しておけば良いのではないか」と考えるかもしれません。しかし、この指示だけでは塞げません。

LLM は入力されたコンテキスト（プロンプトやログ）に基づいて次のトークンを予測するモデルです。どのような手動操作が行われたかという具体的な操作内容・手順の記録が入力コンテキストに存在しない以上、LLM にはその存在自体を認識する術がありません。

コンテキストに無い情報を無理に書かせようとプロンプトで圧力をかけると、LLM は確率的にそれらしい架空の設定項目や手順を推測で補おうとします（ハルシネーション）。その結果、実際の手作業とは異なる架空の操作手順が混入し、ドキュメントの信頼性をかえって損ないます。観測境界の外側にある事実は、LLM に推測で補わせる「予防」では塞げません。ここで退けているのは、記録に無い操作を LLM に書かせる指示です。人間に訊く手順をスキルやスクリプトとして工程に組み込むことは別物で、次節以降で扱うのはそちらです。

記録に無い操作はいつ訊くべきか──4 つの介入タイミング比較

観測境界の外側にある手動操作を把握する唯一の手段は、操作を行った当人である「書き手（人間）」に訊くことです。

では、そのヒアリング工程を開発・執筆パイプラインのどの位置に配置すべきでしょうか。セッション中から公開後まで、大きく 4 つの選択肢が考えられます。ここでいう一次ログ採取段は、エージェントとの作業セッションを終えて作業記録を確定させ、記事や手順書の構成に入る前の時点を指します。

介入タイミングの比較表

4 つの介入タイミングの特徴、メリット、および手戻りコストを比較したのが以下の表です。

介入タイミング主な特徴とメリットデメリット・手戻りコスト判定
(1) セッション中（リアルタイム）人間の記憶が最も鮮明エージェントの自律実行が毎回停止し集中を阻害。承認疲労を最悪化させる4✕
(2) 一次ログ採取直後（一次ログ段）セッション直後で記憶が残っており、手作業の抜けに起因する手戻りを防ぎ、後続パイプラインの巻き戻しを最小化できる。修正は可逆セッション直後に数問の確認負荷が発生する◎ 最適（最小 1 往復）
(3) 構成・執筆時（企画・執筆段）記事の文脈に合わせて必要な設定だけを問える構成案や下書きができてから手作業が判明すると、章立てや論理構成の書き直し（手戻り）が発生△
(4) 公開後・レビュー後（レビュー・公開段）読者やレビュアーに指摘されて初めて気づく最悪のコスト。自社の検証記事実例では、3 サブエージェントによるフル再レビューと再公開で 54 分 53 秒・5 ファイル 83 行追加・36 行削除 の手戻りが発生✕（破綻）

表のうち実測があるのは (4) の 1 件だけで、(1)〜(3) のコストは推定です。それでも本件の経験からは、人間の記憶の鮮度を保ちながら後続パイプライン全体の巻き戻しを避けられる位置として、「セッション直後の一次ログ採取段」 を選びます。

下流に行くほど膨らむ修正コスト（Boehm の 100 倍ルール）

なぜ公開後（表の (4)）の手戻りコストはこれほど甚大になるのでしょうか。

ソフトウェア工学の古典的な研究において、Barry Boehm と Victor Basili は「ソフトウェアの欠陥を納品・リリース後に発見して修正するコストは、要件定義や設計の初期段階で修正する場合と比較して 100 倍高価になることがある」という法則（100 倍ルール）を報告しています5。さらに、ソフトウェア開発工数の 40〜50% は事前に予防できたはずの回避可能な手戻り（avoidable rework）に浪費されていると指摘しています。

AI を活用したドキュメンテーションやコンテンツ作成のパイプラインにも、同じ傾向が当てはまると考えます。

振り返りの判断どおり一次ログ採取段（表の (2)）で確認できていれば、必要だったのはログへの数行の追記だったはずです。実際には公開後（表の (4)）に回ったことで、ログ追記、設計書修正、下書き修正、そして 3 つのサブエージェントによるフル再レビューと再公開という、54 分 53 秒・5 ファイル 83 行追加・36 行削除におよぶ大掛かりな巻き戻しを招きました。本件では、1 行の設定場所が 5 ファイルの修正と 3 エージェントのフルレビューに波及しました。下流に進むほど、依存する成果物の再検証の範囲が広がります。

「可逆なものは検収、不可逆なものは予防」の原則

ヒアリング工程を設計する上での指針となるのが、「可逆なものは検収、不可逆なものは予防」という設計思想です。

予防（プロンプトによる指示など）は「起こり得る原因の空間（無限）」に対して網を張るアプローチです。どれだけ厳格なプロンプトを重ねても、想定外の手動操作を完全に先回りして防ぐことはできません。

一方、検収（ヒアリング）は「実際に実行された結果の空間（有限）」に対して確認を行うアプローチです。セッションが終了した直後の一次ログ採取段における修正は完全に 可逆 であり、影響範囲は手元のログファイル 1 つに限定されます。

これに対し、記事の公開や読者への共有、外部へのリリースは、関係者の認知や公開ステータスを巻き込むため 不可逆 に近い性質を持ちます。不可逆な境界を越えてしまう前に、完全に可逆である一次ログ採取段で検収を済ませておくことが、手戻りを最小化するための鉄則です。

前提が変われば結論はどう変わるか

今後、エージェント技術が進化した場合、この工程設計の結論はどう変わるでしょうか。

現在、OS の GUI 画面を直接認識・操作する Computer Use や、MCP（Model Context Protocol）によるブラウザ操作の統合が急速に進んでいます。AI が操作できるインターフェースが広がれば、従来は「帯域外」だった GUI 設定やブラウザ操作の一部はインバンドの観測境界内に取り込まれる可能性があります。

しかし、実務の開発現場において帯域外操作が完全にゼロになることはありません。スマートフォンの認証アプリによる 2FA 承認、物理的なハードウェアの接続、別端末でのクラウドアカウント設定、セキュリティポリシーでエージェントのアクセスが遮断された社内コンソールなど、原理的に AI の観測境界の外側に残る領域は必ず存在します。

したがって、エージェントの観測境界が拡張されても、帯域外の操作がログに入らないという限界は残り、「セッション直後の一次ログ採取段で検収する」という工程設計の原則も当面は有効だと考えます。ただし、書き手自身が操作を覚えていない場合（本件の夜の時点の答えは「いつのまにか」でした）や、記録者と操作者が別人の場合は、訊いても回収できないことがあります。

よくある質問（FAQ）

Q. エージェントのプロンプトに「前提条件を必ず書くこと」と指示しておけば、ヒアリング工程は不要になりませんか？

A. 不要になりません。AI がアクセスできるのは CLI や Git などの境界内だけであり、帯域外で行われた手動操作はエージェントのログに残らないため、プロンプト指示だけでは検知できません。無理に書かせると、推測によるハルシネーションの原因になります。

Q. セッションの実行中に毎回手作業を確認させるのではダメですか？

A. おすすめしません。実行中の頻繁な確認は開発者の集中を阻害し、承認疲労（Approval Fatigue）によって無思考な承認（ラバースタンプ）を招きます。セッション完了直後の一次ログ採取段でまとめて確認すれば、作業の流れを止めずに済みます。

まとめ

AI エージェントに作業ログを作らせるワークフローにおいて、手作業の抜けによる手戻りを防ぐための判断基準をまとめます。

  • AI の観測境界を認識する: AI が出力する一次記録には、CLI や Git などの観測境界の外側（Out-of-band）で行われた手動操作は構造的に入らない。完全に見えるログほど手作業の抜けが不可視化される。
  • 記録に無い操作を LLM に推測させない: ログに存在しない事実はプロンプト指示だけでは書かせられず、無理に指示するとハルシネーションを招く。訊く手順を工程として組み込む。
  • セッション直後の一次ログ段で検収する: 記録に無い操作を書き手に訊く工程は、下流工程への巻き戻しを防ぐため、可逆な境界である「セッション直後の一次ログ採取段」に配置するのが最も費用対効果が高い。

開発プロセスの自動化、AI Operations の導入設計、Human-in-the-loop を組み込んだパイプライン設計のご相談は、ぜひ コンタクトフォーム よりお気軽にお問い合わせください。

Footnotes

  1. The Observability Gap in AI Agents Madhulika Srikumar, Eric Mibuari et al., Partnership on AI (2026-10-07)。エージェントテレメトリにおける 6 つのギャップおよび Human intervention の欠落。 ↩

  2. Monitoring AI Agents in Production: The Observability Gap Nobody’s Talking About Jamie Mallers, OneUptime (2026-03-14)。決定論的監視の限界および The Confident Wrong Answer。 ↩

  3. Agent observability: The complete guide for 2026 Braintrust Team, Braintrust (2026-06-21)。エージェントトレース 4 本柱（Tool calls, Reasoning steps, State transitions, Memory operations）。 ↩

  4. Approval Fatigue Wolf McNally, Encyclopedia of Agentic Coding Patterns (2026-04-06)。承認要求過多による rubber-stamping、automation bias、および Bounded Autonomy。 ↩

  5. Software Defect Reduction Top 10 List Barry W. Boehm, Victor R. Basili, IEEE Computer, Vol. 34, Issue 1, pp. 135–137 (2001-01, DOI: 10.1109/2.962984)。下流工程における欠陥修正コスト増大（100 倍ルール）および 40〜50% の回避可能な手戻り。 ↩