# Home Data Shape Contract

> DB・保存ファイル・API・イベント・CLIの構造化出力を設計・変更するとき、具体例と読み書きの互換性を確認する。未決の重要な選択を整理し、合意済みの形式や既存設定値だけの変更では再確認しない。

- Skill: `nwiizo/home-data-shape-contract` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nwiizo/home-data-shape-contract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nwiizo/home-data-shape-contract/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: nwiizo (https://skillmd.com/u/nwiizo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nwiizo/home-data-shape-contract

---


# Persisted Data and Public Interfaces

対象は永続化形式とプロセス外へ公開するデータの構造。
ローカル型、テスト用の中間表現、既存形式のまま設定値だけを変える作業には適用しない。

## 進め方

- 現在の書き込み側、読み込み側、保存済みデータ、既に決まった要件を確認する。
- 構造の判断が必要なら、違いが分かる具体値の before/after と互換性への影響を示す。
  新規形式に架空の旧形式を作る必要はない。
- ユーザーの判断が必要な未決の選択だけ確認する。依頼で指定された形式や合意済みの
  方針に沿う可逆的な実装は進める。再承認のために migration や serializer の作成を止めない。
- 本番データの書き換え・削除や公開は、実装作業とは別に、対象と実行権限を確認する。

## 判断基準

- 導出できる値の重複保存は理由がある場合に限る。時点の事実として保存する値と、
  再計算するキャッシュを区別し、後者には更新・不整合の回復方法を持たせる。
- 人が読む形式では意味の分かるキーを使う。短縮キーや `cols` + `rows` は、
  データ量・処理負荷の要件があり、読みにくさと互換性の負担に見合う場合に選ぶ。
- 固定長・固定順序の値は tuple が候補になる。拡張や項目名の意味が重要なら object。
  既存形式を小さくする目的だけで変えない。
- 独立した状態の軸は分け、不可能な組み合わせを許す分割は避ける。
  永続化する enum の値は並べ替えで意味が変わらない表現にする。
- 追加変更でも安全とは限らない。古い reader の未知フィールド・未知値の扱いと、
  新しい reader が古いデータを読めるかを確認する。
- フィールド名を別の意味に再利用しない。移行が必要なら読み書きの切替順序、
  既存データの扱い、失敗時の復旧方法を決める。

判断を説明する具体例は [samples.md](references/samples.md)、
null・時刻・数値などの境界を扱うときは [pitfalls.md](references/pitfalls.md) を読む。