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
$ インストール
git clone https://github.com/daishiman/AIWorkflowOrchestrator /tmp/AIWorkflowOrchestrator && cp -r /tmp/AIWorkflowOrchestrator/.claude/skills/structured-output-design ~/.claude/skills/AIWorkflowOrchestrator// tip: Run this command in your terminal to install the skill
name: structured-output-design description: | 構造化出力の仕様書を設計するためのスキル。スキーマ定義、命名規則、互換性とバージョニング方針を整理し、長期運用に耐える出力契約を作成する。
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 allowed-tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep
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 仕様に準拠した構造へ更新 |
Repository
