tbls Doc Skill

tblsを使用してデータベースのスキーマドキュメントを生成する。

When to Use This Skill

Trigger when user:

•/tbls-doc コマンドを実行
•「DBのドキュメントを生成して」「スキーマドキュメントを書き出して」と依頼
•「tblsで出力して」と依頼

前提条件

tbls がインストールされていること:

bash

brew install tbls

または:

bash

go install github.com/k1LoW/tbls@latest

実行フロー

Step 1: 接続情報の確認

ユーザーからDB接続情報を受け取る。引数がない場合は確認する。

対応形式:

•DSN: postgres://user:pass@localhost:5432/dbname
•DSN: mysql://user:pass@localhost:3306/dbname
•DSN: sqlite:///path/to/db.sqlite
•.tbls.yml が存在する場合はそれを使用

bash

# .tbls.yml の存在チェック
ls .tbls.yml 2>/dev/null || ls .tbls.yaml 2>/dev/null

Step 2: 出力先の確認

デフォルト: ./docs/schema

ユーザーが指定した場合はそちらを使用。

Step 3: tbls 実行

bash

tbls doc <DSN> <出力先> --force

オプション説明:

•--force: 既存ドキュメントを上書き
•DSN がない場合は .tbls.yml から読み取り: tbls doc --force

Step 4: 結果を報告

生成されたファイル一覧を表示:

bash

ls <出力先>/

報告フォーマット:

code

## 完了

スキーマドキュメントを生成しました。

出力先: <出力先>/
テーブル数: X 件

### 生成ファイル
- README.md（テーブル一覧 + ER図）
- <table_name>.md（各テーブルの定義）

### 次のステップ
- `tbls lint` でスキーマの品質チェック
- `tbls diff` で既存ドキュメントとの差分確認

Step 5（任意）: ドキュメント内容の確認

ユーザーが希望すれば、生成された README.md を読んで概要を共有する。

オプション

ユーザーが追加指示をした場合:

指示	コマンド	説明
「lintもして」	`tbls lint <DSN>`	スキーマの品質チェック
「差分見せて」	`tbls diff <DSN> <出力先>`	DB とドキュメントの差分
「設定ファイル作って」	`tbls config`	`.tbls.yml` のひな型生成
「ER図だけ」	`tbls out <DSN> -t mermaid`	Mermaid形式でER図出力
「JSON で」	`tbls out <DSN> -t json`	JSON形式で出力

.tbls.yml の例

プロジェクトに設定ファイルがある場合、DSN指定が不要になる:

yaml

dsn: postgres://user:pass@localhost:5432/dbname
docPath: docs/schema
er:
  format: mermaid
lint:
  requireTableComment:
    enabled: true
  requireColumnComment:
    enabled: true

コマンド例

bash

# 基本（DSN指定）
tbls doc postgres://user:pass@localhost:5432/mydb ./docs/schema --force

# 設定ファイルから
tbls doc --force

# lint
tbls lint postgres://user:pass@localhost:5432/mydb

# 差分確認
tbls diff postgres://user:pass@localhost:5432/mydb ./docs/schema

# Mermaid ER図出力
tbls out postgres://user:pass@localhost:5432/mydb -t mermaid

# JSON出力
tbls out postgres://user:pass@localhost:5432/mydb -t json

使用例

code

/tbls-doc postgres://user:pass@localhost:5432/mydb

または

code

DBのスキーマドキュメントを生成して