構造化出力

中級

What you'll learn

スキーマ強制された出力が、JSON を期待してプロンプトを書くより優れている理由を説明する
JSON Schema を渡し、レスポンスを型付きオブジェクト（Pydantic / Zod）にパースする
構造化出力とツール使用を、仕組みではなく意図で見分ける
タイトで信頼できるスキーマのための4つのコツを適用する
ひと言の判断ルールで正しいツールを選ぶ

Claude の出力が他のソフトウェアに渡るとき、信頼できる構造——既知の形に毎回一致する有効な JSON——が必要です。「JSON で答えて」と頼んで祈るのではなく、プラットフォームの構造化出力サポートを使いましょう。

このレッスンは、プロンプトで祈る方式がなぜ失敗するのかから、スキーマを強制して型付きオブジェクトにパースする方法まで導きます——そして、見た目がそっくりなときに構造化出力とツール使用をどう見分けるかも。上から下まで通して読み、終盤のクイズで自分を試してください。

信頼できる方法

出力の JSON Schema を渡し、API/SDK にそれを強制させてから、型付きオブジェクト（Python なら Pydantic、TypeScript なら Zod）にパースします。SDK の parse ヘルパーは、自分で JSON.parse して検証しなければならない文字列ではなく、型付きの結果を直接返してくれます。

Guided walkthrough1 of 3

必要な出力を JSON Schema としてモデル化します——Python なら Pydantic BaseModel で、TypeScript なら Zod スキーマで。

# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

調整できる具体的なリクエストが欲しいですか？モデルに渡すものの形は次のとおりです——モデルを自分のスキーマに置き換えてください。

スキーマ準拠の出力を求める

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

なぜ単にプロンプトで JSON を求めないのか？

プロンプトで JSON を頼むことはできますし、単純なケースでは機能します——しかしブレることがあります。余計な散文、末尾のカンマ、欠けたフィールド。スキーマ強制された出力はこの種のバグを取り除きます。これは、下流のシステムがそれに依存した瞬間に効いてきます。

Watch out

プロンプトされた JSON はデモでは動き、本番で壊れます。障害は下流のシステムがパースしたときにだけ現れます。
注意すべき典型的な3つのブレ：JSON の周りの余計な散文、末尾のカンマ、欠けた必須フィールド。