db-access-analysis - SKILL.md Agent Skill

name: db-access-analysis description: Goプロジェクト内でDBアクセス（CRUD）が発生している関数・テーブルをisucrudで解析し、コーディングエージェントが「どの関数からどのテーブルにINSERT/UPDATE/DELETE/SELECTが行われるか」を把握するためのスキル。キャッシュ対象の判断、N+1の特定、DBアクセスを伴う関数の影響範囲調査、リファクタリング前のCRUD確認などに使用する。Go (database/sql, sqlx 等) で書かれたプロジェクトが対象。

DB Access Analysis (isucrud)

このスキルは isucrud を用いて Go プロジェクトの DB アクセス箇所を静的解析し、結果をエージェントが扱いやすい形 (Markdown + Mermaid) に出力するためのものです。

このスキルを使うべき場面

次のような問いがあるときに使います。

「この関数を変更すると、どのテーブルへの書き込みに影響するか？」
「テーブル xxx にアクセスしているのはどの関数か？」
「キャッシュを入れるべきテーブルはどれか？（読み込みが多く更新が少ないもの）」
「ループ内でクエリが発行されている箇所（N+1 候補）はどこか？」
「初期化処理を除いた本番コードパスでの CRUD はどうなっているか？」

逆に、Go 以外の言語で書かれたプロジェクト、ORM がビルドタグ等で隠されているコードベース、SQL を文字列リテラルではなく完全に動的生成しているコードでは精度が大きく落ちるので、結果を鵜呑みにせず元コードで確認すること。

前提

解析対象は Go モジュール (go.mod がある) のリポジトリ。
go コマンドが利用可能であること（isucrud は内部で golang.org/x/tools/go/packages 経由でビルドする）。
対象プロジェクトの依存解決ができること（必要に応じて go mod download を先に実行）。

手順

1. isucrud をインストール

go install github.com/mazrean/isucrud@latest

$GOPATH/bin (デフォルトでは $HOME/go/bin) が PATH に通っていなければ、フルパスで呼び出すか PATH を更新する。

2. 対象プロジェクトのルートで実行（標準出力で受け取る）

解析対象の Go プロジェクトのルート（go.mod があるディレクトリ）に移動した上で、-dst - を指定して標準出力に Markdown を出させる。エージェントは Bash ツールの実行結果としてそのまま読み取れるため、ファイルを介さずに解析できる。

isucrud -dst - ./...

実行結果として、Mermaid 形式の DB アクセスグラフを含む Markdown が標準出力に流れてくる。エージェントはこの出力を直接コンテキストに取り込み、関数とテーブルの依存関係を把握する。

3. ノイズを減らすオプション

実プロジェクトでは初期化やテストヘルパが大量に混じることが多い。以下のフラグを活用する。

-ignoreInitialize : 名前に initialize を含む関数を無視（デフォルト true）
-ignoreMain : main 関数を無視（デフォルト true）
-ignore <funcName> : 個別関数を無視（複数指定可）
-ignorePrefix <prefix> : 指定プレフィックスで始まる関数を無視（複数指定可）

例: テスト用関数とログ用関数を除外する場合

isucrud -dst - \
  -ignorePrefix Test \
  -ignorePrefix log \
  -ignore SetupRouter \
  ./...

出力が大きすぎてコンテキストを圧迫する場合は、-ignore* 系で対象を絞るか、必要部分だけ grep でフィルタする（例: isucrud -dst - ./... | grep 'table:users'）。

4. 出力の読み方

出力される Markdown には Mermaid グラフが含まれており、ノードとエッジが次の意味を持つ。

ノード種別:

table:<name> … DB テーブル
func:<pkgPath>.<funcName> … Go 関数

エッジ種別（関数 → テーブル / 関数 → 関数）:

INSERT / UPDATE / DELETE / SELECT … 関数からテーブルへの SQL
関数呼び出し … 関数から関数への呼び出し

ループ内で発行されているクエリは、isucrud 内部では InLoop フラグが立っており、Mermaid 上では対応するエッジに別系統の linkStyle が付くため、N+1 の候補として特定できる。

5. エージェントによる典型的な解析パターン

isucrud -dst - の出力を取得したあと、エージェントは以下のような解析を行う。

テーブル単位の利用箇所抽出
- 出力中で --> table:<対象テーブル> を含む行を抽出し、そのテーブルにアクセスしている関数を列挙する。
- 同様に、関数ノードを起点に深さ優先で辿ることで「この関数経由で触られるテーブル」を全て収集できる。
読み書き比率の集計
- SELECT エッジ数 vs INSERT|UPDATE|DELETE エッジ数を数えれば、キャッシュ候補（読み中心のテーブル）を発見できる。
N+1 候補の検出
- ループ内エッジ（Mermaid 上で別系統の linkStyle が付くもの）を起点に、ループの呼び出し元を追って真の N+1 を特定する。
影響範囲の確認
- 関数を変更する前に、その関数の祖先（呼び出し元チェーン）をグラフで辿り、最終的にどのテーブルに伝搬するかを確認する。

6. 注意事項

isucrud は SQL 文字列を簡易にパースしているため、fmt.Sprintf で組み立てた SQL や、ビルダ経由で動的に組み立てたクエリ、go:generate で生成される ORM のコードは検出漏れすることがある。結果は出発点であり、最終確認は対象ソースコードを Read/Grep で確認すること。
解析対象外（-ignore* フラグで除外したもの）はグラフに現れない。ノイズ削減と検出漏れはトレードオフ。
初回実行時は go mod download 等で時間がかかる場合がある。

クイックチェックリスト

エージェントが DB アクセスを把握したいとき、最低限以下を実行する。

# 1. 対象 Go プロジェクトのルートに居ることを確認
test -f go.mod || echo "Not a Go module root"

# 2. isucrud があるか確認、なければインストール
command -v isucrud >/dev/null || go install github.com/mazrean/isucrud@latest

# 3. 標準出力に解析結果を出して、エージェントが直接読み取る
isucrud -dst - ./...

得られた Mermaid セクションから func:... と table:... の対応関係を抽出し、必要な情報をまとめる。