Claude Code CLIのJSON解析エラー対処法

症状：JSONのはずが「Extra data」で落ちる

Claude Code（Anthropicが提供するCLIツール）を、画面での対話を介さず-pオプション（プロンプトを渡すだけの非対話モード）で呼び出し、結果を--output-format jsonで受け取る場面がある。

自動化スクリプトから定期的に呼び出すような使い方では、この形式が便利になる。

ところが、返ってきたはずのJSON文字列をPythonのjson.loads()に渡すと、json.decoder.JSONDecodeError: Extra dataという例外が起きることがある。

出力を目視すると、内容自体は正しいJSONに見える。何が起きているのか分かりにくいエラーである。

原因：stdoutの末尾に別のログが混ざる

このエラーは、標準出力（stdout、プログラムが結果を書き出す通常の出口）に、JSON本体以外の文字列が続けて書き出されることで起きる。

原因として多いのが、MCP（Model Context Protocol、Claude Codeが外部ツールと連携するための仕組み）関連の診断ログである。

MCPサーバーとの接続状況や警告といった、処理そのものには影響しない情報が、JSON本体の直後にそのまま出力されてしまう場合がある。

json.loads()は文字列全体を1つのJSON値として厳密に解釈する関数であり、正しいJSONを読み終えたあとに余分な文字が1文字でも残っていると、そこで例外を投げて止まる。

つまり、JSON本体そのものは壊れていなくても、後ろに付いた無害なログのせいでパースが失敗する。

なぜ気づきにくいか

このエラーが厄介なのは、人が実行を確認しているときにはまず気づかない点にある。

ターミナルに出力を表示させて目で追う分には、JSONもログもどちらも文字として流れるだけで、エラーには見えない。

問題が表面化するのは、人が介在しない自動実行のパイプライン、たとえば定期実行のジョブがこのコマンドを叩き、結果をそのまま次の処理に渡すような構成である。

パース失敗によってジョブ全体が停止しても、原因のログはstdoutの奥に埋もれているため、外形的には「なぜか動かなくなった」としか見えない。

無人で動かす仕組みほど、こうした一見無害な出力の混入がそのまま停止要因になりやすい。

対処法：raw_decodeで先頭だけを読む

解決の方向は、「文字列全体が1つのJSONである」という前提を捨てることにある。

Pythonの標準ライブラリには、json.JSONDecoder().raw_decode()という、文字列の先頭からJSONとして解釈できる部分だけを読み取り、そこで読み終えた位置（インデックス）も一緒に返すメソッドがある。

import json

decoder = json.JSONDecoder()
data, end_index = decoder.raw_decode(raw_output)
# raw_output[end_index:] にMCPログ等の余分な文字列が残っていても無視できる

json.loads()が「全部読んでJSONでなければ失敗」なのに対し、raw_decode()は「先頭から読めるところまで読む」という向きの関数であり、末尾の余分な出力があっても構わずJSON本体だけを取り出せる。

出力形式が変わらない限り、json.loads()をraw_decode()に置き換えるだけで解決できる。

設計としての教訓：外部CLIのstdoutを信頼しすぎない

このエラーが示しているのは、外部コマンドの出力形式を「ドキュメント通りに整形されたJSONのはず」と決め打ちする危うさである。

CLIツールの出力は、本体の更新や依存する外部サービスの状態によって、想定していなかった行が混ざる余地が常にある。

無人で動かす自動化の仕組みを組むときは、外部プロセスの出力を受け取る境界で「厳密な形式チェックで落ちる関数」ではなく、「多少のノイズを許容して必要な部分だけ取り出す関数」を選んでおくと、こうした停止を未然に防ぎやすい。

会議や作業中の思いつきを録音してAIに要約させるAIボイスメモのような仕組みも、内部では音声認識や要約生成といった複数の処理を順番につないでいる。

どの段階の出力も「想定通りの形式で返ってくる」と決め打ちせず、崩れた出力を吸収できる設計にしておくことは、規模の大小を問わず無人パイプライン全般に共通する備えといえる。