authoring-data-model

authoring-data-model — SKILL.md

バリアント： standard · 使用する場面： データモデル文書を作成するとき。このスキルは、作成者向けの手法と、完全性・クエリ可能性に関する基準を提供します。セクション構成は、組み合わせて使う別のデータモデルテンプレートツールから取得します。そのテンプレートのアウトラインをここで繰り返さないでください。

概要

データモデル文書は、システムに保存されたデータの永続化／ドメインモデルです。エンジニアがスキーマを実装する際に基にする設計であり、データをクエリするすべての人が参照する文書です。このスキルでは、上流の feature-spec からエンティティを導出し、ストレージのパラダイムを特定してそれに沿ってモデル化し、完全性ルールを明示し、すべてのインデックスをアクセスパターンに基づいて正当化することで、作成者が文書を作成する方法を説明します。ここで教えるのは、作成の方法、つまり調査の手法と品質基準です。セクション構成を提供する別のテンプレートツールと組み合わせて使用します。基準は「エンジニアがこの文書からスキーマを作成して正しいクエリを書けること、そしてモデルの完全性ルールとトレードオフが明示されていること」です。

このスキルはパラダイムに対応しています。同じモデリングの厳密さ（エンティティ、関係、完全性、根拠のあるインデックス、明記されたトレードオフ）は、リレーショナル／SQL、ドキュメント／NoSQL、グラフ、ワイドカラム、キー・バリューの各ストアに適用されます。異なるのは成果物の形式だけです。以下では、リレーショナルとドキュメントの2つを詳しく扱います。その他は、それぞれのパラダイムに適した形式でモデル化します（Step 2）。

有効化する場面

• 上流の feature-spec（および、存在する場合はストア名を記載した architecture-doc）を基に、システムまたは機能のデータモデル／スキーマ設計文書を作成または大幅に改訂するとき。
• 作成者が、エンティティの導出、関係のモデル化、インデックスの正当化、トレードオフの明記といった手法と、構築可能でクエリ可能なモデルが満たすべき基準を必要としているとき。白紙の状態ではありません。

次の場合は有効化しないでください：

• 完成したデータモデルをレビューまたは評価するとき。これは作成時ではなく、実行時のレビューゲートです。
• API ワイヤーコントラクト（操作とリクエスト／レスポンス DTO）を作成するとき。これは api-spec の役割です。api-spec はこのモデルのエンティティを参照します（下流への一方向の参照）が、エンティティを再定義するものではありません。
• 永続化の実装（ORM／リポジトリ／アクセスレイヤー）を設計するとき。これは technical-design 文書の役割です。システムのデータストアのトポロジーは architecture 文書で扱います。
• 実行可能な DDL／マイグレーションスクリプトを作成するとき。これは設計文書です（エンティティ、制約、マイグレーションの計画）。コードではありません。
• 別の種類の文書を作成するとき。

入力

計画から渡されたすべての文書、つまり depends_on セット（この文書に情報を与えると discovery が判断した上流文書）を読み、それらにこの文書の内容を結び付けてください。入力が固定されていると想定しないでください。このスキルに記載された典型的な上流文書は手法の指針であり、受け取る文書の上限ではありません。自立して作成できるようにしてください。実際に受け取ったコンテキストがどのようなものであっても、それを基に文書を作成します。情報を与えると想定される文書がない場合は、手元にある情報で進め、不足分を明示的な前提として示してください。補うために捏造してはいけません。また、利用可能な調査機能がある場合は活用し（deep-research）、テンプレートを埋めるだけでなく、包括的で網羅的な文書にしてください。

機能コンテキスト（提供された場合）： 呼び出し元から capability_record（capability-map.yaml product_capabilities のレコード）が渡された場合は、Step 1 の前に読みます。これはスコープの境界を定義します。owns = 対象とするエンティティ、refs = 参照するが所有しないエンティティ、publishes／consumes = 表面化させるイベント、entry_points／exit_points = ユーザーの流入点と離脱点、has_ui／has_api／has_persistence = 該当するサーフェスです。提供されている場合は、これを厳守すべき制約として扱い、定義された境界から逸脱しないでください。

ワークフロー

セクション構成は、組み合わせて使うデータモデルテンプレートツールから取得します。以下の手順は、それを埋めるための手法です。テンプレートにある任意のセクションに適用してください。テンプレートのアウトラインをここで繰り返してはいけません。

ステップ 1：構造を把握し、入力の根拠を確認する

テンプレートツールから、データモデルテンプレートのセクション一覧を取得します。上流の feature-spec（機能が操作するデータ）と、存在する場合は architecture-doc（選定されたストア）を読みます。これらを具体化するのであり、白紙から始めるのではありません。モデリングの判断は、調査機能を通じて、確立された実践（ER モデリング、正規化理論、選択したパラダイムの慣用的な手法）に基づいて行い、独自に考案しないでください。

capability_record がある場合：すべての owns エンティティについて主要なテーブル／コレクションを定義します。refs エンティティは FK 参照のみとして扱い、データを重複させないでください。publishes イベントについては、outbox／イベントエントリーを含めます。

ステップ 2：パラダイムを判定し、トラックを選ぶ

architecture-doc／選定されたストアから、ストアごとにパラダイムを判断します（システムが複数のパラダイムを使用する場合は、それぞれ独自のトラックでモデル化します）。いずれの場合も同じ厳密さを適用します。異なるのは成果物です。

• リレーショナル／SQL — エンティティをテーブルに対応付けます。ER 図と属性ごとの仕様表を作成します。主キー／外部キーと参照整合性を明示します。正規化したうえで、意図的に非正規化します。
• ドキュメント／NoSQL — アクセスパターン優先（アドホックなクエリの柔軟性に制約があるため、エンティティではなくクエリ一覧からモデルを作成します）。コレクションとドキュメントの形状、埋め込みと参照、まとめて読み取るエンティティの併置を定義します。単一テーブル設計 — 複数のエンティティタイプにわたって汎用のパーティションキー＋ソートキーを使い回し、アイテムコレクションに格納します。ベースキーで対応できないアクセスパターンに限って GSI／LSI を追加し、ホットな（カーディナリティの低い）パーティションキーは避けます。
• その他のパラダイム（慣用的な手法に従い、規模に応じてモデル化。フルのトラックは作成しません）： グラフ — エンティティはノード、関係は型付き／方向付きの第一級エッジ（エッジプロパティを持つ）として扱い、アクセスパターンはトラバーサル（例：友達の友達）とします。リレーショナルな中間テーブルを無理に当てはめないでください。ワイドカラム — ワイドで追記中心の行に対して、パーティションキー＋クラスタリングキーを使用します。読み取りに合わせて設計し、自由に非正規化し、TTL ベースの保持を行い、結合は使用しません。キー・バリュー — キーによるアクセスのみを前提とします。値の形状とキーのスキームをモデル化します。型付きエンティティ、エンティティごとのキー、アクセスパターンで根拠を示したインデックス／セカンダリ構造、トレードオフの明示、ライフサイクルという横断的なルールは、すべてのパラダイムで適用されます。パラダイムごとの慣用的な手法は references/modeling-method.md に記載されています。

ステップ 3：アクセスパターンを列挙してからモデル化する

まず、このデータを対象にシステムが対応する必要のある読み取り／書き込みを列挙します。リレーショナルでは、それらをインデックスの根拠とします。NoSQL では、それらによってスキーマが決まります。続いて、次の手順を実施します。

• エンティティ — feature-spec の名詞から導出します。すべての属性に型を付け、必須／任意を明示し、デフォルト値がある場合は記録し、値の制約を記載します。永続化エンティティは api-spec のワイヤ DTO と区別してください。両者は異なることが多いため、DTO ではなく、保存する形状をモデル化します。
• 関係 — すべての関係について、カーディナリティ（1:1／1:M／M:N）、関係を実現する外部キーまたは参照、ライフサイクルを所有する側、参照ルール（on-delete：restrict／cascade／set-null、または NoSQL の場合は埋め込みと参照の使い分け、および DB 強制 FK なしで参照整合性を保つ方法）を記載します。ER 図、関係一覧、エンティティカタログの内容を一致させます。
• キーと制約 — エンティティごとに主キーを定義します（自然キーか代理キーかと、その理由。NoSQL の場合はパーティションキー＋ソートキー、および使い回すキーの戦略）。一意性（複数列を含む）、チェック／ドメイン制約、フィールド間の不変条件を明示します。暗黙にせず、明記してください。

ステップ 4：インデックスを正当化し、トレードオフを明示し、ライフサイクルに対処する

• インデックス — それぞれをステップ 3 のアクセスパターン（WHERE/JOIN/ORDER BY の列と、クエリで参照される外部キー）に結び付けます。正当化できるアクセスパターンのないインデックスは削除します。過剰なインデックスはストレージを圧迫し、書き込みを遅くします。
• 正規化／非正規化 — 正規形（リレーショナルの場合は通常 3NF/BCNF）または NoSQL の埋め込み戦略を明記し、意図的な非正規化をすべて、それが対応する読み取りパターン、許容する書き込みコスト／データの陳腐化に関するトレードオフ、冗長なコピーの一貫性を保つ方法とともに記録します。基本的なトレードオフは、正規化が書き込み効率と整合性を優先し、非正規化が読み取りパフォーマンスを優先することです。
• データライフサイクル — エンティティごとの保持／アーカイブ（論理削除か物理削除か、トゥームストーンがクエリ／一意性に及ぼす影響を含む）、保存する導出値／計算値があればその信頼できる情報源と最新状態を保つ方法、履歴が重要な場合の時間管理／監査／バージョン管理（有効期間付きの行、監査／追記専用ログ、緩やかに変化するディメンション戦略、楽観的並行性制御のための行バージョン管理）。
• データプライバシーと分類 — 機微属性（PII／sensitive／internal／public）を分類し、その分類に基づいて鍵の保持期間とデータの保存場所を決め、データ最小化（必要なものだけを保存すること）を適用します。データ層でシークレットを保護します（パスワードはハッシュ化＋ソルトを付与し、カード情報はトークン化する — 平文では決して保存しない）。references/modeling-method.md を参照してください。
• マイグレーションとスキーマの進化 — マイグレーション／シードの計画（スキーマの作成と進化、バックフィル、シードデータの方法）を記述します。対象は計画であり、DDL ではありません。変更を追加的（後方互換性あり）か破壊的かに分類します。データが存在するストアに破壊的変更を適用する場合は、拡張と縮小（拡張 → バックフィル → 読み取りの切り替え → 縮小）で実施します（その場での名前変更／削除は決して行いません）。ローリングデプロイ時の後方／前方互換性に関する方針を明記します。詳細と修正手順は references/lifecycle-and-amend.md にあります。

ステップ 5：不足を明らかにしてから、基準に照らして自己確認する

不明点は明示的な仮定／未解決の質問として記録し、決して作り上げないでください。その後、引き渡す前に ## Output の品質基準に照らして文書を確認します。すべてをテキストで表現してください（Mermaid の erDiagram、属性／制約の仕様表、インデックス／リレーションシップの一覧、NoSQL のフェンス付きドキュメント形状の例など）。手法と基準は表現媒体に依存しません。

ステップ 6：承認済みモデルを修正する（スキーマ変更の差分）

入力が承認済みモデルに対する変更リクエスト（新しいエンティティ／属性、リレーションシップ／多重度の変更、非正規化、キーの変更）の場合は、描き直さずに編集します。影響を受けるエンティティとそのリレーションシップ／制約／インデックスだけを、その場で修正します。マイグレーションが修正の仕組みです — データモデル固有の特性は次の 2 つです。

• 分類してマイグレーションする。 変更を追加的（新しい NULL 許容列／テーブル／インデックス — 後方互換性あり）か破壊的（列の削除／名前変更／範囲の縮小、多重度の変更、キーの変更）に分類します。破壊的変更は、後方／前方互換性の分析を含めて拡張と縮小（その場での書き換えは決して行わない）として計画します。置き換えられるエンティティ／属性／インデックスには非推奨の印を付け、黙って削除しないでください。文書のバージョンを上げ、変更履歴を更新します。
• 下流への波及を先回りして対処する。 スキーマ変更は、変更対象のエンティティに対応するリソースを持つ下流の api-spec、スキーマに関わる impl/test-plan、およびマイグレーション／ランブックに波及します。上流の feature-spec を先に修正します（spec→plan→impl の順）。波及する変更を明示し、下流の利用者を黙って破壊しないでください。

完全な手順は references/lifecycle-and-amend.md にあります。グリーンフィールドでの初回構築では、このステップは該当しません。

ルール

厳守するルール（違反禁止）：

• 重複ではなく、内容を作成します。 セクション構成はテンプレートツールから採用し、このスキルでは手法と品質基準を示します。作成するドキュメントでテンプレートのアウトラインを再掲したり、このスキルが構成を決めるかのように考えたりしてはいけません。
• すべてのエンティティに型とキーを設定し、すべてのリレーションシップにカーディナリティと参照ルールを明記します。 型のない属性、キーのないエンティティ、カーディナリティや参照動作が欠けたリレーションシップは、成果物に含めてはいけません。
• すべてのインデックスをアクセスパターンに対応づけます。 根拠のないインデックスも、必要なのに欠けているインデックスも許容されません。
• 白紙から始めず、feature-spec（および architecture-doc）を根拠にします。 エンティティと属性は実際のドメインを反映させます。不明点は作り上げず、前提として明示します。
• 永続化モデルは api-spec と一方向の関係にします。 これは保存されるスキーマです。api-spec はこれらのエンティティを参照する下流のコンシューマーであり、この作業の入力ではありません（入力として扱うと循環依存が生じます）。保存エンティティはワイヤー DTO ではありません。
• 機能の境界（capability_record が指定されている場合）。 ドキュメントの出力範囲を、そのレコードが定める境界内に限定します。境界外の内容を生成すること（refs エンティティを自分の担当であるかのように扱う、exit_point を越えたフローを設計するなど）は、スコープ違反であり、仕様にない内容を作り上げることに相当します。

推奨事項（必要に応じて変更可能）：

• 規模は内容に応じて調整します。「包括的」と指定されていれば、それに応じた網羅性を目指します。データストアが小規模なら、不要なセクションは省略します。重視するのは分量ではなく、整合性、クエリ可能性の網羅性、アクセスパターンのカバーです。
• 自然キーが安定していて意味を持つ場合を除き、サロゲート主キーを優先します。どちらを選んだ場合も、その選択を明記します。

注意点

• NoSQL データストアにリレーショナルモデルの考え方をそのまま当てはめること。 ドキュメント型／NoSQL のデータストアに対して、テーブルと 3NF を前提にすると、使いものにならないモデルになります。まずパラダイムを特定し（Step 2）、NoSQL ではアクセスパターンを優先してモデル化します。
• 「念のため」インデックスを追加すること。 対応するアクセスパターンがないインデックスは無駄な負荷です。書き込みを遅くし、ストレージを圧迫します。それぞれを Step 3 のクエリに対応づけるか、削除します。
• カーディナリティや削除時のルールがないリレーションシップの線。 1:M/M:N の区別と削除時の動作が示されていない ER 図は、実装できません。すべてのリレーションシップに、その両方が必要です。
• 保存エンティティではなく、ワイヤー DTO をモデル化すること。 api-spec のリクエスト／レスポンスの形状は、保存されるデータの形状とは異なる場合がよくあります（計算フィールド、内部情報の省略、結合の平坦化など）。永続化の形状をモデル化し、api-spec からそこへマッピングします。
• ER 図とテーブルの不整合。 一方にあるエンティティやリレーションシップがもう一方にないと、読者に混乱を与えます。Mermaid 図、エンティティカタログ、リレーションシップ一覧の内容を一致させます。
• DDL／マイグレーションコードを出力すること。 成果物は設計（エンティティ＋制約＋マイグレーション計画）であり、実行可能なスキーマスクリプトではありません。

アンチパターン

• 「api-spec にフィールドがすでに列挙されているので、そこからモデル化します。」 これは依存関係を逆転させ、ワイヤー DTO と保存エンティティを混同します。feature-spec を基にモデル化し、api-spec はこのモデルを参照します。その逆ではありません。
• 「すべてを BCNF に正規化して終わりにします。」 正規形は出発点であり、ゴールではありません。アクセスパターンに必要な意図的な非正規化と、そのトレードオフを明記します。
• 「ドキュメントを完全に見せるため、テンプレートのセクションを再掲します。」 アウトラインを重複させても、ドキュメントを作成したことにはなりません。求められている構成に沿って、手法を反映した内容を記述します。
• 「データストアは明らかなので、根拠を示す必要はありません。」 保存先とパラダイムを選び、その根拠（データ形状、整合性、規模、アクセスパターン）を示します。下流の読者がそれを推測できるとは限りません。

出力

この完全性とクエリ可能性の基準を満たすデータモデルドキュメント（Markdown形式のテキスト）。これらの9つの条件は reviewing-data-model ゲートと単一の情報源で管理されます。そのチェックリストがこのリストそのものなので、作成時の基準とレビュー時の基準に食い違いは生じません。引き渡す前に、以下に照らして自己チェックしてください。

1. エンティティと属性 — すべてのエンティティに、型の定められた属性とキー（主キー、または NoSQL のパーティションキー＋ソートキー）があること。モデル化する形状は api-spec のワイヤー DTO ではなく、保存される形状であること。各エンティティが feature-spec のドメインに由来していること。
2. リレーションシップと参照整合性 — すべてのリレーションシップでカーディナリティを明示すること。M:N はジャンクションエンティティ（リレーショナル／ドキュメント）で実現すること。グラフではエッジを使用すること。FK／参照と所有側に名前を付けること。削除時のルール（リレーショナル）を明記するか、埋め込みと参照のどちらを使うか＋FK を使わない場合の整合性戦略（NoSQL／その他）を明記すること。
3. キー、制約、アクセスパターンに基づくインデックス — エンティティごとに PK を定め（自然キーか代理キーかを明記）、一意性制約とチェック制約／フィールド間制約を明確にすること。アクセスパターンを列挙し、すべてのインデックスをアクセスパターンに結び付けること（根拠のないインデックスや、必要なのに不足しているインデックスがないこと）。
4. 正規化とストレージパラダイム — 正規形（リレーショナル）または埋め込み／シングルテーブル戦略（NoSQL／その他）を明記すること。採用したパラダイムとその根拠を示すこと。意図的な非正規化については、それぞれ読み取りパターン、トレードオフ、整合性戦略を記録すること。
5. データのライフサイクルと移行 — 必要に応じて、保持／アーカイブと論理削除／物理削除を定めること。派生データについては、信頼できる唯一の情報源と鮮度を明記すること。履歴が重要な場合は、時系列データ／監査情報を扱うこと。移行とシードの計画を示すこと（破壊的変更ではエクスパンド・アンド・コントラクトを採用し、ローリングデプロイが適用される場合は後方／前方互換性を確保すること）。
6. 図 ⇄ カタログ ⇄ 表の同期 — Mermaid の erDiagram 内のすべてのエンティティ／リレーションシップがカタログおよびリレーションシップ／インデックスの一覧に記載され、その逆も成り立つこと。孤立や不整合がないこと。
7. 横断的なデータ品質 — 機密属性を分類（PII／機密）し、データの性質に応じて保持期間／データの保存場所を定めること。シークレットを保存時に保護し、認証情報を平文で保存しないこと。対象規模でモデルが実用に耐えること（ホットパーティション、インデックスのないホットクエリ、上限のない行がないこと）。データの性質に応じて対応すること。
8. 根拠があり、誠実で、一貫していること — エンティティ／属性が feature-spec を反映していること（捏造や定型的な記述ではないこと）。前提を明示すること（入力が不十分な場合は、スキーマをでっち上げるのではなくブロッカーとすること）。捏造しないこと。api-spec とは一方向の関係であること（feature-spec から導出し、api-spec は下流の利用者にすぎないこと。DTO から逆算しないこと）。既存の提供済みスキーマがある場合は、それと一貫していること。
9. 変更リクエスト時は差分の範囲に限定して修正する — 変更したエンティティについて、変更箇所に関する条件 1～8 を満たすこと。変更が追加か破壊的かを分類し、移行計画と互換性分析を示すこと。変更の波及先と波及元を明示すること。ドキュメントのバージョンを更新し、変更履歴を記載すること。置き換えられた項目にはその旨を示すこと。（新規構築の初回作成では該当なし。）

比例性： 小規模なストアでは、必要のないものを正当に省略できます（エンティティが 1 つ、M:N なし、非正規化なし、時系列履歴なし、初稿では移行なし、PII なし、など）。文章の量ではなく、完全性とクエリ可能性の網羅性で判断してください。

想定する利用者は、永続化を実装しクエリを作成するエンジニア、これらのエンティティにリソースを対応付ける下流の api-spec 作成者、そして上記の基準に照らしてドキュメントをチェックする reviewing-data-model ゲートです。

関連

• コンテンツテンプレートツール — このスキルと組み合わせるデータモデルのセクション構成を提供します（構成を提供するのが役割で、このスキルは手法と基準を担います）。
• ディープリサーチ機能 — 独自に考案するのではなく、確立された実践（ER モデリング、正規化理論、パラダイム固有の慣習）に基づいてモデル化の判断を行います。
• 上流の feature-spec（存在する場合は architecture-doc も）— 入力コンテキストです。このモデルでは、feature-spec で定義された動作に必要な永続化を設計します。
• api-spec の作成に関する懸案事項 — 下流の利用者です。そのリソースは、このモデルのエンティティに対応付けられます（方向は一方向です）。別の成果物であり、ワイヤー上の契約であって、保存されるスキーマではありません。
• reviewing-data-model — 専用の受け入れゲート（対になるスキル）です。## Output にある同じ 9 つの条件（単一の情報源）に照らして完成したモデルを評価し、VERDICT: approve|revise を出力します。完成した data-model 成果物は、汎用の design-review ではなく、こちらに送ります（technical-design と architecture-doc の成果物と同様に、汎用レビューの対象外です）。
• references/ の 2 つのファイル：references/modeling-method.md（パラダイムごとの慣習と、エンティティ／リレーションシップ／キー／インデックス／正規化の深さ）および references/lifecycle-and-amend.md（保持／時間的特性／プライバシー、拡張・縮小マイグレーション、修正手順、前方／下方への波及）。

段階的な開示

詳細な内容はサブフォルダーに置かれ、必要なときだけ読み込まれます。

• references/modeling-method.md — パラダイムごとの慣習（リレーショナル／ドキュメント／グラフ／ワイドカラム／キー・バリュー）に加え、エンティティ／属性、リレーションシップ／参照整合性、キー／制約／アクセスパターンに基づくインデックス、正規化／パラダイムの選択、データのプライバシー／分類に関する詳細を記載しています。特定のパラダイムをモデル化するときや、整合性に関する判断が境界的なときに読み込みます。
• references/lifecycle-and-amend.md — 保持／論理削除／派生データ／時間的特性の詳細に加え、拡張・縮小マイグレーションの手順と修正方法（追加か破壊的変更かの分類、互換性、前方／下方への波及）を記載しています。ライフサイクルや修正／差分タスクのときに読み込みます。
• references/sources.md — 手法と基準の研究上の出典を記載しています。主張の根拠を確認するときに読み込みます。

このスキルには scripts/ や assets/ は含まれません。

本文の予算

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン（目安。品質を優先し、700 行／7,000 トークンを恒常的に超える場合は注意を促してください）。
• 参照ファイルごとに、10k トークン超で警告、25k 超でエラー。参照ファイルの合計は、25k 超で警告、50k 超でエラー。

変更履歴

• 1.3.0 (2026-06-21) — capability_record のコンテキスト注入：呼び出し元が任意で注入する capability_record を Step 1 で使用（owns／refs／publishes／consumes によるスコープ境界）。capability_boundary ルールを追加し、本文の予算を目安に変更。レコードが注入されていない場合は適切にフォールバックします。
• 1.2.0 (2026-06-15) — 本番品質への再構成：反復／修正の方法（Step 6 — 追加か破壊的変更かの分類＋拡張・縮小マイグレーション＋後方／前方互換性＋前方／下方への波及）を追加。ライフサイクルにおけるスキーマの進化／マイグレーション、時間的特性／監査／SCD、データのプライバシー／分類を詳述。パラダイムの対象範囲を拡張（グラフ／ワイドカラム／キー・バリューの慣習＋NoSQL の単一テーブルに関する詳細）。## Output を、reviewing-data-model の対となるスキルと 1 対 1 で対応する9 つの条件を単一の情報源として持つ構成に変更（横断的なデータ品質＋差分に限定した修正を追加）。完成した成果物の送付先を、汎用の design-review ではなく reviewing-data-model に変更。詳細を references/modeling-method.md と references/lifecycle-and-amend.md に分割。手法＋入力契約＋媒体は変更なし（追加のみ）。
• 1.1.0 (2026-06-04) — 初回レビュー済みリリース。