エージェント実行テレメトリ — 実測（観測記録）

アプリと技術書をAIエージェントで作っている、その回し方そのものを数えた記録です。手元に残っていた実行ログを機械で数えて、出てきた数字だけを並べています。うまくいった話ではなく、測ったら何が出たかの記録です。

数えて出てきたこと

呼ばれていたツールの 75.8% はシェルだった。ファイルを直接書き換えるツールは合わせて 8.2%。
入力トークンの 97.6% はキャッシュの読み直しで、生の入力は 384,744 トークンしかなかった。
1 セッションの長さは中央値で 241 ターン。長いほうが例外ではなかった。

33,274

ツール呼び出し（37 日ぶん）

18.1%

サブエージェント経由
（ツール呼び出しに占める）

この期間に動いた足場の版

Replay

まず 1 本、そのまま再生する

割合の話に入る前に、1 本だけ実物を置きます。2026-09-12 のセッションで、長さは 57 分・267 イベント。途中でサブエージェントを 3 本呼んでいて、うち 2 本は同時に動いています。

並んでいる帯を見ると、待っている時間のほうが長いのが分かります。このセッションでツールが実際に動いていたのは全体の 18% で、残りは考えている時間と、人間が読んで返事をしている時間です。触ったファイルは 42 種類で、いちばん多いものには 4 回戻ってきていました。

Tool Mix

呼ばれていたのは、ほとんどシェルだった

33,274 回のツール呼び出しのうち 25,224 回、75.8% がシェルの実行でした。ファイルを直接書き換える Edit（2,082）と Write（654）は、足しても 8.2% です。読み取りの Read が 3,894 回。

コードを書く道具として使っているつもりでしたが、実際に動いていたのはビルド・テスト・git・ログの確認でした。編集そのものより、編集した結果を確かめる往復のほうが多いという形になっています。

Chains

次に来るツールも、やはりシェルだった

呼び出しを出現順に並べて、隣り合う 2 つ組を数えました。27,111 組のうち シェルの次にまたシェルが 16,964 組（63%）で、単独の割合（75.8%）から予想されるより偏っています。

同じツールが続いた長さを数えると、1 回で終わったのが 4,742 本ある一方で、20 回以上続いた連打が 233 本ありました。エージェントを回すというのは、1 手ずつ違う道具を選ぶことではなく、同じ道具を長く叩き続けることでした。

Cost

入力のほとんどは、キャッシュの読み直しだった

入力として数えられているトークンのうち、新しく送ったぶんは 384,744 しかありません。残りはキャッシュへの書き込み 405,249,666 と、キャッシュからの読み直し 16,702,924,871 です。出力は 59,965,971。

長いセッションでは、同じ文脈を何度も読み直します。生の入力とキャッシュ読み直しの比は 4 万倍を超えていて、費用の形を決めているのはプロンプトの長さではなく、文脈をどう置いたかのほうでした。

Horizon

長く回すほうが、例外ではなかった

135 セッションの長さを数えると、中央値は 241 ターンでした。上位 1 割の境目が 765 ターン、いちばん長いもので 2,429 ターンです。

短い問い合わせが山になり、長いものが少数の外れ値として出るだろうと思っていました。実際は山そのものが 128〜512 ターンのあたりにあって、長く回すのは例外ではなく普通のほうでした。

Substrate

足場は、作っているものより速く入れ替わった

ログには、そのとき動いていた実行環境の版が記録されています。37 日のあいだに現れた版は 26 種類で、26 日は 1 日のうちに 2 つ以上の版が記録されていました。

作っているものではなく、作るための道具のほうが動き続けています。手順を人の記憶に置いておくと、次に開いたときには前提が変わっています。決めたことを文章で外に出しておかないと追いつけないのは、この速さが理由でした。

Failure

失敗は起きていたが、例外のままだった

結果がエラーとして返ってきた呼び出しを数えました。シェルで 513 回（25,202 回中の 2.0%）。ファイルを読むのと書き換えるのは 1% を下回っています。

止めた回数のほうは 42 回で、1 日に 1 回強です。手が止まる原因は、道具が失敗することではなかったことになります。

Decision Log

何を測ると決めて、何を出さないと決めたか

scopeプロジェクトごとの内訳は出さないと決めた

DECISION: 全部のプロジェクトを合算して数える。どのプロジェクトが何回、という次元を出力に作らない。出すのは「いくつあったか」だけ。
WHY / 仮説: はじめは匿名の P1〜P14 にして内訳を出すつもりだった。しかし量と期間を公開している別の数字（リリース日、コミットの推移）と突き合わせれば、どれがどれかは十分に絞り込める。匿名化は「名前を消すこと」ではなく「復元できないこと」なので、名前を消しただけでは足りない。
RESULT: 図から読めることは減った。プロジェクトによって使うツールが違うかどうかは、この記録からは分からないままになっている。

form対象ファイルはハッシュも出さず、通し番号だけにした

DECISION: トレースで「同じ対象に戻ってきた」を見せるために、内部ではパスを突き合わせる。ただし出力に載せるのは初めて出てきた順の整数だけにする。
WHY / 仮説: 最初は sha1 の先頭 6 桁を出すつもりだった。だが実際のパスは src/index.ts のようなありふれたものが多く、辞書を作って総当たりすれば戻せる。ハッシュは「元に戻せない」ように見えて、入力の候補が少なければ戻せる。
RESULT: 弧で結ばれたところが「同じ対象」だとは読めるが、それが何のファイルかは誰にも分からない。図として伝えたいのは往復があったことなので、これで足りている。

measure数え直しをデプロイの手順から外した

DECISION: 生成した JSON をリポジトリに入れて、デプロイのたびには作り直さない。デプロイが走らせるのは検査と突き合わせだけにする。
WHY / 仮説: 同じ区画のもう 1 本（開発の実測）はデプロイのたびに数え直している。こちらも同じにすると、本文が「37 日ぶん」と書いているのに図の期間だけが伸びていく。加えて、このデータは公開前に人が目で見て確かめる必要があるので、毎回作り直されると差分が読めない。
RESULT: 数字は測った日で止まる。代わりに、HTML に書いた値と JSON がずれていないかをデプロイのたびに突き合わせて、ずれていればログに出すようにした。同じサイトの別の数字が、コンソールに警告を出すだけで長く古いまま残っていたことがあるため。

Open Questions

まだ数えていないもの

サブエージェントを呼んだ効果。呼んだ回数（6,029 回ぶんのツール呼び出し）は数えたが、それによって本体のターン数が減ったかは測っていない。比べるには、同じ種類の仕事を呼んだ場合と呼ばなかった場合で並べる必要があり、その「同じ種類」をログから決める方法がまだ無い。
シェルの中身。いま git status と長いテストが同じ 1 回として並んでいる。コマンド名の最初の 1 語だけなら出せるが、そこから先はパスと引数になるので、どこで切るかを決めていない。
エラーにならなかった失敗。いちばん知りたいのはここだが、ログには「エラーとして返ってきたか」しか入っていない。やり直しの回数を代わりの指標にできないか試している途中。
待ち時間の内訳。トレース 1 本では「ツールが動いていたのは 18%」まで出せたが、残りが考えている時間なのか人間の返事待ちなのかは分けていない。

Colophon

この記録の諸元

対象	手元の Claude Code 実行ログ 312 ファイル（135 セッション / 14 プロジェクト / 1.6GB）
期間	2026-07-31 〜 2026-09-12（37 日）
数え方	定義は `scripts/gen_agent_telemetry.py` の先頭に書いてある。そこが唯一の源で、この本文の数字も図も同じ JSON を読んでいる
出していないもの	プロンプトの本文、ファイルパス、ブランチ名、リポジトリ名、プロジェクトごとの内訳。出力に載せる場所そのものを作っていない
更新	測った日のスナップショットとして固定する（デプロイのたびに数え直すと、本文の数字と図がずれる）
関連	実測の一覧・開発の実測（人間の側）・ AI エージェントの設計と進め方（開発ノート・題材は別の社内システム）・この主題を書いた技術書