db-design

Imported from kensusai/hjkland (skills/db-design/SKILL.md). Install upstream with npx skills add kensusai/hjkland --skill db-design. Copyright stays with the author.

フェーズ 7: DB設計

目的

DB設計を、AIエージェントが安全に変更できる形で docs/database.md に整理する。スキーマ変更のたびにこのドキュメントと migration が同期している状態を保つ。

進め方

1. docs/domain.md のエンティティ・業務ルールを出発点に、既存スキーマ(migration・スキーマ定義ファイル)を棚卸しする。
2. docs/database.md を作成し、以下を記載する。
3. ER図は Mermaid の erDiagram で記載し、スキーマ変更時に必ず更新する。
4. ドメインの不変条件のうち DB 制約で守れるもの(NOT NULL / UNIQUE / FK / CHECK)は制約として明記する。

docs/database.md に含める内容

• エンティティ一覧 — テーブルと役割、ドメイン用語との対応
• リレーション — ER図(Mermaid)とカーディナリティ
• 制約 — 一意制約・外部キー・CHECK と、その業務的根拠
• インデックス — 主要クエリと対応するインデックス方針
• migrationルール — ツール・命名・後方互換の守り方(例: カラム削除は「追加→移行→削除」の段階リリース)
• seedデータ — 開発用データの投入方法と場所
• 削除方針 — 物理削除か論理削除か、テーブルごとの方針と理由
• 監査ログ方針 — 誰が・いつ・何を変更したかを残すテーブル/カラムの方針

ルール

• スキーマ変更は必ず migration として行い、DB を直接変更しない。
• 破壊的変更(カラム削除・型変更)は、ロールバック手順を migration と同時に書く。
• スキーマを変更したら、同じ変更内で docs/database.md の ER図と該当項目を更新する。

型安全: スキーマと型の同期

• DBスキーマとアプリケーションの型定義を機械的に同期する仕組み(ORMの型生成・スキーマからのコード生成)を用意し、手書きの二重管理をしない。
• ID はテーブルごとに区別された型(branded / newtype)で扱い、取り違えをコンパイルエラーにする。