プロンプトと出力契約

まず 1 回の要求で、原文が示す事実、返してよい内容、確認が必要な項目を決めます。注文フォームの事前入力を例に、タスク定義・欠損値・構造制約・業務検証をつなぎます。有効な JSON でも、値の根拠と利用条件の確認が必要です。

プロンプトで目標、入力、境界を記述

「あなたは専門家です。正確に抽出してください」というだけでは、「正確」の定義が不明確です。検証可能なタスクとは、少なくとも以下を明確にするものです：入力は何か、どのフィールドが必要か、どの程度まで推論を許容するか、欠損や競合をどう処理するか、最終結果を誰が使うか。プロンプトエンジニアリングでも、変更が有効かどうかを比較するためには、まず成功基準が必要です。Prompt engineering overview

例えば、入力が「A1が欲しい。数量は後で確認」とする場合、タスクが sku と quantity のみを要求すると、モデルは 1 と推測する可能性があります。未知の数量は null と規定し、needs_input フラグを立てることで、「答えがないこと」を正当な結果として扱えます。

安定したルールは信頼性の高い指示層に配置できます。現在の資料では、出典が明確なデータを提供しています。メッセージのロールやコンテンツブロックはインターフェースの構造であり、単なるテキストの適当な連結として扱うべきではありません。XML タグ、見出し、または区切り文字はコンテンツを区別するのに役立ちますが、安全な分離を保証するものではありません。外部資料中の「以前のルールを無視せよ」といった指示も、データ処理として扱う必要があります。

教育的なプロンプトは以下のように構成できます：

タスク：ユーザー原文から商品 SKU と数量を1つ抽出し、人間による確認前のフォーム自動入力用とする。
ルール：原文に明示的に記載されている情報のみを使用する。欠損フィールドは null。
ステータス：2つのフィールドが明確で競合がない場合、complete。それ以外の場合、needs_input。
範囲：注文の作成、プロフィール情報の照会、支払い情報の推論を行わない。
出力：提供されたスキーマに従う。結果の前後に説明文を追加しない。
ユーザー原文：A1が欲しい。数量は後で確認。

プロンプト内の「範囲」はモデルに何を行うべきかを指示しますが、実際のツール権限は実行側で管理されます。操作権限を一文で記述するだけでは、Agent ループ における実行前の検証を代替できません。

具体例で実際の曖昧さを解消

few-shot の例は、具体的な入出力を通じて規約を説明します。null、列挙型、単位、競合など、抽象的なルールが誤解されやすい場面に適しています。必ずしも例が多いほど良いわけではなく、正例だけで境界条件の説明を代替できるわけでもありません。

スキーマに曖昧さを表現する余地がない場合、例がどれだけ優れていても無理やり値を埋めることを避けられません。まずはデータモデルを調整し、次に表現を調整します。開発中のテストケースをすべて例として書き込み、それらの改善を汎化能力の向上と見なさないでください。

多様なケースが必要な場合は、各ケースが制約やトレードオフにおいて異なることを明示的に指定します。短い出力が必要な場合は、文字数とフィールドを直接規定します。temperature、effort、文字数制限はそれぞれ異なる問題を制御するものであり、temperature=0 → effort=low のような変換公式として記述すべきではありません。詳細なメカニズムについては、トークンとサンプリング および 推論と思考 を参照してください。

構造制約の適用範囲

プロンプトで JSON を要求するだけでは、モデルが文字通りの規約に従うように促すに過ぎません。制約付きデコーディングは、生成時に有効な出力の継続を制限し、完全な成功出力がサポートされるスキーマに適合するようにします。クライアント側での検証は生成後のチェックであり、サービスがサポートしない制約を追加できますが、生成済みのトークンを後から変更することはありません。

Claude の output_config.format は JSON レスポンス用に使用され、ツール上の strict: true は厳格なツール呼び出し用に使用されます。これらを組み合わせることは可能ですが、利用可能なスキーマのサブセットや機能互換範囲は、対象モデルおよび SDK に照らして確認する必要があります。構造化出力

JSON Schema 自体の境界

properties はフィールドを記述しますが、これらのフィールドが必須であることを示すものではありません。必須かどうかは required で宣言します。additionalProperties: false は未定義のフィールドを拒否しますが、定義済みフィールドを自動的に必須にはしません。null は値であり、フィールドが存在しないこととは異なります。JSON Schema object

例えば、quantity フィールドは常に存在するが、不明な場合は null であるようにしたい場合、required と nullable 型の両方を指定する必要があります。これを integer として定義し required に設定すると、「原文に数量がない」場合、期待される表現（null）が得られなくなります。

ベンダーの構造化出力は、JSON Schema のサブセットのみをサポートする場合があります。一部の SDK は、完全なスキーマをサービスがサポートする簡略形式に変換し、クライアント側で元の制約に基づいて検証します。これは、サポートされていないフィールドを含む生の JSON リクエストを直接送信することとは異なります。「SDK が受け入れ可能」だからといって、「サーバー側で生成時にすべての制約が強制される」と解釈してはいけません。SDK スキーマ変換の説明

有効な JSON から利用可能な結果まで

数量を3から5にすると JSON と型は通っても原文の根拠が失われます。3のまま在庫を減らすと業務条件で失敗します。独立した判定から修正すべき層を特定できます。

失敗時のパスに対する出力設計

構造化出力の保証は、インターフェースがサポートし、レスポンスが完全なパスに限定する必要があります。切り捨て、拒否、転送エラー、キャンセルは独立して処理する必要があり、最初の text ブロックを取得してデータベースに書き込むだけでは不十分です。

クライアント側では、有限のリトライや特定フィールドの修正要求が可能ですが、リトライには上限を設け、コストとして記録する必要があります。失敗が情報欠落に起因する場合、同じ入力を繰り返しても事実が自動的にに補完されるわけではありません。以前にツールの副作用が実行されていた場合、解析失敗を理由にタスク全体をリプレイしてはいけません。

構造化レポートの出典を保持するには、独自のスキーマにドキュメント ID、証拠の位置、バージョンを含め、アプリケーション側で検証します。ベンダー内蔵の citations が特定の構造化出力と同時に使用可能かどうかは、具体的な機能互換性の問題であり、「JSON と追跡可能性は共存できない」ことを意味するものではありません。検索証拠の完全性については、RAG を参照してください。

完全なローカル検証の例

以下のスキーマは、アプリケーション側での完全な検証用に使用され、対象サービスが其中的なすべてのキーワードをそのままサポートできることを保証するものではありません。この例は Python の jsonschema パッケージに依存し、正常な結果、欠損結果、余分なフィールド、誤った型、フィールド間の矛盾を検証します。モデルを呼び出すことも、注文を作成することもありません。

from jsonschema import Draft202012Validator, ValidationError

schema = {
    "type": "object",
    "properties": {
        "sku": {"type": ["string", "null"], "minLength": 1},
        "quantity": {"type": ["integer", "null"], "minimum": 1},
        "status": {"type": "string", "enum": ["complete", "needs_input"]},
    },
    "required": ["sku", "quantity", "status"],
    "additionalProperties": False,
}
Draft202012Validator.check_schema(schema)
validator = Draft202012Validator(schema)

def check(data):
    validator.validate(data)
    fields_present = data["sku"] is not None and data["quantity"] is not None
    if (data["status"] == "complete") != fields_present:
        raise ValueError("ステータスとフィールドの完全性に不一致がある")
    return data

assert check({"sku": "A1", "quantity": 3, "status": "complete"})["quantity"] == 3
assert check({"sku": "A1", "quantity": None,
              "status": "needs_input"})["quantity"] is None
bad = [
    {"sku": "A1", "quantity": True, "status": "complete"},
    {"sku": "A1", "quantity": 0, "status": "complete"},
    {"sku": "A1", "quantity": None, "status": "complete"},
    {"sku": "A1", "status": "needs_input"},
    {"sku": "A1", "quantity": 3, "status": "complete", "extra": 1},
]
for item in bad:
    try:
        check(item)
    except (ValidationError, ValueError):
        pass
    else:
        raise AssertionError(f"無効な結果が受け入れられた: {item}")
print("正常/欠損結果は通過、5種類の無効な結果は拒否された")

この簡略化されたデータモデルは欠損のみを表現し、複数商品や競合は表現していません。実際のタスクでこれらの状態が必要な場合、対応するフィールドとルールを追加する必要があり、fields_present を完全性の判定基準として使い続けることはできません。この例では、SKU が存在するか、数量が原文から来ているか、在庫が十分かどうかも検証していません。これらは出典とビジネス検証の領域です。

アクションを実行する際には、リアルタイムの状態を再度検証する必要があります。例えば、抽出時には在庫が十分でも、提出時には売り切れている場合、スキーマではこの競合状態は解決できません。パラメータ検証、ビジネス制約、トランザクション処理は、対応するシステム内で完了させる必要があります。

プロンプトとスキーマのバージョン管理を一体化する

プロンプト、スキーマ、モデル、SDK、検証ロジックのバージョンを記録します。フィールドを nullable から required へ変更したり、列挙型に新しい値を追加したり、単一オブジェクトを配列で置き換えたりすると、ダウンストリームの動作が変わる可能性があります。モデルの出力だけでなく、旧来の消費者が新版の結果をどのように処理するかを検証する必要があります。

評価セットは、正常な入力、欠損、競合、ノイズ、長い入力、悪意のある材料、切り捨てをカバーする必要があります。構造の有効性、フィールドの正確性、未知値の処理の正しさ、そして実際のタスク成功率を個別に集計します。JSON がすべて合法でも事実が間違っている場合、構造制限を追加し続けるのは効果的ではないかもしれません。証拠、プロンプト、モデル能力の位置づけの問題に戻って検討する必要があります。

意味のある少量の例と明確な規約を保持し、互いに矛盾する重複する要求を削除します。変更のたびに、評価と観測可能性 のタスクレベル比較検証を行います。

次に読む：コンテキストエンジニアリング。