「Cursor」×「A5:SQL Mk-2」でテーブル定義書をリッチにする

# Cursor擦り倒すシリーズ
1. [Cursorで要件定義がエラいスムーズになった話](https://qiita.com/WdknWdkn/items/7c130f2febfdf33b31a4)
1. [（続）Cursorで「詳細設計→ガントチャート草稿」作成がめっちゃ楽になった話](https://qiita.com/WdknWdkn/items/b0d9807e32acfc328f2e)
1. [「Cursor」×「A5:SQL Mk-2」でテーブル定義書をリッチにする](https://qiita.com/WdknWdkn/items/104312248bacc85ff03e)　←本稿こちら
1. [「Cursor」×「Obsidian」内部リンク生成＆最適化プロンプト](https://qiita.com/WdknWdkn/items/52c2aab1163391ecdfea)
1. [「Cursor」で「難解コード」のリーディングがめちゃ楽になった話](https://qiita.com/WdknWdkn/items/da8407d206bfb0bdd206)　
1. [「Cursorで要件定義をめっちゃ簡単に」を「rules」にしてさらに簡単にした](https://qiita.com/WdknWdkn/items/535c597f968a7c987d5b)
1. [「Cursor」で「素の議事録」を「要件定義書」に高速でまとめなおした話](https://qiita.com/WdknWdkn/items/79980f4201c8cf9145bf)
8. [「Cursor」で新人向け「SQLトレーニング問題作成」するプロンプト作成](https://qiita.com/WdknWdkn/items/c19bddb688efb8c40689)


## Claude Code擦り倒すシリーズ、はじめました

1. [「Claude Code」導入をめっちゃスムーズにする「ドキュメントの下地」を作るプロンプト](https://qiita.com/WdknWdkn/items/2755301aebff878e0075)


# これは「テーブル定義書をCursorでいい感じに作る」記事です。

Cursor周りでこすり倒してる感じがしてきていますが、最近は日々トライアンドエラーの頻度も増してきていまして、わずかばかりでも需要があるなら、どんどんと発信していこうという所存です。

## 序章 ― 私たちは、なぜ “定義書” を信じきれないのか

テーブル定義書――それは一度書いたら「もう安心だ」と思い込みやすいドキュメントです。しかし、私の組織でも何度となく **“実装と定義書の乖離”** に悩まされてきました。
*仕様変更の影響範囲が読めない。
リファクタ後のカラムが何のためにあるのかわからない。
属人化した SQL がレビューをすり抜ける……*
そうした **“静的な紙の設計書”** と “動的に変わるコードベース” のギャップを埋める――それが今回紹介するフローの出発点でした。

### 「A5\:SQL Mk-2」について

結構昔から、テーブル定義書を定義するのにたびたび使っていたツールでしたが、
 **Excelで出してメンテナンスが後後しづらい** な、とか、
 **DBスキーマから参照できる情報だといまいち足りない** んだよな、みたいな悩みがあっていまいち使いきれてなかったんですよね。
そこに来て **「Cursorの登場」** と、今まで「誰が使うねん」と思っていた **「md形式のテーブル定義書」が見事にマリアージュ** してしまったという感覚です。

---

## 背景 ― 「A5\:SQL Mk-2 × Cursor」で狙ったこと

* １．**A5\:SQL Mk-2** で “Markdown形式のテーブル定義書” を一括生成
* ２．**Cursor** を使い、

  * 各カラムが *どの Controller／Model／Job* で更新・参照されているか
  * JOIN 先やユースケースがどこに潜んでいるか
    を自動抽出させる
* ３．**“構造” と “使われ方”** を一つの `.md` に同居させる

結果、**レビュー効率** はもちろん、オンボーディング時の「とっかかり資料」としても強力になりました。

> 「テーブル定義書は“スキーマのスナップショット”ではなく、
> *“振る舞いを語るストーリーブック”* に変えられるのだ――」
> そう実感できたのが、この取り組みの最大の収穫です。

---

## 全体俯瞰 ― まずは 4 行で流れを掴む

```mermaid
flowchart LR
  A[A5:SQL Mk-2<br>テーブル定義書出力] --> B[Cursor<br>分析フェーズ]
  B --> C[AI 出力確認→修正指示]
  C --> D[Cursor<br>更新フェーズ]
  D --> E[MD 保存→Git commit]
```

1. **A5\:SQL Mk-2** で *“テーブル定義書”* の Markdown を吐き出す
2. 定義書とソースをワークスペースへ
3. **Cursor** で *Prompt-1* を叩き、コード横断検索 → 追記案を生成
4. その場でレビューし、OK なら *Prompt-2* で **元ファイルを直接書き換え**
5. 差分を Git で管理し、PR で軽量レビュー

---

## 手順

### 1. **A5\:SQL Mk-2** で *“テーブル定義書”* の Markdown を吐き出す

#### 1-① メニューから「テーブル定義書作成」を選択

メニューバーから
   　`データベース(D)` → `テーブル定義書作成(S)...`
   　をクリック

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/215128/25059f17-f377-4c4f-8ce4-5135a3b03fd5.png)

---

#### 1-② テーブル定義書作成ウィンドウの設定

「テーブル定義書作成」ウィンドウが開いたら、以下を設定：

* **スキーマ・テーブルの選択**

  * 対象スキーマを選ぶ（例：`mysql`）
  * 「テーブル」にチェック
  * `全選択`ボタンで全テーブルを一括選択

* **出力形式**

  * `Markdown` を選択

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/215128/cc332e70-e882-4673-9f0a-6eda3488b00d.png)

---

#### 1-③ テーブル定義書を出力

画面右下の `テーブル定義書作成` ボタンを押下
   　→ テーブルごとの Markdown ファイルが生成される！！！

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/215128/17c47edf-a03c-43dc-a67f-640523c27eea.png)

---

### 2. 定義書とソースをワークスペースへ

2-1. 「Add Folder To WorkSpace ...」で、ソースコードプロジェクトに、テーブル定義定義書フォルダを追加
2-2. Cursor 左側ペインの **“＋”** をクリック
2-3. `テーブル定義書ファイル` と `処理してそうなソースコードディレクトリ` を *ドラッグ＆ドロップ*

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/215128/d0652787-d35f-4146-ad64-7c9a41a059ba.png)

### 3. **Prompt-1** ― *分析フェーズ* の実行

以下のプロンプトを張り付け→実行。

```markdown
# テーブル定義ファイル分析タスク

## 目的
指定されたテーブル定義ファイルを分析し、指定ソースコードから関連情報を抽出して、
「更新条件」「登録値の定義」「関連テーブル・カラム」を列挙する。

## インプット

* テーブル定義ファイル: /docs/schema/sample_table1.md
* ソースコードディレクトリ: /app, /database/migrations

## アウトプット
- Markdown 形式の追記用断片
- カラムごとに以下を記述  
  * 更新条件: どのユースケースで値が変わるか  
  * 登録値の定義: デフォルト、NOT NULL 制約、アプリ側バリデーション  
  * 関連カラム: 外部キー・JOIN 元など

**制約**
- コードコメント≠真実の場合を想定し、実装ロジックを優先
- 推測した場合は〈Assumed〉タグを付与

```

* 30〜60 秒ほどで **「## 関連テーブル」「## 関連機能」「### \<column\_name>」** という塊が返ってきます
* もし **誤検知**（例えば “LIKE 検索” を UPDATE と誤解する など）があれば、*“その場で追質問”* して再生成させるのがコツです

### 4. **Prompt-2** ― *更新フェーズ* へシームレス遷移

続けて同じチャットに貼り付け。

```markdown

# テーブル定義書更新タスク

## タスク
- 「sample_table1.md」に、解析結果をセクション単位で追記する。
- "## カラム情報" は対応するカラム行へ追記

## 追記内容
| カラム名 | 更新条件 | 登録値の定義 | 関連テーブル・カラム |
|---------|---------|-------------|---------------------|
| ...     | ...     | ...         | ...                 |

**ルール**
- 既存記述は改変せず、追記のみ
- Markdown テーブルとして整合すること

```

* **Yes／No** を返すだけでなく、Cursor 側で “直接ファイルを書き換え” ます*

### 5. Git へコミット

（ドキュメント管理をgit管理していたりする場合は、こちらもぜひ）

---

## 私が感じた効能 ― “言葉” と “行動” の距離が縮まる

1. **「何のためのカラムか？」** が *コード片* とともに残る
3. スキーマ変更 PR で **“想定外の副作用”** を拾いやすくなった
4. *diff ＝会話の起点* になるため、レビューが “指摘” から “対話” へシフト

---

## 失敗と学び ― AI まかせにしない 3 つの約束

*失敗例: JOIN 先を誤認し、不要な外部キーをドキュメントに追記してしまった。
原因は **“LIKE '%address\_id%'”** を安易に拾ったことでした。*

そこで、私は次の 3 点を**必ず**守るようにしています。

1. **“○○Controller@△△”** の *メソッド単位* で必ず人間が目を通す
2. **「更新条件」≠“頻出 UPDATE 文”** であることを自覚する
3. AI が出した “関連テーブル” を **ER 図でクロスチェック** する

これらは *「AI を盲信しない安全弁」* として機能しています。

---

## 結び ― “ドキュメントは静的” という思い込みを壊すために

私はずっと「ドキュメントを書く時間が惜しい」と感じていました。
しかし、**“AI で書かせ、人間はレビューに専念する”** という構図を手に入れた今、
ドキュメントは *“変化の速いコードベースと同じ速度で呼吸する存在”* へと変貌しました。

もちろん、これで万能ではありません。
それでも――
**「向き合う」** という言葉を、*“ひたすら行動で示す”* ための一手として、
今回のフローはチームにとって大きな意味を持ったと感じています。

**おわり。**