Cursor擦り倒すシリーズ

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

「Claude Code」導入をめっちゃスムーズにする「ドキュメントの下地」を作るプロンプト

これは「テーブル定義書を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 行で流れを掴む

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

手順

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

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

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

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

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

スキーマ・テーブルの選択
- 対象スキーマを選ぶ（例：mysql）
- 「テーブル」にチェック
- 全選択ボタンで全テーブルを一括選択
出力形式
- Markdown を選択

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

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

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

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

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

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

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

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

## インプット

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

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

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

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

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

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


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

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

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

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

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

5. Git へコミット

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

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

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

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

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

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

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

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

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

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

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

おわり。