このページは英語でのみご覧いただけます。

LLM Structured Outputs

Pathruleルール2件 • メモリ1件 • スキル1件

LLM structured outputs replace prose parsing with an explicit schema contract, but schema-constrained generation does not make values correct or safe. This bundle versions schemas, distinguishes refusal and incomplete states, validates semantics, and migrates consumers deliberately. Unlike AI SDK, it defines a provider-independent data boundary rather than one library's generation and transport conventions.

推奨されるパスの配置

Pathruleは各要素を対応するパスに配置するため、アシスタントはそれが属する場所でだけ参照します。これはインポート時に適用されるスコープで、ワークスペースで調整できます。

/ ワークスペースのルート

migrate-llm-schema

src/

ai/

Validate syntax, schema, and semantics before side effects

Constrained generation is not trusted generation

schemas/

Version every structured-output contract

ルール

Validate syntax, schema, and semantics before side effects/src/ai高強制Model output crosses three validation layers before it can mutate state, call a tool, or reach another system.

1	Model output crosses three validation layers before it can mutate state, call a tool, or reach another system. A payload can be valid JSON and match a schema while containing impossible amounts, unauthorized identifiers, stale versions, or unsafe instructions. Enforce this boundary in /src/ai so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Separate transport completion, refusal, truncation, and provider error from the domain result type.
4	- Parse once and validate against the exact schema version requested from the provider.
5	- Apply domain checks for ranges, references, authorization, invariants, and current state after structural validation.
6	- Perform no write, message, charge, or tool call until every layer succeeds.
7
8	Verification: Feed malformed JSON, schema mismatches, refusal, truncation, valid but unauthorized IDs, and a fully valid payload; confirm only the final case reaches effects.

Version every structured-output contract/src/schemas高強制Schema identity and version travel with prompts, model requests, stored results, fixtures, and consumers.

1	Schema identity and version travel with prompts, model requests, stored results, fixtures, and consumers. Editing a shared schema in place makes old stored output ambiguous and can turn a harmless field rename into a production parsing failure. Enforce this boundary in /src/schemas so invalid work stops before it reaches another subsystem or creates an externally visible side effect.
2
3	- Give each contract a stable name and explicit version independent from the prompt or provider model name.
4	- Keep old readers while stored or in-flight results can still use the old version.
5	- Treat required-field, enum, type, meaning, and nesting changes as compatibility decisions with migration plans.
6	- Generate provider-specific schema subsets from one canonical domain contract when providers support different JSON Schema features.
7
8	Verification: Load fixtures for every supported version through current readers and reject an unknown version before domain work; test one planned migration end to end.

メモリ

Constrained generation is not trusted generation/src/aiA provider can constrain shape while the model still selects incorrect, fabricated, stale, or attacker-influenced values.

1	A provider can constrain shape while the model still selects incorrect, fabricated, stale, or attacker-influenced values. Keep the schema at the generation boundary to reduce parser ambiguity, then treat the parsed object exactly like untrusted API input.
2
3	Authorize referenced resources against the current principal and tenant. Resolve identifiers from trusted stores rather than accepting display text as authority. Keep high-impact decisions behind deterministic policy or human review even when the payload is structurally perfect. Keep the decision explicit at /src/ai; moving it into an incidental caller makes behavior depend on which route happened to execute first.
4
5	See /src/schemas for contract versions and /tests/ai for refusal and adversarial fixtures. That related boundary consumes this decision and carries the evidence that proves it still holds.

スキル

migrate-llm-schema/rootMigrate a structured-output schema, stored results, prompts, validators, and consumers without an ambiguous cutover.

1	---
2	name: migrate-llm-schema
3	description: Migrate a structured-output schema, stored results, prompts, validators, and consumers without an ambiguous cutover.
4	---
5
6	# Migrate Llm Schema
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Classify the proposed change as backward compatible, reader-compatible, or breaking for both generation and every downstream consumer.
11	2. Create the new schema version, provider adapter, fixtures, semantic validator, and dual-version reader before switching production requests.
12	3. Replay representative and adversarial inputs, compare refusal and validation rates, and migrate stored output only when its meaning can be preserved.
13	4. Roll out by cohort with version metrics, keep rollback readers, then retire the old version only after in-flight and stored dependencies are gone.
14
15	Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.

このパターンを使う理由

Agents parse model prose with regex, trust schema-constrained values without semantic validation, or change a shared schema without migrating stored output and consumers.

対象：Teams using model output to drive application state, tools, workflows, or persisted records

アシスタントが次のことをしないようにします。

Regex parsing of prose presented as a stable contract
Refusals and truncated output treated as valid business data
Schema changes that silently break stored results and downstream consumers

Markdownで表示

ライセンス: Apache-2.0
バージョン: 1.0.0
更新日: 2026-08-25