db-review

プロジェクトのDB設計を、一般的なRDB設計のベストプラクティスとアンチパターンの知見をもとにレビューするスキル。 アンチパターンの「候補」を深刻度別に洗い出し、ユーザーが選んだ箇所だけをプロジェクト文脈を踏まえて深掘りする。

このスキルの基本姿勢（最重要）

検出するのは「アンチパターンの可能性がある箇所」であって、断定された「NG」ではない。

• 断定（NG）ではなく候補提示（WARNING） を基本とする。
• どのアンチパターンにも「あえてその設計にしている正当な理由」が存在する。検出時は必ず 許容されるケース を意識し、最終判断はユーザーに委ねる。
• テーブルサイズ・被参照数・更新頻度・業務要件など、機械的には分からない判断材料は「○○なら問題」という形で条件付きで提示する。
• 使われ方に依存する指摘はスキーマモードで断定しない: 「UNIQUE/FKの欠如」「履歴の要否」は、追記ログ設計（最新行＝現在）・UPSERT運用・アプリ層での担保かもしれず、スキーマだけでは判定できない。結果（「○○が作れてしまう」「○○が失われる」等）を事実として書かず、「○○の可能性（要コード確認）」と仮説で書く。確証は全体モードのクエリ検査か深掘りで得る。
• 一度に全部の改善案を出さない。まず一覧を出し、ユーザーが気になった箇所だけ深掘りする。

ワークフロー

1. モード選択（スキーマ / 全体）
   ↓
2. スキーマファイルの自動検出（見つからなければパスを聞く）
   ↓
3. 全体モードならクエリ/モデルのディレクトリを聞く
   ↓
4. チェックファイルを読んでレビュー実行
   ↓
5. 深刻度別に結果を出力（注意書き付き）
   ↓
6. 深掘りしたい箇所を選んでもらう → 文脈を踏まえた壁打ち

ステップ1: モード選択

AskUserQuestion で2モードから選んでもらう。

モード	入力対象	ユースケース
スキーマモード	スキーマファイルのみ	サクッとレビュー
全体モード	スキーマ + 指定ディレクトリ配下のクエリ・モデル	フルレビュー

ステップ2: スキーマファイルの自動検出

下記のglobパターンでスキーマファイルを探索する。 複数形式が見つかったら、どれをレビュー対象にするかユーザーに確認する。 1つも見つからなければ、スキーマファイルのパスを聞く。

形式	globパターン
Prisma	**/schema.prisma
Drizzle	**/schema.ts / **/db/schema/**/*.ts / **/drizzle/**/*.ts
Rails	**/db/schema.rb / **/db/migrate/*.rb
Django	**/models.py / **/*/models/*.py
Laravel	**/database/migrations/*.php
TypeORM	**/*.entity.ts
Sequelize	**/models/*.{js,ts} / **/migrations/*.js
SQLAlchemy	**/models.py / **/models/*.py
生SQL（DDL）	**/*.sql（CREATE TABLE を含むもの）

node_modules / vendor / .venv / dist / build 配下は除外する。

ステップ3: クエリディレクトリの指定（全体モードのみ）

全体モードでは、クエリ・モデル・リポジトリが含まれるディレクトリをユーザーに聞く。 指定ディレクトリ配下から、SQLキーワード（JOIN, WHERE, LIKE, OFFSET, ORDER BY, FOR UPDATE, CREATE VIEW 等）やORM呼び出し（.offset(), .skip(), .findMany() 等）を含む記述を探索対象にする。 ORM自動検出はしない（フレームワーク非依存で動かす）。

ステップ4: チェックファイルを読んでレビュー実行

モードに応じて読むファイルを変える。チェックの本体はSKILL.mdには書いていない。必ず読むこと。

• スキーマモード → references/schema-checks.md を読んでレビュー実行
• 全体モード → references/schema-checks.md + references/full-checks.md の両方を読んでレビュー実行

各チェックの 検出方法 に従ってスキーマ／コードを走査し、該当箇所を集める。 許容されるケース に当てはまりそうなものは、深刻度を下げるか注意書きを添える。

ステップ5: 結果出力

後述の「出力フォーマット」に従い、深刻度でグルーピングして出力する。 この段階では改善案を出さない（一覧と所在のみ）。

ステップ6: 深掘り

ユーザーが選んだ指摘について:

1. 該当箇所のコード（スキーマ定義・クエリ・関連モデル）を実際に読む。
2. プロジェクトの文脈（テーブルの役割・周辺の使われ方）を踏まえる。
3. 「なぜ問題か」「どう直すか（具体案）」「あえてこの設計が正当なケース」をセットで提示する。
4. 改善案は1つに断定せず、トレードオフを添えて選択肢として出す。

ここで初めて改善提案を生成する。チェックファイルに改善案を書いていないのは、文脈なしの汎用改善案より、コードを読んだ上での具体案の方が役立つため。

出力フォーマット

深刻度でグルーピングし、各レベルの説明を見出しに含める。冒頭に必ず注意書きを付ける。

> ⚠️ 以下はアンチパターンの**可能性**がある箇所です。
> プロジェクトの要件上、意図的に採用しているケースもあります。最終判断はあなたに委ねます。

## CRITICAL — データ不整合・データ消失リスク

- `users.deleted_flag` — フラグによる論理削除（UNIQUE制約・FKが効かなくなる）
- `orders` → `users` — FK制約の欠如

## HIGH — パフォーマンス劣化・保守困難

- `orders.idx_status` — 低カーディナリティ列への単独INDEX
- `event_guests.guest_1..guest_5` — 繰り返しカラム（マルチカラムアトリビュート）

## MEDIUM — 将来的な技術的負債

- `m_code` — 単一参照テーブル（OTLT）の疑い
- `data` / `info` カラム — 汎用的すぎる命名

---

検出: CRITICAL 2件 / HIGH 2件 / MEDIUM 2件

→ 深掘りしたい箇所を選んでください（番号・カラム名・「CRITICAL全部」などで指定OK）

各指摘に含める情報

• 該当箇所（テーブル名・カラム名・ファイル:行）: 必須
• 何のアンチパターンかの一言: 必須
• 書籍の章番号や根拠: 出力には含めない（深掘り時にもチャプター引用はしない）
• 改善案: 一覧段階では出さない。深掘りフローで生成する

深刻度レベルの判定基準

レベル	基準	例
CRITICAL	データ不整合・データ消失リスク	FK欠如、履歴なし上書き設計、論理削除フラグ
HIGH	パフォーマンス劣化・保守困難	効かないINDEX、ジェイウォーク、繰り返しカラム、N+1
MEDIUM	将来的な技術的負債	命名不統一、コメント欠落、グレーノウハウの濫用

チェックファイルに各チェックの 深刻度 を記載しているが、それは初期分類。 許容されるケース に強く当てはまる場合や、テーブルが小さく影響が無視できる場合は、深刻度を1段下げる判断をしてよい（その旨を注記する）。

注意

• スキップ機能は設けない。意図的な設計との区別は注意書き + ユーザーの最終判断に委ねる。
• 該当ゼロのチェックは出力に載せない。「○○は問題なし」のような網羅報告はしない。
• スキーマモードで検出できるのは「示唆」止まりのものがある（履歴の有無、JSON列の存在など）。確証は全体モードのクエリ検査で得られる旨を、必要なら添える。