Structured Output Design

概要

構造化出力設計は、AI からの出力をプログラムで確実に処理可能な形式で 取得するための設計技術です。

主要な価値:

• 型安全な出力によるバグの削減
• パース失敗の防止
• バリデーションによる品質保証
• 開発者体験の向上

リソース構造

structured-output-design/
├── SKILL.md
├── resources/
│   ├── json-schema-patterns.md      # JSON Schema設計パターン
│   ├── function-calling-guide.md    # Function Calling設計ガイド
│   └── zod-integration.md           # Zod統合ガイド
├── scripts/
│   └── validate-schema.mjs          # スキーマ検証スクリプト
└── templates/
    ├── json-schema-template.json    # JSON Schemaテンプレート
    └── zod-schema-template.ts       # Zodスキーマテンプレート

コマンドリファレンス

リソース読み取り

# JSON Schema設計パターン
cat .claude/skills/structured-output-design/resources/json-schema-patterns.md

# Function Calling設計ガイド
cat .claude/skills/structured-output-design/resources/function-calling-guide.md

# Zod統合ガイド
cat .claude/skills/structured-output-design/resources/zod-integration.md

スクリプト実行

# スキーマ検証
node .claude/skills/structured-output-design/scripts/validate-schema.mjs <schema.json>

テンプレート参照

# JSON Schemaテンプレート
cat .claude/skills/structured-output-design/templates/json-schema-template.json

# Zodスキーマテンプレート
cat .claude/skills/structured-output-design/templates/zod-schema-template.ts

ワークフロー

Phase 1: 出力構造の設計

目的: 必要な出力データの構造を定義

設計要素:

• 必須フィールドの特定
• データ型の決定（string, number, boolean, object, array）
• ネスト構造の設計
• 配列要素の型定義

判断基準:

• すべての必要フィールドが定義されているか？
• 各フィールドの型が適切か？
• ネストの深さは適切か（3 階層以内推奨）？

Phase 2: 制約の定義

目的: データの有効性を保証する制約を設定

制約タイプ:

• 文字列制約: minLength, maxLength, pattern, format
• 数値制約: minimum, maximum, multipleOf
• 配列制約: minItems, maxItems, uniqueItems
• オブジェクト制約: additionalProperties, dependencies

判断基準:

• バリデーションルールが明確か？
• エラーメッセージが適切か？
• 制約が厳しすぎないか？

Phase 3: スキーマの実装

目的: JSON Schema または Zod で実装

JSON Schema 形式:

{
  "type": "object",
  "properties": {
    "field": { "type": "string" }
  },
  "required": ["field"]
}

Zod 形式:

const schema = z.object({
  field: z.string(),
});

判断基準:

• スキーマが正しく定義されているか？
• TypeScript 型推論が機能するか？

Phase 4: プロンプトへの統合

目的: スキーマをプロンプトに組み込み

統合方法:

1. JSON Mode 指定:

出力は以下のJSON形式で返してください：
{...schema...}

2. Function Calling:

{
  name: "process_data",
  parameters: schema
}

3. Response Format:

{
  response_format: {
    type: "json_object";
  }
}

ベストプラクティス

すべきこと

1. 厳密な型定義:

   • すべてのフィールドに型を指定
   • nullable の明示
   • enum による値制限

2. 適切な制約:

   • 文字列長の制限
   • 数値範囲の指定
   • 必須フィールドの明示

3. 説明の追加:

   • description フィールドの活用
   • examples の提供

避けるべきこと

1. 過度な柔軟性:

   • ❌ additionalProperties: true
   • ✅ additionalProperties: false

2. 曖昧な型:

   • ❌ type: "any"
   • ✅ 具体的な型指定

3. 深いネスト:

   • ❌ 5 階層以上のネスト
   • ✅ 3 階層以内に平坦化

トラブルシューティング

問題 1: パースエラー

症状: AI の出力が JSON としてパースできない

原因: スキーマが複雑すぎる、制約が不明確

解決策:

1. スキーマを簡略化
2. 具体例をプロンプトに追加
3. JSON Mode を有効化

問題 2: 型不一致

症状: 期待した型と異なる値が返される

原因: 制約が不十分、説明が不明確

解決策:

1. enum で有効値を制限
2. format で形式を指定
3. description を詳細化

関連スキル

• .claude/skills/zod-validation/SKILL.md (.claude/skills/zod-validation/SKILL.md): Zod バリデーション
• .claude/skills/json-schema/SKILL.md (.claude/skills/json-schema/SKILL.md): JSON Schema 仕様
• .claude/skills/type-safety-patterns/SKILL.md (.claude/skills/type-safety-patterns/SKILL.md): 型安全パターン

変更履歴