AIエージェントが「デプロイ前に」バグを直せるようになった｜Cloudflare Workersのローカルトレーシングを読み解く

2026年8月4日、Cloudflareが「Your agent can now debug Workers with local tracing（エージェントがローカルトレーシングでWorkersをデバッグできるようになった）」という記事を公開しました。

・原典（Cloudflare公式ブログ）: https://blog.cloudflare.com/local-tracing/

一言でいうと、ローカル開発サーバー（wrangler dev / vite dev）が、何もしなくてもOpenTelemetryトレースを自動で記録するようになり、AIコーディングエージェントがそれをAPI経由でSQL照会できるようになった、という発表です。

「ローカル開発にトレーシングが付いた」と聞くと地味な改善に見えますが、この機能が面白いのは最初からAIエージェントを利用者として設計されている点です。この記事では、何ができるようになったのか、内部でどう動いているのか、そしてこの設計が示す潮流を読み解きます。

背景：エージェントのデバッグは「見えない」から高くつく

まず、この機能が解こうとしている課題から整理します。

Claude CodeやCodexのようなコーディングエージェントは、すでにローカルでWorkerを動かしてコードを書けます。ところが、動かしたWorkerが500エラーを返したとき、エージェントには**「どの処理が失敗したのか」が見えません**。

人間のエンジニアなら、ブラウザの開発者ツールやダッシュボードを開いて当たりをつけます。しかしエージェントが同じ状況でやることは、こうなりがちです。

1. 怪しい箇所に console.log を差し込む
2. リクエストを再実行する
3. 出力された文字列を読んで推理する
4. まだ分からなければ、別の箇所にログを足して繰り返す

この「ログ差し込み→再実行→出力の読解」のサイクルは、1周ごとにコードの編集と大量のログ出力の読み込みが発生します。つまりトークンと時間を大量に消費するわりに、得られる情報は非構造的です。エージェントのデバッグが遅くて高くつく構造的な理由が、ここにありました。

Cloudflareの今回の機能は、この推理ゲームを「構造化データへの問い合わせ」に置き換えるものです。

何ができるようになったか：SDK不要の自動トレース

最新のWranglerまたはCloudflare Viteプラグインで開発サーバーを起動すると、コードの変更もSDKの導入も一切なしで、Workerの実行が自動的にトレースとして記録されるようになりました。

自動で記録されるのは、次の3種類です。

console.* の出力もトレースに紐づけて収集されるため、「このリクエストのこのスパンで、このログが出た」という相関が最初から取れています。自分でカスタムスパンを張っていれば、それも同じ場所に表示されます。

計測はWorkersのオープンソースランタイムであるworkerd自体に組み込まれているため、アプリケーション側に計測コードを書く必要がありません。ここは後述する設計思想の話につながる、重要なポイントです。

エージェントはどうやってこの機能を「発見」するのか

個人的にいちばん唸ったのが、この部分です。

開発サーバーは、自分がAIエージェントのセッション内で起動されたことを検知すると、ターミナルに次のようなヒントを表示します。

This dev session is running in an AI agent.
The Local Explorer API is available at
http://localhost:8787/cdn-cgi/explorer/api

エージェントは普段からコマンドの出力を読んでいるので、このメッセージが自然に目に入ります。そしてこのAPIのルートはOpenAPIスキーマを返すため、エージェントは「どんなエンドポイントがあって、どう呼べばいいか」を実行時に自分で調べられます。

つまり、エージェント側のプロンプトや設定ファイルに使い方をハードコードしておく必要がないのです。MCPサーバーの追加設定も要りません。「ツールの存在を出力で知らせ、仕様はスキーマで自己記述する」——エージェントという新しい利用者に対するインターフェース設計として、かなり洗練されたやり方だと思います。

トレースとログの照会は、専用エンドポイントに対するSQLクエリで行います。

POST /cdn-cgi/explorer/api/local/observability/query

エージェントにとってSQLは母語のようなものなので、「直近のリクエストでエラーになったスパンを出して」といった問い合わせを、自分でクエリを組み立てて実行できます。

実例：スキーマ変更で壊れた注文APIを、デプロイなしで直す

Cloudflareの記事では、具体的なシナリオが示されています。

POST /api/orders というエンドポイントがあり、内部では「KVからカートを取得 → D1に注文を保存 → Queueに通知を送信」という3段の処理をしています。これがスキーマ変更後に500を返すようになった、という状況です。

エージェントへの指示は、これだけです。

「POST /api/orders が500を返す。原因を特定して、修正して、ローカルで検証して」

エージェントがトレースをクエリすると、次のことが1回の問い合わせで分かります。

• KVからのカート取得は成功している
• D1への挿入が no such column: delivery_window で失敗している
• Queueへの送信はそもそも呼ばれていない（手前で落ちているため）

失敗箇所が特定できたので、エージェントはD1のスキーマを検査し、未適用のマイグレーションを発見して適用します。そしてリクエストを再送し、新しいトレースを照会して「今度は3段とも成功した」ことを確認する——ここまでの発見・修正・検証のループが、すべてローカルで完結します。

従来のログ差し込み方式なら何往復もかかっていた作業が、1つのループに畳まれる。これが「トークンと時間の節約」の実体です。

内部の仕組み：workerd・Miniflare・SQLite

「How it works」のセクションによると、内部構成は次のようになっています。

1. workerd（Workersランタイム本体）が、fetch・バインディング・ハンドラーの各呼び出しを自動的にスパンとして記録する
2. Miniflare（ローカル開発環境）が、ランタイムイベントとコンソール出力を収集し、OpenTelemetryトレースと相関ログに組み立てる
3. 組み立てたテレメトリを、SQLiteベースのDurable Objectに書き込む
4. Local Explorer APIが、そのデータをSQLで照会できるように公開する

面白いのは、テレメトリの保存先に外部のデータベースではなくWorkersプラットフォーム自身の部品（SQLite-backed Durable Object）を使っていることです。ローカル開発環境の中に小さなオブザーバビリティ基盤が丸ごと入っている、と考えると分かりやすいと思います。

また、計測がランタイム組み込みであることには実利があります。アプリケーションコードへの計測SDK導入はバンドルサイズや保守の負担になりがちですが、この方式なら開発者もエージェントも「何もしていないのに最初から見える」状態から始められます。

人間にはブラウザUI「Local Explorer」

このデータはエージェント専用ではなく、人間向けのブラウザUIも同時に提供されています。Wranglerの実行中にターミナルで e キーを押すか、開発サーバーの /cdn-cgi/explorer を開くと、Local Explorerが起動します。

• リクエストを選んで、スパンのタイムライン・実行時間・属性・エラーを検査できる
• そのリクエストに相関づいたコンソールログを並べて確認できる
• KV・R2・D1・Durable Objects・Workflowsといったローカルバインディングの中身を閲覧・編集できる（D1やDurable ObjectsにはSQLエディタも付く）

公式ドキュメントによると、必要バージョンは Wrangler 4.118.0以上、またはCloudflare Viteプラグイン1.50.0以上です。

・公式ドキュメント（Local Explorer）: https://developers.cloudflare.com/workers/local-development/local-explorer/

すべてlocalhost上で動くため、Cloudflareのダッシュボードにログインする必要はありません。エージェントが直したものを人間が同じデータで確かめられる——「エージェントの検証」と「人間の関門」が同じ土台に乗るのは、実務上ありがたい構成です。

読み解き：開発ツールが「エージェントを一級ユーザ」として設計され始めた

最後に、この発表を少し引いた視点で見てみます。

これまでのオブザーバビリティ（トレース・ログ・メトリクス）は、基本的に本番環境で人間が障害対応するための道具でした。今回のCloudflareの機能は、それを2つの軸で反転させています。

1つ目は、本番からローカルへ。 トレーシングを「障害が起きてから見るもの」ではなく「デプロイ前の開発ループの中で使うもの」に持ち込みました。修正の検証がデプロイ前に閉じるので、「とりあえずデプロイして本番ログで確かめる」という危険な近道を減らせます。

2つ目は、人間からエージェントへ。 ダッシュボードのGUIではなく、OpenAPIスキーマとSQLエンドポイントという機械が読める形を一級のインターフェースとして用意しました。起動メッセージでの告知、スキーマによる自己記述、SQLでの照会——どれも「読み手がLLMである」ことを前提にした設計です。

似た動きは他所でも始まっていますが、ランタイムレベルの自動計測からエージェント向けAPIまでを開発サーバーに標準搭載した例として、今回の実装はかなり具体的です。**「エージェントが使いやすいように開発環境そのものを作り変える」**という方向性は、今後ほかの開発プラットフォームにも広がっていくと見ています。

コーディングエージェントの実力は、モデルの賢さだけでは決まりません。環境がどれだけ「見える」かで、同じモデルでも成果が大きく変わります。今回の機能は、その「環境側の整備」がプラットフォーム公式の仕事になった、という象徴的な一歩だと言えそうです。

実務での取り入れ方：自動発見に頼らず、指示書に「手順」を書く

ここからは、実際にエージェントと開発している立場からの実務的な補足です。ポイントは2つあります。

1. トレースの存在は、CLAUDE.mdやスキルに明示的に書く

Cloudflareの設計(起動時ヒント + OpenAPIによる自己記述)は「ハードコード不要」を謳っていますが、実運用ではヒントに頼れない場面が普通にあります。

• ヒントが見えるのは、dev サーバーをエージェント自身が起動した端末だけです。人間が別の端末で wrangler dev を立てておき、エージェントが後から作業に入る構成では、エージェントはヒントを一度も目にしません
• 長いセッションでは、コンテキストの圧縮・要約でヒントが消えることもあります

そこで、エージェントへの指示書(CLAUDE.mdやスキル)には、APIの場所だけでなくデバッグの手順(ポリシー)ごと書いておくのが良いと考えています。価値があるのは手順の側です。

- wrangler dev 中は Local Explorer API
  (http://localhost:8787/cdn-cgi/explorer/api) が使える
- デバッグ時は console.log を差し込む前に、まず
  POST /cdn-cgi/explorer/api/local/observability/query へ
  SQL でトレースを照会する
- 修正後は再リクエストし、新しいトレースを照会して
  成功を確認する(検証まで完結させる)

自動発見はあくまで「指示がなくても動く」ためのブートストラップ(保険)で、確実に使わせるのは指示書側の仕事——この役割分担で組み込むのが現実的です。エージェントは放っておくと慣れた「ログ差し込み」の習慣に戻りがちなので、「トレースを先に見る」を手順として固定してしまうことに意味があります。

2. 「ログをファイルにも二重書きしてAIに読ませる」工夫は不要になるか

エージェントにログを読ませるために、標準出力に加えてファイルにも二重で書き込む——という工夫をしてきたチームは多いと思います(筆者らもやってきました)。この機能で不要になるのでしょうか。

答えは「対象範囲内では不要になるが、全廃はまだ早い」です。

Workersのローカル開発に限れば、不要どころか上位互換です。console.* は自動でキャプチャされ、リクエスト・スパンに相関づいた形でSQLiteに入り、SQLで絞り込めます。ファイルログをgrepするより「このリクエストのこのスパンで出たログ」とピンポイントに引ける分、構造的に優れています。

ただし、ファイル二重書きが引き続き有効な領域は残ります。

つまり、「Workersのdevループの中のデバッグ用の二重書き」は畳んでよく、それ以外のプロセス用と事後解析用は残す、が現実的な線です。そしてこの切り分け自体を指示書に書いておくと、エージェントが古い習慣に戻るのも防げます。

まとめ

• Cloudflareが2026年8月4日、Workersのローカルトレーシング機能を発表。wrangler dev / vite dev がOpenTelemetryトレースと相関ログをSDK不要・コード変更なしで自動記録する
• AIエージェントは、起動時のヒントとOpenAPIスキーマからLocal Explorer APIを実行時に自動発見し、トレースとログをSQLで照会できる。ログ差し込みの推理ゲームが、構造化データへの問い合わせに変わる
• 「発見 → 修正 → 再実行 → 検証」のデバッグループがデプロイ前のローカルで完結する
• 人間には同じデータを見られるブラウザUI（Local Explorer）が提供され、バインディングの閲覧・編集やSQLエディタも使える。Wrangler 4.118.0以上 / Viteプラグイン1.50.0以上で利用可能
• オブザーバビリティを「本番×人間」から「ローカル×エージェント」へ広げ、エージェントを一級ユーザとして扱う開発ツール設計の具体例になっている
• 実務では、自動発見のヒントに頼らずCLAUDE.mdやスキルに「トレースを先に照会する」デバッグ手順ごと明示するのが確実。ログのファイル二重書きは、Workersのdevループ内では不要になるが、対象外プロセス・事後解析・本番向けには残す

出典

• Your agent can now debug Workers with local tracing（Cloudflare公式ブログ、2026年8月4日）
• Local Explorer · Cloudflare Workers docs（公式ドキュメント）