Claude Codeの--output-format jsonで回答をJSON化する — READMEの1行を10分で受け取る
Claude Codeをこれから動かす人が、練習用READMEのStatusを読み、その答えをJSONのresult欄で受け取るための手順です。
この記事で扱う機能は--output-format jsonの一つだけ。最初の成功は、ターミナルに"result": "ready"が見えることです。
前提はmacOSまたはLinuxのターミナルと、Claude Codeを利用できるアカウントです。Windows向けの手順はここでは動作確認していません。
更新・公式確認日: 2026-10-18
--output-format jsonとは何か
AIエージェントは、質問に文章で答えるだけでなく、必要に応じてファイルを読むなどの道具を使い、依頼を進めるAIです。ここではClaude Codeに、手元の練習用ファイルを読んでもらいます。
CLIは、画面上のボタンではなくターミナルに文字を入力して操作する方法。ターミナルは、コマンドという短い指示文を入力するアプリです。JSONは、"名前": "値"のように情報の名前と値をセットで並べる形式です。普段の会話として読むより、後からプログラムに渡しやすい形だと考えると分かりやすいです。
Claude Codeの-pは、質問を一回実行して終了する使い方です。これに--output-format jsonを付けると、通常の文章の代わりに、回答と実行情報を含むJSONが出ます。今回見る場所はresultです。たとえば"result": "ready"なら、回答の本文がreadyだったということ。session_idなど他の項目まで覚える必要はありません。
ここで大事なのは、JSONにしたからAIの答えが正しくなるわけではないことです。答えを置く「箱」の形が変わるだけ。元ファイルと結果を照らして、人が確認する一歩は残ります。
最初の準備: インストールからサインインまで
ここからはmacOS/Linuxの例です。ターミナルを開き、公式のインストールコマンドを実行します。ダウンロードしたスクリプトを実行する形なので、URLを公式ページで確認してから貼り付けてください。すでにClaude Codeを使える人は、この段落を飛ばして構いません。
curl -fsSL https://claude.ai/install.sh | bash
完了したら新しいターミナルを開き、存在を確認します。バージョン番号が表示されればインストール確認は成功です。番号は更新で変わるため、記事の数字と一致させる必要はありません。
claude --version
初回はclaudeで対話画面を開き、画面の案内に従ってブラウザでサインインします。Claude Codeは公式案内によると、対象のClaude有料プラン、Consoleアカウント、または対応するクラウドプロバイダーが必要です。無料のclaude.aiプランだけで使えると誤解しないでください。契約・利用枠に関わる条件は変わり得るため、使用前に公式ページを確認してください。
claude
サインインが済んだら、この練習のためのターミナルへ戻ります。認証済みか気になる場合は、claude auth statusで確認できます。ただし表示にはアカウント情報が含まれる場合があります。スクリーンショットや記事へそのまま貼らないでください。
10分で動かす: 匿名READMEを1回読む
READMEは、フォルダの説明を書いておくテキストファイルです。実際の仕事のファイルを最初からAIに渡す必要はありません。まずは自分で作った一行だけで試します。以下はmacOS/Linuxのシェルで実行する例です。mkdirはフォルダを作り、cdはそのフォルダへ移動し、printfは文字をファイルへ書きます。
mkdir -p ~/claude-json-practice
cd ~/claude-json-practice
printf 'Status: ready\n' > README.md
cat README.md
catの結果がStatus: readyなら、入力ファイルの準備は完了です。ここまではAIを使っていません。先に自分の目で入力を見ておくと、後で答えの確認がしやすくなります。
では、Claude Codeに1つだけ頼みます。英語の依頼文は「README.mdを読み、Statusの後ろの値だけを報告して」という意味です。自然文の依頼は日本語でもかまいませんが、下の一行は実際に試した形にそろえています。
claude -p 'Read README.md and report only the value after Status.' --output-format json
出力は長く見えるかもしれません。今回探すのは次の一部分です。実際のJSONには実行時間など別の項目も付き、内容や順番は実行環境で変わります。
{
"result": "ready",
"is_error": false
}
この二行は見やすく抜き出した例示で、実行結果の全文ではありません。resultがreadyで、手元のREADMEもStatus: readyだったら初回成功です。JSONの記号を全部理解しなくても、「名前がresultの欄に答えがある」と読めれば十分です。
今回、匿名の練習フォルダでClaude Code 2.1.299を使って実行したところ、終了コードは0、resultはready、is_errorはfalseでした。ただしAIの回答は毎回完全に同じになると保証されません。resultに前置きが混じったら、READMEと照らしつつ依頼文を「値のみ返す」と具体化してください。ここでいう終了コード0は、コマンドが正常終了したことを示すもので、読み取った内容の正しさまで保証する数字ではありません。
JSONにする便益はどこにあるか
一度だけ人が答えを読むなら、通常の文字出力でも十分です。JSONが役立つのは、次の作業へ結果を渡すとき。たとえば、複数の練習用ファイルを後で確認する仕組みを作るなら、「文章の何行目か」を探すより「result欄」を読む方が扱いやすくなります。
ただし、機械に渡す前に確認する点が二つあります。一つは、元のファイルに秘密情報が入っていないか。もう一つは、AIの答えが元ファイルと一致するかです。今回のStatus: readyは、外へ出しても困らない架空の値にしています。会社のREADMEや顧客情報を試しに入力するのは避けてください。
JSON全体には、回答以外の実行情報が含まれます。セッション識別子などを人に見せる必要はありません。SNSへ共有するときも、JSON全文ではなく、必要な箇所だけを抜き出して匿名化するのが無難です。この記事でも実測JSONの全文を載せていません。
つまずいたときの確認場所
1. claude: command not foundと出る
インストール後に開き直した新しいターミナルでclaude --versionを試します。そこで見つからない場合は、インストール先がターミナルの検索経路（PATH。コマンドを探すフォルダの一覧）に入っていない可能性があります。むやみに別のインストール方法を重ねず、末尾の公式セットアップにあるPATH案内から確認してください。
2. サインイン画面が出る、または利用できない
まずclaudeを単独で起動し、公式の初回サインイン案内に従います。利用可能なプラン・アカウントが必要です。ブラウザの認証画面や契約画面は、この記事のコマンドだけでは代行できません。認証情報やエラーメッセージの全文を公開の質問欄へ貼らないでください。
3. resultがreadyにならない
最初にpwdで現在のフォルダを確認し、cat README.mdで内容を確認してください。cd ~/claude-json-practiceを忘れると、別のREADMEを読んでいるかもしれません。Status: readyの綴りが違えば、AIの返答も変わります。まずファイルを正してから同じコマンドを再実行すると、原因を一つずつ切り分けられます。
4. JSONが長く、どこを読めばよいか分からない
"result":を探してください。ターミナルの検索機能を使っても構いません。is_errorがtrueなら、回答と見なして先へ進まず、エラー内容を確認します。result以外の利用量や識別子を、今回の初回成功の条件に含める必要はありません。
5. 出力が通常の文章に見える
コマンド末尾の--output-format jsonをコピーし損ねていないか確認します。-pだけなら通常の文字出力です。ハイフンは半角の--、jsonは小文字です。ターミナルへ貼るときに、装飾された引用符へ置き換わっていないかも確かめてください。
使いどころと限界
この方法が向くのは、AIの一回の回答を次の作業でも参照したい人です。resultという取り出し口を知っておくと、後でスクリプトへつなぐときの迷いが減ります。スクリプトは、同じ手順を繰り返すための小さなプログラムのことです。この記事では作成まで進めません。今日の目標は、まず1回、自分の手で結果を出すこと。
逆に、READMEの1行を目で確認するだけならcat README.mdで十分です。AIを呼ぶ必要すらありません。また、JSONは回答を整列させる形式であり、回答の正しさや必ず同じ文章が返ることを保証しません。出力には処理のメタデータも入るので、むしろ単純な読み物としては普通の文章より見づらい場合があります。
最初は小さな架空ファイルで成功させ、役に立つ場面だけで使う。これくらいが、AIエージェントを気負わず道具として始める距離感かなと思います。
次の一歩は一つだけ。練習用READMEのreadyを別の架空の値に書き換え、同じコマンドをもう一度実行して、resultがその値を反映するか確かめてみてください。試した後に「入力を変えると結果も変わる」を自分の目で確認できます。
参考リンク
- Claude Code CLI reference（
-pと--output-format） - Claude Code headless guide（JSON出力と
result欄） - Claude Code Quickstart（インストールと初回サインイン）
- Claude Code setup（利用条件とインストール確認）
上記の公式ページは2026-10-18に確認しました。本文のClaude Code実行例はmacOSの隔離フォルダで検証しました。Windowsのコマンド例はこの記事では動作未確認です。
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。続きはXで。