Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】8 jq Commands That Show What Your Coding Agent Actually Did, From Its Transcript

2026年11月04日に「Dev.to」が公開したITニュース「8 jq Commands That Show What Your Coding Agent Actually Did, From Its Transcript」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

AIコーディングエージェントの活動記録(JSONL形式)を`jq`コマンドで分析し、その詳細を把握する方法を紹介する。実行したコマンドや編集したファイル、エラー、使用モデルなどを特定でき、エージェントの動作確認や問題解決に有用だ。

ITニュース解説

AIコーディングエージェントが開発現場に広く普及し、コード生成やリファクタリング、テスト作成といった多様な作業を自動で実行するようになった。しかし、エージェントが何をどのように実行したのか、なぜ特定の行動を取ったのか、あるいはなぜ失敗したのかといった内部の挙動は、多くの場合ブラックボックスのように感じられる。この課題に対処するため、エージェントが生成する「トランスクリプト」、つまり活動ログを解析する技術が重要となる。

この記事では、代表的なAIコーディングエージェントであるClaude CodeやCodexが、その活動内容をJSONL形式のファイルに記録していることに着目している。JSONLは、JSON(JavaScript Object Notation)形式のデータが1行に1つずつ並んだテキストファイルであり、構造化されたログデータを効率的に記録するのに適した形式である。そして、このJSONLファイルから必要な情報を抽出し、加工する強力なコマンドラインツールがjqである。システムエンジニアを目指す上で、このようなログデータを解析するスキルは、問題解決やシステム改善において不可欠な能力となる。

まず、エージェントのログファイルを見つけることから始める。Claude Codeは通常~/.claude/projects/以下に、Codexは~/.codex/sessions/以下にJSONL形式でログを保存している。これらのファイルは多数存在するため、ls -tコマンドで最終更新日時が新しい順に並べ替え、head -1で最新のファイルパスを取得して変数に格納する方法が紹介されている。ログファイルを見つけたら、まずその中にどのような種類のデータが記録されているかを確認する。jq -r '.type' "$T" | sort | uniq -c | sort -rnというコマンドを使えば、ログの各行がどのような「タイプ」(例えば「assistant」や「user」など)であるかを一覧し、それぞれの出現回数を確認できる。これは、ログの全体像を把握する上で非常に役立つ。

次に、具体的なjqコマンドを使い、エージェントの行動を深く掘り下げていく。

  1. 実行されたシェルコマンドの特定: エージェントが開発環境でどのようなシェルコマンドを実行しようとしたかを知ることは、その意図を理解する上で重要である。jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Bash") | .input.command'というコマンドは、エージェントがBashツールを使って実行しようとした全てのコマンドを抽出する。これには、実際に成功したものだけでなく、拒否されたり失敗したりしたものも含まれるため、エージェントの試行錯誤の過程を追跡できる。

  2. 編集または作成されたファイルの特定: エージェントがどのファイルを触ったのかを把握することは、コード変更の影響範囲を理解する上で不可欠である。jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | select(.name | IN("Edit", "Write")) | .input.file_path' "$T" | sort | uniq -c | sort -rnというコマンドは、EditやWriteといったツールコールを特定し、その対象となったファイルのパスを抽出する。ファイルパスとその編集回数が表示されるため、エージェントが頻繁に修正を試みた箇所を特定できる。ただし、sed -iのようなシェルコマンド経由でのファイル変更は、この方法では捕捉できない点に注意が必要である。

  3. エラーになったツールコールの検出: エージェントが実行したツールコールの中で、エラーとして返されたものを特定する。jq -rs 'def b: .message.content // [] | arrays | .[]; (map(b | select(.type=="tool_use") | {(.id): .name}) | add) as $n | .[] | b | select(.type=="tool_result" and .is_error) | [($n[.tool_use_id] // "?"), (.content | tostring | .[0:100])] | @tsv' "$T"というコマンドは、ログ全体を読み込み、ツールコールのIDとツール名をマッピングした後、エラーが発生したtool_resultを探し、対応するツール名とエラーメッセージの冒頭100文字を抽出する。これにより、どのツールでどのような種類のエラーが多発しているかを把握でき、問題の早期特定に繋がる。

  4. 権限拒否の確認: ユーザーが設定したセキュリティルールやパーミッションによって、エージェントの操作が拒否されたケースを特定する。jq -r 'select(.type=="user") | .message.content[]? | select(.type=="tool_result" and .is_error) | .content | tostring | select(test("has been denied"))' "$T"というコマンドは、エラー結果の中から「has been denied」という文字列を含むメッセージを抽出し、権限拒否の詳細を明らかにする。

  5. 処理が遅いツールコールの特定: エージェントの応答が遅いと感じた場合、どのツールコールがボトルネックになっているかを特定する。ログには直接的な実行時間のフィールドはないが、jqの高度な機能を使うことで、ツールコールの開始タイムスタンプと結果のタイムスタンプの差分から処理時間を概算できる。jq -rs 'def b: ...; def ms: ...; (map(.timestamp as $t | b | select(.type=="tool_use") | {(.id): {t: ($t | ms), name, input}}) | add) as $c | [.[] | .timestamp as $t | b | select(.type=="tool_result") | $c[.tool_use_id] as $u | select($u) | {s: ((($t | ms) - $u.t) / 1000), name: $u.name, what: ($u.input | tostring | .[0:60])}] | sort_by(.s) | reverse | .[:5][] | [.s, .name, .what] | @tsv' "$T"という長いコマンドは、全てのツールコールの処理時間を計算し、最も遅かった上位5つを表示する。

  6. 失敗後のエージェントの発言: エージェントが失敗した直後にどのような発言をしたかを追跡することは、エージェントがその失敗をどのように解釈し、次の行動計画を立てたかを理解する上で非常に有用である。jq -rs 'def b: ...; [.[] | .type as $r | b | if .type == "tool_result" and .is_error then null elif $r == "assistant" and .type == "text" then .text else empty end] | . as $s | range(1; length) | select($s[. - 1] == null and $s[.] != null) | "--- \($s[.][0:300])"' "$T"というコマンドは、失敗したツールコールの直後にエージェントが発したテキストメッセージを抽出する。これにより、エージェントが問題を認識してアプローチを変更したのか、あるいは同じことを繰り返し試しているのかを判断できる。

  7. 使用されたAIモデルのカウント: どのAIモデルが、どの程度の頻度で応答を生成したかを把握する。jq -rs 'map(select(.type=="assistant")) | unique_by(.message.id) | group_by(.message.model)[] | [.[0].message.model, length] | @tsv' "$T"というコマンドは、assistantタイプの行からmessage.modelを抽出し、message.idで重複を除外してからモデルごとに集計する。これにより、異なるモデルを使い分けている場合に、それぞれのモデルの貢献度を把握できる。

  8. Codexのログ解析: Codexのログ形式はClaude Codeとは異なるため、専用のjqコマンドが必要となる。Codexのログはtimestamp、type、payloadという主要なフィールドを持つ。

    • モデルごとの利用状況: jq -r 'select(.type=="turn_context") | .payload.model' "$R" | sort | uniq -cでturn_contextタイプから使用されたモデルを抽出する。
    • ツールコール: jq -r 'select(.type=="response_item") | .payload | select(.type=="function_call" or .type=="custom_tool_call") | [.name, ((.arguments // .input) | .[0:100])] | @tsv' "$R"でresponse_itemタイプの中からツールコールを特定し、その名前と引数の冒頭部分を抽出する。
    • トークン使用量: jq -c 'select(.payload.type == "token_count") | .payload.info.total_token_usage // empty' "$R" | tail -1でセッション終了時点の累計トークン使用量を確認できる。

これらのjqコマンドを使いこなすことで、AIコーディングエージェントの行動を深く理解し、その効率性や信頼性を評価できるようになる。これは、AIを活用したソフトウェア開発を進める上で、エージェントとのより効果的な連携を築き、最終的にはより高品質なシステムを構築するための重要なステップとなる。Hermes IDEのような統合開発環境は、このような情報を視覚的に提供することで開発者を支援するが、jqを使った直接的なログ解析スキルは、いかなるツール環境においても基本的なデバッグと理解の基盤を提供する。

関連コンテンツ

関連IT用語