ブログ • AI / Agent

AI Coding Agent はどう動くか？Claude Code、Codex、Xcode 27 Agent、Tool Calling と JSON データの完全解説

Claude Code、Codex、Xcode 27 を開くと、見た目はどれもチャットだ。リポジトリを変え、テストを走らせ、シミュレータを叩いているのは、あの自然言語の返答ではない。

AI Coding Agent の動き方はこうだ。モデルが次の一手を推論し、Tool Calling を出す。ローカルまたは IDE 内の harness がツールを実行し、構造化データとして結果を戻す。引数も結果も、ほとんど JSON だ。

この記事では：

• Coding Agent が補完に対して足している層は何か
• 共通のループ：観察 → 判断 → 実行 → 書き戻し
• Tool Calling の arguments が JSON 文字列である理由
• Claude Code、Codex、Xcode 27 Agent がツール箱をどこに置くか
• JSON / JSON Schema をどの層で検証するか、JSONNote でローカルに分解する方法

チャット枠ではなく、ループだ

補完が解くのは「次の一行は何か」。Coding Agent が解くのは「この目標を実プロジェクトでどうやり切るか」——文脈を読み、ツールを選び、コードを変え、コマンドを実行し、結果を見て、また判断する。

公式ドキュメントの言い方は変わる。形は同じだ。Claude Code は「文脈を集める → 行動する → 結果を検証する」と書く。Xcode 27 は先に計画し、ファイルを変え、ビルド / テスト / Preview / シミュレータで自己検証する。下層はどちらも：

1. 1
   観察

   ファイルを読み、シンボルを探し、git の状態を見、落ちたテストのログを取る。この一歩が無いと、あとのパッチは当て推量だ。

2. 2
   判断

   モデルは文脈の中で次の一手を選ぶ。また読む、また探す、一箇所を変える、コマンドを一本走らせる、あるいはあなたに聞く。

3. 3
   実行

   harness が tool call を受け、権限と sandbox の下で本当に走らせる。この時点でモデルはディスクに触れない。

4. 4
   書き戻し

   ツール結果はテキストまたは JSON になり、文脈に戻る。モデルは新しい証拠で続き、あるいは完了を宣言する。

あなたもこのループにいる。割り込み、方向転換、高リスク操作の承認。モデルは推論を担う。harness はツール、権限、セッション、「完了の定義」を担う。四社が制御権をどう争うかは次を参照：

AI Coding Agent はもうコード補完だけではない：Codex、Claude Code、OpenCode、DeepSeek Harness は何を争っているのか？

本稿は「ループがどう回るか、JSON がどのホップに現れるか」だけを分解する。技術スタックの層は次を参照：

2026 AI Agent 技術スタック：LLM、MCP、Function Calling、JSON Schema。

Tool Calling：引数は JSON

Tool Calling（Function Calling とも呼ばれる）は「モデルがコードを書ける」の別名ではない。構造化された関数呼び出しだ。モデルは宣言したツール一覧から名前を選び、引数契約に合う JSON を生成する。

OpenAI 互換 API では、ツール定義の parameters 自体が JSON Schema だ：

{
  "type": "function",
  "function": {
    "name": "run_tests",
    "description": "Run the project test suite and return a structured summary.",
    "parameters": {
      "type": "object",
      "properties": {
        "suite": { "type": "string", "enum": ["unit", "integration", "e2e"] },
        "path": { "type": "string", "minLength": 1 }
      },
      "required": ["suite"],
      "additionalProperties": false
    }
  }
}

モデルが返すとき、arguments はしばしば文字列であり、すでに parse 済みのオブジェクトではない：

{
  "id": "call_8f21",
  "type": "function",
  "function": {
    "name": "run_tests",
    "arguments": "{\"suite\":\"unit\",\"path\":\"src/auth\"}"
  }
}

だから業務層は少なくとも二つのことをする。まず文字列を合法な JSON に解析し、宣言した schema でフィールド、型、列挙を検証する。欠けた引用符、余分なカンマ、未宣言キーは、このホップで起きる。「モデルが賢く見えた」層ではない。

一巡はこうだ。リクエストに schema を載せる → モデルがツールを選び arguments を生成する → 解析して検証する → ツールを実行する → 結果を tool message として戻す → モデルが続ける。schema がはっきりしていれば、最初の引数が当たる。曖昧なら、ループは空転する。

契約の書き方、JSON Mode と Strict Schema の差は次を参照：

AI Agent に JSON Schema はなぜ必要？Tool Calling から Structured Output まで完全解説。

Claude Code：内蔵ツール + 拡張層

Claude Code の公式ドキュメントは Agent を二部に分ける。推論を担うモデルと、行動を担うツール。ツールが無ければ Claude は文字しか返せない。あればリポジトリを読み、ファイルを変え、コマンドを実行し、Web を検索できる。

内蔵ツールはだいたい五種類だ。ファイル操作（Read / Edit / Write）、検索（Grep / Glob）、実行（Bash）、Web（WebSearch / WebFetch）、プラグインが要るコード知能（定義へジャンプ、型エラー）。子 Agent と、あなたへの質問もツールだ。オーケストレーション用である。

「落ちたテストを直す」が一巡すると、だいたいこうなる：

1. 1
   Bash でテストを走らせる

   先にどのアサーションが落ちたかを見る。コードを触るのはそのあとだ。

2. 2
   Grep / Read でソースを特定する

   スタックとシンボルで、必要な文脈を窓に読み込む。

3. 3
   Edit で精密に置換する

   公式は先に読んでから変えろと言う。old_string → new_string。盲目の書き込みを避ける。

4. 4
   もう一度テストで検証する

   結果は文脈に戻る。失敗したらまた回す。「直ったはず」と口で言わない。

拡張層はこのループの上に乗る。置き換えない：

• CLAUDE.md：どのセッションも知っておくべきプロジェクト規約
• Skills：必要になったときだけ載せるワークフロー。経験を全部システムプロンプトに詰め込まない
• MCP：外部システムのツール。既定は必要時検索で、文脈の膨張を抑える
• Hooks / Permissions：確定的な遮断。危険コマンドと保護パスを、モデルの毎回の記憶に頼ってはいけない

Claude Code のエンジニアリング上の妥協ははっきりしている。確率的な Agent + 確定的な Hooks。セッション自体も JSONL に落ち、再開と分岐がしやすい——デバッグしているのは「一段のチャット」ではなく、tool イベントの列だ。

Codex：sandbox、承認、JSONL

Codex も Agent loop を回す。ただし製品の中心は「モデルが生成したコマンドをどう着地させるか」だ。ターミナルで

Codex CLIを走らせるときは、先に sandbox と承認を選び、それからモデルを動かす。

自動化ではcodex exec --jsonを使う。標準出力は JSONL になる。thread / turn の開始と終了、コマンド実行、ファイル変更、MCP 呼び出し、計画の更新。CI スクリプトが消費するのはイベントストリームであり、散文ではない。

{"type":"item.completed","item":{"id":"item_12","type":"command_execution","command":"npm test -- src/auth","exit_code":1,"aggregated_output":"FAIL src/auth/session.test.ts"}}
{"type":"item.completed","item":{"id":"item_13","type":"file_change","path":"src/auth/session.ts","kind":"update"}}
{"type":"turn.completed","usage":{"input_tokens":18420,"output_tokens":966}}

下流に安定したフィールドが要るときは--output-schemaで最終返答を JSON Schema に合わせる。Tool Calling の parameters と同じ種類の契約だ。縛るのは「タスク終了時のその JSON」であり、途中のコマンド一つひとつではない。

既定のcodex execは読み取り専用 sandbox だ。ファイルを変えるなら明示的に--sandbox workspace-writeを足す。ディレクトリを増やすときは先に--add-dirを使い、いきなりdanger-full-accessに飛ばない。

Xcode 27 Agent：計画、検証、エディタツール

Apple は WWDC 2026 で、Xcode 27 を「Apple プラットフォームで Agent と一緒にコードを書く場所」と位置づけた。ターミナル Agent と違い、ツール箱は IDE の中にある。

Apple のニュース記事と

Xcode, agents, and you、

What’s new in Xcode 27が、いくつかをはっきり書いている。

• 会話はエディタのペインに入り、コードと並べて表示でき、diff と成果物を見られる
• /planで先にリポジトリを探り、案を出す。すぐにはソースを変えない。子 Agent を並行で立ち上げて文脈を集められる
• 実装段階では Xcode 自身のツールで検証する。ビルド、テスト実行、SwiftUI Preview の描画、シミュレータまたは Device Hub で App を叩く
• ビルドエラーは Agent に直接戻り、失敗ログを見てまた変え、またビルドする
• モデルは一社に縛られない。Anthropic、Google、OpenAI、およびローカルモデル
• MCP で外部ツールをつなぎ、ACP で外部 Agent（OpenCode など）を Xcode に入れる

WWDC のラボは Chat と Agent を能力差として語り、文言の差としては語らない。Chat のツールは小さく固定。Agent モードはコマンドラインと Xcode 内部ツール（ビルド、テスト、Preview、シミュレータ）を足す。既定の安全モードは権限プロンプトだ——Agent はタスクに必要なものに届くが、ディスクを勝手に歩き回れない。

JSON 開発者にとって、Xcode のこのホップの要点は、検証結果も構造化して書き戻されることだ。ビルド失敗、テスト要約、Preview の成果物は、Agent の次の入力になる。バックエンドで見るのは、たいてい自分の API の JSON。IDE では、同じループが Xcode ツールの出力を消費する。

システム級の Siri AI が使うのは App Intents であり、このエディタ Agent ではない。「Apple の Agent は一種だけ」と二本を混ぜないこと。次を参照：

Siri AI は AI Agent になるか？。

三社対照：同じループ、違うツール箱

機能一覧は似てくる。差は既定ツール、実行境界、そして結果が次の文脈になる経路だ。

選び方は短くてよい。汎用の多言語リポジトリと再利用できる Skills なら Claude Code。実機で走らせ、権限を CI に書きたいなら Codex。目標が Apple プラットフォームで、検証が Xcode ツールチェーンを通らねばならないなら Xcode 27。Xcode の ACP があれば、Xcode 27 を選んでも前二者を捨てなくてよい——外部 Agent はエディタに入れる。ビルドと Preview はなお Xcode のツールだ。

JSON データはどの層にあり、誰が検証するか

三社の UI は違う。JSON が現れる位置は安定している：

いちばん大事なのはこれだ。API 層の schema はモデルの生成を導く。業務層の schema は汚いデータを拒む。二層は互いに代替できない。AI の出力にまず schema が要る理由は次を参照：

AI に JSON Schema が必要な理由。

Coding Agent 向けのツール schema では、「いつ呼ぶか、いつ呼ばないか」を書き、選択肢は enum に入れ、description に埋め込まない：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["action", "path"],
  "properties": {
    "action": { "type": "string", "enum": ["read", "edit", "test"] },
    "path": { "type": "string", "minLength": 1 },
    "suite": { "type": "string", "enum": ["unit", "integration"] },
    "old_string": { "type": "string" },
    "new_string": { "type": "string" }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "if": { "properties": { "action": { "const": "edit" } } },
      "then": { "required": ["old_string", "new_string"] }
    },
    {
      "if": { "properties": { "action": { "const": "test" } } },
      "then": { "required": ["suite"] }
    }
  ]
}

モデルが{"action":"edit","path":"src/a.ts"}を返しても old_string が無ければ、schema が実行層で止める。あとから diff を見るより安い。

JSONNote で tool 引数をデバッグする

Agent 開発で遅い部分は、めったにプロンプトではない。遅いのは一度の失敗した tool call だ。JSONNote はブラウザローカルで動く。鍵もリポジトリの中身もアップロードしない。

1. 1
   まず arguments が parse できるかを見る

   モデルが返した文字列をJSON フォーマットに貼る。欠けた引用符、末尾カンマ、チャットアプリで切れた hash は、ここで見える。

2. 2
   次に schema で検証する

   ツール定義と実際の arguments をJSON Schemaに並べる。enum の誤り、required の欠落、余分なフィールドは、モデルの「すみません」より役に立つ。

3. 3
   二回の呼び出しを比べる

   description を直したあと、あるいは additionalProperties: false を足したあと、JSON Diffで引数の回帰を見る。

4. 4
   デバッグ現場を共有する

   URL Hash 共有で tool JSON をリンクに埋め込む。同僚が開けば再現できる。データはサーバを通らない。

よくある質問

AI Coding Agent とコード補完の本質的な違いは？

補完は次の一行を提案するだけ。Coding Agent はリポジトリを読み、ファイルを変え、コマンドを実行し、外部ツールを呼び、ループの中でツール結果に応じて判断を続ける。差は文の上手さではなく、行動できるかどうかだ。

モデルはディスク上のファイルを直接変えるか？

いいえ。モデルが生成するのは tool call だけで、たいていは一段の JSON。本当にファイルを書き、shell を走らせ、シミュレータを叩くのはローカルの harness。ツールが無い、権限が拒まれる、引数の検証が失敗する——ディスク上では何も起きない。

Claude Code、Codex、Xcode 27 Agent のどれが良いか？

統一の勝者はない。汎用リポジトリと Skills / MCP なら Claude Code。sandbox、承認、CI の JSONL イベントなら Codex。Apple プラットフォームでビルド / Preview / シミュレータ検証が要るなら Xcode 27 Agent。Xcode は ACP で外部 Agent もつなげる。

モデルがすでに schema に沿って埋めているのに、なぜ自分で JSON を検証するのか？

モデルが埋める引数は緩い制約だ。arguments はしばしば文字列で、フィールドの欠落、型の誤り、未宣言キーの追加が起きる。本番経路はなお parse + JSON Schema 検証のあと、業務層へ渡す。Codex の --output-schema も最終返答だけを縛り、各ステップの tool 結果の検査の代わりにはならない。

Xcode 27 の Agent は Apple 自身のモデルしか使えないか？

いいえ。Xcode 27 は Anthropic、Google、OpenAI のモデルと Agent を同じエディタワークフローにつなぎ、ローカルモデルも支える。ACP で外部 Agent、MCP で外部ツールもつなげる。変わるのはツール箱と検証の手段であり、ループそのものではない。

まとめ

三社の見た目は、これからもチャットに見え続ける。下の一文は変わらない：

Coding Agent = モデルの判断 × Tool Calling × harness の実行。JSON はツール引数と書き戻し結果の共通の形だ。

先にループを見定め、それからツール箱を選ぶ。Claude Code は汎用 Agent を強化し、Codex は sandbox とイベントを握り、Xcode 27 はビルドと Preview を検証ツールにする。schema は宣言に書き、検証は実行層に置き、デバッグはブラウザローカルに残せる。

← ブログに戻る