そのドキュメント、自動化しませんか？

Transcript

1. 2026.07.20 そのドキュメント、 ⾃動化しませんか？ スプレッドシートのモデル⼀覧を、コードから⾃動⽣成へ 内藤勇介
2. // ABOUT ⾃⼰紹介 内藤勇介 / Yusuke Naito @yuksew ユースタイルラボラトリー株式会社 ∙ 訪問介護向け SaaS「カイビズ」を開発 ∙ バックエンドエンジニア / 設計 ∙ 最近: 介護報酬の請求計算、開発体験の向上 02
3. // AGENDA 今⽇話すこと 01 スプレッドシートでモデル⼀覧を作るつらみ 02 正本（SSOT）はコードへ。モデル⼀覧は⽣成する 03 同じやり⽅を DB にも 04 まとめ 03
4. // BACKGROUND スプレッドシートでモデル⼀覧を作るつらみ 07
5. // BACKGROUND ドメインモデル⼀覧をスプレッドシートで管理していた • モデルとフィールドの⼀覧（論理名‧型‧必須‧備考） • モデルを追加‧変更するたびに、シートも⼿で更新 • OpenAPI のスキーマをここから⽣成していた 04
6. // BEFORE 当時の仕組み 自動 スプレッドシート モデル⼀覧 GAS schemas.json 生成 components/schemas スキーマ定義 openapi.yaml 手動 / AI → HTML API の定義 ⼿書き（または AI） schemaは⾃動⽣成。API のパス定義は⼿書き、シートの更新は⼿作業。 05
7. // BEFORE つらみ • 5年間の開発でシートが 350 枚を超えた • リポジトリ外なので コミット‧PR に残らない • 検索‧相互参照に弱い • AI で読み書きがしづらい 06
8. // APPROACH 正本はコード、⽣成はツールに任せる。 07
9. // TYPESPEC TypeSpec とは models/common.tsp /** 氏名 */ @OpenAPI.extension( "x-kind", "valueObject") model StructuredName { familyName: string; givenName: string; displayName: string; } API‧モデルを定義する⾔語 TypeScript ライクに書ける メタ情報も TypeSpec に書ける 08
10. // BUILD ─ API モデル⼀覧と OpenAPI を⽣成する TypeSpec 定義 openapi:build models/*.tsp tsp compile ＋ 生成スクリプト モデル⼀覧 OpenAPI tsp compile → OpenAPI（openapi.yaml） build-html.js → API ドキュメント（HTML） build-model-docs.js → モデル⼀覧（models.html） 09
11. // BUILD 同じやり⽅を DB にも 07
12. // BUILD ─ DB DB は実物から抽出する migration tbls + Liam 380 本（スキーマの正本） MySQL に migrate → スキーマ抽出 ER図‧DB定義書 tbls k1LoW/tbls 実 DB からスキーマを抽出し、DB定義書を⽣成 Liam @liam-hq/cli 抽出したスキーマから ER図 を⽣成 11
13. // PIPELINE push 1回で、全部が更新される OpenAPI TypeSpec 定義 models/*.tsp GitHub Actions openapi:build モデル⼀覧 ER 図 migration GitHub Actions tbls + Liam DB 定義書 GitHub Actions で実⾏ → Cloudflare Pages に公開。 ⽣成物を相互リンクで接続。 12
14. // BEFORE → AFTER 変わったこと Before After • シート 350枚超を⼿で維持 • push 1回で⽣成‧更新 • コミット‧PR に残らない • コミット‧PR‧差分に乗る • 検索‧AI 連携に弱い • 検索‧AI に強い 13
15. // TAKEAWAYS まとめ 01 正本はコードに置き、モデル⼀覧は⽣成する 02 push 1 回で、ぜんぶ最新になる 03 AI が読める「正本」に寄せる 14
16. // THANK YOU ありがとうございました