Structured Output Design

Structured Output Design

概要

構造化出力の「契約」を設計し、スキーマ・命名規則・互換性方針を一貫させるスキル。仕様書を作成して関係者の合意形成を促進する。

詳細は references/Level1_basics.md から段階的に参照する。

ワークフロー

Phase 1: 契約要件の整理

目的: 出力仕様の目的、利用者、互換性要件を明確化する。

アクション:

1. 仕様の利用者と運用期間を整理する。
2. 互換性の許容範囲を定義する。
3. 命名規則とバージョン表現を決定する。

Phase 2: 仕様書とスキーマの設計

目的: 出力契約を文書化し、スキーマとテンプレートを整合させる。

アクション:

1. assets/output-contract-template.md を埋める。
2. assets/json-schema-template.json を基にスキーマを作成する。
3. 互換性・移行方針を明記する。

Phase 3: 検証とレビュー

目的: 仕様書とスキーマの不整合を解消する。

アクション:

1. scripts/validate-output-contract.mjs を実行する。
2. scripts/validate-schema.mjs でスキーマの構造を点検する。
3. 指摘事項を反映し版を確定する。

Task仕様ナビ

ベストプラクティス

すべきこと

• フィールドに型・制約・例を必ず記載する。
• 互換性の原則を明文化する。
• バージョン表現を出力に含める。
• 仕様変更は影響範囲を記録する。

避けるべきこと

• 必須/任意を曖昧にしたまま運用しない。
• 破壊的変更をサイレントに入れない。
• 仕様書とスキーマの不一致を放置しない。

リソース/スクリプト参照

references/

• references/Level1_basics.md: 基礎指針
• references/Level2_intermediate.md: 実務パターン
• references/Level3_advanced.md: 高度な設計指針
• references/Level4_expert.md: 専門領域の注意点
• references/schema-patterns.md: スキーマ設計パターン
• references/json-schema-patterns.md: JSON Schemaの具体例
• references/field-naming.md: 命名規則
• references/compatibility-strategies.md: 互換性戦略
• references/function-calling-guide.md: 関数呼び出し形式の注意点
• references/zod-integration.md: Zod統合の指針

assets/

• assets/output-contract-template.md: 出力契約書テンプレート
• assets/json-schema-template.json: JSON Schema雛形
• assets/schema-versioning-template.json: バージョン表現テンプレート
• assets/zod-schema-template.ts: Zod用テンプレート

scripts/

• scripts/validate-output-contract.mjs: 仕様書の必須項目検証
• scripts/validate-schema.mjs: JSON Schema構造検証

変更履歴