structured-output-design
構造化出力の仕様書を設計するためのスキル。スキーマ定義、命名規則、互換性とバージョニング方針を整理し、長期運用に耐える出力契約を作成する。Anchors:• JSON Schema / 適用: スキーマ設計 / 目的: フィールド仕様の形式化• Semantic Versioning 2.0.0 / 適用: バージョニング設計 / 目的: 互換性ルールの明確化• Postel's Law / 適用: 互換性判断 / 目的: 入出力の許容範囲を整理Trigger:Use when defining output contracts, schema evolution rules, or compatibility plans for structured data.output contract, schema design, compatibility, versioning, JSON schema
When & Why to Use This Skill
This Claude skill facilitates the design of robust structured output specifications, focusing on JSON Schema definition, naming conventions, and versioning strategies. It helps developers create durable output contracts that ensure long-term system compatibility and seamless data integration by applying industry standards like Semantic Versioning and Postel's Law.
Use Cases
- Defining formal JSON Schema contracts for microservices to ensure reliable and predictable data exchange.
- Establishing Semantic Versioning policies for API evolution to prevent breaking changes in production environments.
- Designing structured response formats for AI agents to guarantee machine-readable outputs that align with business logic.
- Standardizing naming conventions and field specifications across complex data structures to improve system maintainability.
| name | structured-output-design |
|---|---|
| description | | |
| • JSON Schema / 適用 | スキーマ設計 / 目的: フィールド仕様の形式化 |
| • Semantic Versioning 2.0.0 / 適用 | バージョニング設計 / 目的: 互換性ルールの明確化 |
| • Postel's Law / 適用 | 互換性判断 / 目的: 入出力の許容範囲を整理 |
Structured Output Design
概要
構造化出力の「契約」を設計し、スキーマ・命名規則・互換性方針を一貫させるスキル。仕様書を作成して関係者の合意形成を促進する。
詳細は references/Level1_basics.md から段階的に参照する。
ワークフロー
Phase 1: 契約要件の整理
目的: 出力仕様の目的、利用者、互換性要件を明確化する。
アクション:
- 仕様の利用者と運用期間を整理する。
- 互換性の許容範囲を定義する。
- 命名規則とバージョン表現を決定する。
Phase 2: 仕様書とスキーマの設計
目的: 出力契約を文書化し、スキーマとテンプレートを整合させる。
アクション:
assets/output-contract-template.mdを埋める。assets/json-schema-template.jsonを基にスキーマを作成する。- 互換性・移行方針を明記する。
Phase 3: 検証とレビュー
目的: 仕様書とスキーマの不整合を解消する。
アクション:
scripts/validate-output-contract.mjsを実行する。scripts/validate-schema.mjsでスキーマの構造を点検する。- 指摘事項を反映し版を確定する。
Task仕様ナビ
| Phase | Task | 目的 | 入力 | 出力 |
|---|---|---|---|---|
| 1 | 契約要件整理 | 利用者・互換性要件の確認 | ユーザー要求 | 要件メモ |
| 2 | 契約設計 | 仕様書とスキーマを整備 | 要件メモ | 出力契約書 |
| 3 | 契約検証 | 仕様書/スキーマの検証 | 出力契約書 | 検証レポート |
ベストプラクティス
すべきこと
- フィールドに型・制約・例を必ず記載する。
- 互換性の原則を明文化する。
- バージョン表現を出力に含める。
- 仕様変更は影響範囲を記録する。
避けるべきこと
- 必須/任意を曖昧にしたまま運用しない。
- 破壊的変更をサイレントに入れない。
- 仕様書とスキーマの不一致を放置しない。
リソース/スクリプト参照
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構造検証
変更履歴
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2026-01-02 | 18-skills.md 仕様に準拠した構造へ更新 |