yodogawa 2.0.0 → 2.1.0

package/skills/a-011-define-data-model/SKILL.md

@@ -1,134 +1,121 @@
----
-name: a-011-define-data-model
-description: ドメインモデルと画面設計からデータベース構造（ERD）を定義し、エンティティ、属性、リレーションシップ、制約を明確化するワークフロー
----
-
-# DefineDataModel (a-011)
-
-## 目的
-
-- ドメインモデル（Aggregates）と画面設計を基に、データベース構造を定義する。
-- エンティティ（テーブル）、属性（カラム）、リレーションシップを明確化する。
-- データ型、制約（NOT NULL、UNIQUE、CHECK）、インデックス戦略を決定する。
-- Mermaid ERD（Entity Relationship Diagram）で視覚化し、開発者間の認識を統一する。
-
-## 前提
-
-- `docs/project/domain/01-domain-model.md` が作成されていること。
-- `docs/project/design/01-tech-stack.md` が作成されていること（DB選定済み）。
-- `docs/project/design/03-screen-design.md` が作成されていること。
-- `docs/project/design/` ディレクトリが存在すること。
-
-## 手順
-
-### 1. ドキュメントと前提条件の確認
-
-- 必要なドキュメントを読み込む：
-  - `docs/project/domain/01-domain-model.md`
-  - `docs/project/design/01-tech-stack.md`
-  - `docs/project/design/03-screen-design.md`
-
-- ドキュメントが不足している場合、対応するワークフローの実行を促す。
-
-### 2. テンプレートの準備
-
-- テンプレートをコピーして作業用ファイルを作成する：
-
-  ```bash
-  SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
-  cp "$SCRIPT_DIR/templates/project/04-design/05-data-model.md" "docs/project/design/05-data-model.md"
-  ```
-
-### 3. エンティティの抽出と提案
-
-- **ドメインモデルから**: Aggregate Rootおよび内部エンティティを抽出。
-- **画面設計から**: 表示・入力項目から必要なデータ構造（履歴、設定、ログ等）を抽出。
-- **エンティティ一覧案を提示**:
-  - 「以下のエンティティを定義します：」
-  - 「[エンティティ名] (対応するAggregate: [名前])」
-
-### 4. 詳細定義（インタビュー）
-
-ユーザーからのフィードバックを受け、各エンティティの詳細を定義する。
-
-#### 4.1 基本定義
-
-- テーブル名（物理名）、論理名、説明
-- 主キー（ID）の戦略（Auto Increment / UUID / CUID）
-
-#### 4.2 属性（カラム）
-
-- カラム名、データ型（DB製品に合わせて具体的に）
-- 制約（NOT NULL, UNIQUE, DEFAULT）
-- 監査カラム（created_at, updated_at）の有無
-
-#### 4.3 リレーションシップ
-
-- 関連するエンティティ（1:1, 1:N, N:M）
-- 外部キー制約（ON DELETE CASCADE / SET NULL / RESTRICT）
-
-### 5. ERDの作成と正規化
-
-- 抽出したエンティティとリレーションシップを Mermaid ERD 形式で記述する。
-- 正規化（1NF-3NF）を確認し、意図的な非正規化があれば理由を記録する。
-- インデックス戦略（検索頻度の高いカラム、ユニーク制約）を定義する。
-
-### 6. ドキュメント作成
-
-- `docs/project/design/05-data-model.md` に決定事項を記入する。
-- **必須項目**:
-  - エンティティ一覧
-  - リレーションシップ定義
-  - ERD (Mermaid)
-
-### 7. 完了条件と構造の確認
-
-- 以下の完了条件を満たしているか、コマンドとチェックリストで確認してください：
-  1. **構造確認**:
-
-     ```bash
-     # エンティティ一覧の確認
-     grep "## エンティティ一覧" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: Entities"
-     # ERDの確認
-     grep "\`\`\`mermaid" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: ERD"
-     # リレーションシップ定義の確認
-     grep "## リレーションシップ" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: Relationships"
-     ```
-
-  2. **チェックリスト**:
-     - [ ] `docs/project/design/05-data-model.md` が作成されている
-     - [ ] 全エンティティの物理名・論理名が定義されている
-     - [ ] ERDが正しくレンダリングされる
-
-### 8. Git への追加（オプション）
-
-- ユーザーに確認：「作成したデータモデルドキュメントを Git に追加しますか？」
-- 「はい」の場合、以下を実行：
-
-  ```bash
-  git add docs/project/design/05-data-model.md
-  git status
-  ```
-
-- 推奨コミットメッセージ：
-
-  ```
-  docs: データモデル（ERD）の定義
-
-  - エンティティ、属性、リレーションシップを定義
-  - MermaidによるER図を追加
-  ```
-
-## 完了条件
-
-- `docs/project/design/05-data-model.md` が作成されている。
-- データベーススキーマ（テーブル、カラム、型、制約）が定義されている。
-- エンティティ間の関係性が可視化（ERD）されている。
-- ユーザーが内容を承認している。
-
-## エスカレーション
-
-- ドメインモデルとの不整合がある場合：
-  - 「ドメインモデルのAggregate構造とデータモデルが乖離しています。ORMのマッピング戦略を確認するか、ドメインモデルを見直してください。」
-- パフォーマンス懸念がある場合：
-  - 「正規化によりJOINが多発する可能性があります。Read Model（参照用テーブル）の導入や、意図的な非正規化を検討しませんか？」
+---
+name: a-011-define-data-model
+description: ドメインモデルと画面設計からデータベース構造（ERD・エンティティ・属性・リレーションシップ・制約）を定義する。画面設計後、永続化層を設計する際に使用。
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# DefineDataModel (a-011)
+
+## 目的
+
+- ドメインモデル（Aggregates）と画面設計を基に、データベース構造を定義する。
+- エンティティ（テーブル）、属性（カラム）、リレーションシップを明確化する。
+- データ型、制約（NOT NULL、UNIQUE、CHECK）、インデックス戦略を決定する。
+- Mermaid ERD（Entity Relationship Diagram）で視覚化し、開発者間の認識を統一する。
+
+## 前提
+
+- `docs/project/domain/01-domain-model.md` が作成されていること。
+- `docs/project/design/01-tech-stack.md` が作成されていること（DB 選定済み）。
+- `docs/project/design/03-screen-design.md` が作成されていること。
+- `docs/project/design/` ディレクトリが存在すること。
+
+## 手順
+
+### 1. ドキュメントと前提条件の確認
+
+以下を読み込む:
+
+- `docs/project/domain/01-domain-model.md`
+- `docs/project/design/01-tech-stack.md`
+- `docs/project/design/03-screen-design.md`
+
+不足があれば対応スキルの実行を促す。
+
+### 2. テンプレートの準備
+
+```bash
+SCRIPT_DIR=$(for d in .agent .cursor .claude .codex; do [ -d "$d" ] && echo "$d" && break; done)
+cp "$SCRIPT_DIR/templates/project/04-design/05-data-model.md" "docs/project/design/05-data-model.md"
+```
+
+### 3. エンティティの抽出と提案
+
+- **ドメインモデルから**: Aggregate Root および内部エンティティを抽出
+- **画面設計から**: 表示・入力項目から必要なデータ構造（履歴、設定、ログ等）を抽出
+- 「[エンティティ名] (対応 Aggregate: [名前])」形式で一覧化
+
+エンティティ一覧の記述例は [examples/erd-templates.md](examples/erd-templates.md#エンティティ一覧テーブル) を参照。
+
+### 4. 詳細定義（インタビュー）
+
+#### 4.1 基本定義
+
+- テーブル名（物理名）、論理名、説明
+- 主キー戦略（Auto Increment / UUID / CUID）— 選択ガイドは [examples/erd-templates.md](examples/erd-templates.md#主キー戦略) を参照
+
+#### 4.2 属性（カラム）
+
+- カラム名、データ型（DB 製品に合わせて具体化）
+- 制約（NOT NULL, UNIQUE, DEFAULT, CHECK）
+- 監査カラム（created_at, updated_at）の有無
+
+カラム定義の例は [examples/erd-templates.md](examples/erd-templates.md#カラム定義テンプレート) を参照。
+
+#### 4.3 リレーションシップ
+
+- 関連（1:1 / 1:N / N:M）
+- 外部キー制約（ON DELETE CASCADE / SET NULL / RESTRICT）— 選択基準は [examples/erd-templates.md](examples/erd-templates.md#外部キー削除動作の選択) を参照
+
+### 5. ERD の作成と正規化
+
+- Mermaid ERD 形式で記述（テンプレートは [examples/erd-templates.md](examples/erd-templates.md#mermaid-erd-記述例) を参照）
+- 正規化（1NF-3NF）を確認。意図的な非正規化があれば理由を記録
+- インデックス戦略（検索頻度、UNIQUE、複合インデックス）を定義
+
+正規化の目安は [reference/structure-check.md](reference/structure-check.md#正規化レベルの目安) を参照。
+
+### 6. ドキュメント作成
+
+`docs/project/design/05-data-model.md` に以下を記入する:
+
+- エンティティ一覧
+- リレーションシップ定義
+- ERD（Mermaid）
+- インデックス戦略・非正規化の記録
+
+### 7. 構造チェック
+
+```bash
+grep "## エンティティ一覧" docs/project/design/05-data-model.md \
+  && grep "\`\`\`mermaid" docs/project/design/05-data-model.md \
+  && grep "## リレーションシップ" docs/project/design/05-data-model.md \
+  && echo "OK" || echo "MISSING SECTION"
+```
+
+詳細チェックリストは [reference/structure-check.md](reference/structure-check.md#チェックリスト) を参照。
+
+### 8. Git への追加（任意）
+
+```bash
+git add docs/project/design/05-data-model.md
+git commit -m "docs: データモデル（ERD）の定義"
+```
+
+## 完了条件
+
+- `docs/project/design/05-data-model.md` が作成されている。
+- データベーススキーマ（テーブル、カラム、型、制約）が定義されている。
+- エンティティ間の関係性が可視化（ERD）されている。
+- ユーザーが内容を承認している。
+
+## エスカレーション
+
+- **ドメインモデルとの不整合**: 「Aggregate 構造とデータモデルが乖離しています。ORM のマッピング戦略を確認するか、ドメインモデルを見直してください。」
+- **パフォーマンス懸念**: 「正規化により JOIN が多発する可能性があります。Read Model や意図的な非正規化を検討しませんか？」
+
+## 参考
+
+- [examples/erd-templates.md](examples/erd-templates.md) — エンティティ一覧、カラム定義、主キー戦略、外部キー動作、Mermaid ERD、インデックス・非正規化の例
+- [reference/structure-check.md](reference/structure-check.md) — 構造確認コマンド、チェックリスト、正規化レベル、レビュー質問

package/skills/a-011-define-data-model/examples/erd-templates.md

@@ -0,0 +1,108 @@
+# エンティティ定義と ERD テンプレート
+
+SKILL.md 手順3〜5 で使用するエンティティ記述・リレーション・ERD のサンプル。
+
+## エンティティ一覧テーブル
+
+| 物理名 | 論理名 | 対応 Aggregate | 説明 |
+|:--|:--|:--|:--|
+| users | ユーザー | User | 認証・プロフィール |
+| orders | 注文 | Order | 注文ヘッダ |
+| order_items | 注文明細 | Order (child) | 注文の商品行 |
+| products | 商品 | Product | 商品マスタ |
+
+## カラム定義テンプレート
+
+### users テーブル
+
+| カラム | 型 | 制約 | 説明 |
+|:--|:--|:--|:--|
+| id | UUID | PK | 主キー |
+| email | VARCHAR(255) | NOT NULL, UNIQUE | ログイン ID |
+| password_hash | VARCHAR(255) | NOT NULL | bcrypt ハッシュ |
+| status | VARCHAR(20) | NOT NULL, DEFAULT 'active' | active / suspended |
+| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | 作成日時 |
+| updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | 更新日時 |
+
+### 主キー戦略
+
+| 戦略 | 適合シーン |
+|:--|:--|
+| Auto Increment | 単一 DB、連番の可読性重視 |
+| UUID v4 | 分散環境、推測困難性 |
+| UUID v7 / ULID | ソート可能な ID が必要 |
+| CUID | 短く衝突しにくい ID |
+
+## リレーションシップ定義例
+
+- `users 1 : N orders` (FK: orders.user_id → users.id)
+- `orders 1 : N order_items` (FK: order_items.order_id → orders.id, ON DELETE CASCADE)
+- `products 1 : N order_items` (FK: order_items.product_id → products.id, ON DELETE RESTRICT)
+
+### 外部キー削除動作の選択
+
+- `CASCADE`: 親削除時に子も削除（注文明細など）
+- `SET NULL`: 親削除時に NULL（オプション参照）
+- `RESTRICT`: 子が存在すれば親削除不可（マスタデータ）
+
+## Mermaid ERD 記述例
+
+```mermaid
+erDiagram
+  users ||--o{ orders : places
+  orders ||--|{ order_items : contains
+  products ||--o{ order_items : referenced_by
+
+  users {
+    uuid id PK
+    varchar email UK
+    varchar password_hash
+    varchar status
+    timestamptz created_at
+    timestamptz updated_at
+  }
+
+  orders {
+    uuid id PK
+    uuid user_id FK
+    varchar status
+    numeric total_amount
+    timestamptz created_at
+  }
+
+  order_items {
+    uuid id PK
+    uuid order_id FK
+    uuid product_id FK
+    int quantity
+    numeric unit_price
+  }
+
+  products {
+    uuid id PK
+    varchar name
+    numeric price
+    int stock
+  }
+```
+
+## インデックス戦略の例
+
+- 検索頻度の高いカラム（`orders.user_id`, `orders.status`）に単純インデックス
+- 一意性保証: `users.email` に UNIQUE
+- 複合インデックス: `(user_id, created_at DESC)` で注文履歴の高速取得
+- 全文検索用途は別途 pg_trgm / GIN 等を検討
+
+## 意図的な非正規化の記録例
+
+- `orders.total_amount`: 集計クエリの高速化のため、order_items の合計を冗長保持
+- 更新時のトリガ or アプリ側計算を明記
+
+## コミットメッセージ例
+
+```text
+docs: データモデル（ERD）の定義
+
+- エンティティ、属性、リレーションシップを定義
+- Mermaid による ER 図を追加
+```

package/skills/a-011-define-data-model/reference/structure-check.md

@@ -0,0 +1,56 @@
+# 構造チェックとレビュー観点
+
+SKILL.md 手順7〜8 で使う確認コマンドとレビュー観点。
+
+## セクション存在確認
+
+```bash
+# エンティティ一覧の確認
+grep "## エンティティ一覧" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: Entities"
+# ERD の確認
+grep "\`\`\`mermaid" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: ERD"
+# リレーションシップ定義の確認
+grep "## リレーションシップ" docs/project/design/05-data-model.md && echo "OK" || echo "MISSING: Relationships"
+```
+
+## チェックリスト
+
+- [ ] `docs/project/design/05-data-model.md` が作成されている
+- [ ] 全エンティティの物理名・論理名が定義されている
+- [ ] 各カラムの型・制約・デフォルト値が定義されている
+- [ ] 主キー戦略（Auto Increment / UUID / CUID）が明記されている
+- [ ] 監査カラム（created_at, updated_at）の有無が決定している
+- [ ] リレーション（1:1, 1:N, N:M）と外部キー動作（CASCADE / SET NULL / RESTRICT）が定義されている
+- [ ] ERD が正しくレンダリングされる
+- [ ] インデックス戦略が記録されている
+- [ ] 意図的な非正規化があれば理由が記載されている
+
+## 正規化レベルの目安
+
+- **1NF**: 繰り返しグループを排除、原子値のみ
+- **2NF**: 複合主キーの部分従属を排除
+- **3NF**: 推移関数従属を排除
+- 通常は 3NF を基本とし、パフォーマンス目的で意図的に非正規化する場合は理由を明記
+
+## レビュー確認質問
+
+- 「ドメインモデルの Aggregate 構造と整合していますか？」
+- 「検索・集計のパフォーマンス要件を満たせそうですか？」
+- 「ソフトデリート / 履歴保持の方針は決まっていますか？」
+- 「機微情報（パスワード、PII）の扱いは適切ですか？」
+
+## Git への追加（任意）
+
+```bash
+git add docs/project/design/05-data-model.md
+git status
+```
+
+推奨コミットメッセージ:
+
+```text
+docs: データモデル（ERD）の定義
+
+- エンティティ、属性、リレーションシップを定義
+- Mermaid による ER 図を追加
+```