はじめに

この記事は人間が書いた駄文を元に、生成 AI で誤字脱字などのレビューをしています。 #Human-Authored!

株式会社ライトカフェ AI駆動開発G Group Manager の仙波（@semba_yui）です。
AI を使った効率的な開発の仕組み化について Claude Code を使いながら検証する ~~怒り狂う~~ 日々を過ごしています。

この記事では AI 駆動開発におけるすべてのベースになる、Documentation as Code に際した、便利ツールの組み合わせを紹介したいと思います。

TL;DR

tbls は markdown 形式のテーブル定義書 & ER 図 & schema.json が自動生成できる
Liam ERD に tbls の schema.json を読ませることで大量のテーブルでも読みやすく表示できる
tbls でテーブル定義書、Liam ERD で ER 図の自動生成をすることで人間と AI に読みやすく、かつ正しいドキュメンテーションが継続できる

この記事の対象読者

テーブル定義書を読もうと思ったらメンテナンスされていない Excel しか無いよと言われたことがある人
逆に実装優先でテーブル定義書などのドキュメンテーションのメンテナンスを諦めている人
tbls などER図の自動生成ツールを導入したものの、テーブル数が増えすぎて把握できない図が生まれてしまった人

とりあえず結論

出来上がったテーブル定義書と ER 図はこちらです。
GitHub Pages へホスティングしています。

元リポジトリはこちら

使うツールのざっくり紹介

tbls とは？

DB のスキーマを読み取り、以下のようなドキュメントを自動生成してくれます。

ER図
テーブル定義書
- markdown
- Excel などなど
スキーマデータ（schema.json）

これだけでも大変便利ですし、中でも viewpoints機能 はかなり重宝できる神機能です。

しかし、本採用して運用していくと1点辛い部分が発生してしまいます。

tbls をエンプラ企業で採用したときのツラミ

tbls をエンプラ企業で採用したときのツラミ、テーブル数が多すぎて自動生成された ER 図が蜘蛛の巣みたいになる問題 が発生します。

（~~私のサンプルリポジトリでそこまで再現する気力が出なかったので~~）11 テーブルだけの図を用意しました。

11テーブルだけでも文字の重なりがあってところどころ厳しいのがわかるかと思います。
これが50テーブル↑になってくると、、、

ここを解決するのが Liam ERD です！

Liam ERD とは？

ER 図を自動生成することに特化したツールです。

自動生成された ER 図は React Flow で美しくレンダリングされ、ズーム／検索／関係のハイライトなどが可能です。大量のテーブルが生まれても ER 全体像の把握や、リレーションの把握がしやすいような UI / UX になっています。

また、Liam ERD も単体で採用するのではなく、tbls 側で論理 FK なども定義することができるため、tbls で作成した schema.json を使うからこそ、更に把握しやすい ER 図を描いてくれます。

実際に導入してみる

tbls 導入編

Docker 版の tbls を使うと、tbls を吐き出す用の一時 DB とともに docker compose にまとめられるので便利です。

日本語は文字化け問題があったので自前でお気に入りの HackGen フォントを入れています。

.tbls.yml では論理 FK や日本語で出力してもらうためのラベリングなど、各種設定ができます。

Liam ERD 導入編

こちらは Liam ERD CLI を使いました。

pnpm dlx @liam-hq/cli init

基本的には Quick Start に従うのみで問題ありません。

ビルドも簡単で、tbls が吐き出す schema.json を指定してあげるだけです。

ビルドの場合

pnpm dlx @liam-hq/cli erd build --format tbls --input docs/schema/schema.json --output-dir docs/out

ローカルサーバーで確認する場合

pnpm dlx serve docs/out

その他マイグレーションツールなど

今回は Flyway を使ってローカルに立てた MySQL へ自動で DDL が流れるようにしています。
その MySQL の情報を下に、tbls のドキュメントを吐き出している形です。

注意点は、Flyway の DDL が流れきってから tbls で出力してあげないと各種自動生成に失敗してしまうぐらいです。

PS: 既存の仕組みでいいという風潮と戦うあなたのために

仕組みを一気に切り替えるのではなく、徐々に切り替えることが重要です。

markdown と一緒に Excel 形式でもテーブル定義書を吐き出す

Excel 設計書、~~個人的には嫌いですが、~~ 今まで Excel を使って慣れてきたメンバーも多く、かつ Excel だと関数を使った集計などもできて便利だったりしますよね。

そこで tbls です。ありがたい。
なんと tbls は Excel 出力にも対応してます。

HTML にビルドする際、ついでに Excel 形式で吐き出しておいて上げればいいわけです。
Excel で見たい人にはこれを渡して参照するなり書き込んでもらったりすれば OK です。

サンプルコードでは、CI で Artifacts として吐き出すようにしてあります。

ただし、Single Source of Truth（唯一の真実の源）はあくまでデータベース本体です。
Excel に色々書き込んでオレオレ仕様書を作ってこれが最新だと運用するのはやめておきましょう。

※ Single Source of Truth のイディオムは o3 から学びました。o3 ってこういう語彙好きな傾向あるよね。

ドキュメントは GitHub Pages、もしくはプロジェクトメンバー向けの静的サイトなどでホスティングしてあげる

作成したドキュメントは markdown → HTML にビルドしてくれるようなツールを使い、エンジニアだけが読み慣れた markdown 形式ではなく、Biz、Ops 層にも読みやすいようなドキュメンテーションに整えて上げることが重要です。

エンジニアだけでなく、プロジェクト全体で AI を使うための基盤を整えることが AI 駆動開発含む、AI 駆動〇〇全てにおけるベストプラクティスになると考えています。

静的サイトにビルドしてくれるツールの例

npm で導入できるツールだと以下のあたりが有力です。
それぞれ一長一短あるので、プロジェクトに応じて使い分けてください。

VitePress: 今回はこちらを採用
Astro Starlight
Docusaurus

Python 系のプロジェクトだと mkdocs も良かったです。

ちなみに検索窓をプラグインで追加できたり、デフォルトで持っているようなツールが楽です。あのカラムどれだったっけな？が grep できて使い勝手が向上します。

AI にテーブル情報を把握させるにはどれを読ませるといい？

これは SQL ファイル自体を読ませるのが一番手っ取り早く、token 効率もいいです。
図は人間が読みやすいですが、AI に与えるには少し効率が悪かったりします。

コンテキストエンジニアリングの精度がそのまま生成 AI の精度にも関わってくるので、なるべく効率よく情報を渡して上げる必要がありますね。

おわりに

今回は tbls × Liam ERD （× GitHubPages (VitePress)）で人間、そして AI にも、理解しやすいテーブル定義書と ER 図を自動生成する方法を解説しました。

tbls 作者様の The future of tbls and "Documentation as Code" / phpconfuk 2023 の記事は必見です。
tbls 自体の使い方もこの記事以上にわかりやすく紹介されていますが、個人的にはそれよりも以下の一説がお気に入りです。

ドキュメントが更新されれば、人は更新分について正しいかどうかレビューできる。しかし、システム開発が進んで取り残されてしまったドキュメントのレビューはできない。

この思想が AI 駆動開発におけるレビュー負荷の問題を解消するためには重要です。

Claude Code を並列起動することで成果物が圧倒的なスピードで運ばれてきますが、レビューしきれない問題。人間がレビューするための基盤づくりを整えることもまた、AI 駆動開発を仕組み化するときには避けられません。

ドキュメント → 実装と順を追ってレビューしていくことで、AI のアウトプットに対するレビュー負荷を下げ、持続できるようになっていくのだと考えています。

AI 駆動開発の関連記事

問い合わせ先

株式会社ライトカフェ / 株式会社ライトカフェクリエイションへの案件のご依頼・ご相談は、以下までご連絡ください。

Mail: info@lightcafe.co.jp

We are hiring!

株式会社ライトカフェ / 株式会社ライトカフェクリエイションは、エンジニアを積極採用中です！
詳細は以下をご覧ください。

※その他メディア：noteでは、会社の魅力や雰囲気などを発信しています。