AIのための特別なアーキテクチャはいらない 0→1開発で実践した設計原則とガードレール

カミナシ Tech Night #3
https://kaminashi.connpass.com/event/387233/

Shimmy
ソフトウェアエンジニア

Transcript

1. AIのための特別なアーキテクチャはいらない 0→1開発で実践した設計原則とガードレール カミナシ Tech Night #3
2. ⾃⼰紹介 • 名前: Shimmy • 所属: 株式会社カミナシ ◦ ソフトウェアエンジニア ◦ カミナシで新規プロダクトを開発中 ◦ TanStack Startを使ってFull TypeScriptで開発 • その他: ◦ 最近はポケポケに時間を取られています ◦ AIのお陰で個⼈開発にまた⽕がついて、ゴリゴリコードを書いてます （AIが）
3. 今⽇話すこと 1. AIの⼒を最⼤限引き出す設計条件 2. その設計を決定論的に守らせる仕組み
4. AIの⼒を最⼤限 引き出す条件
5. 条件1: 関⼼の分離
6. Feature-First構成 関⼼事でディレクトリを分ける • ある機能を修正したいとき、修正したい箇所がまとまって いると扱いやすい • 1つの関⼼事がすべて1ディレクトリの中にあるのでAIの コンテキストに載せやすい • 並列にAI開発しても関⼼ごと別に分ければコンフリクトし にくい
7. 結合をバランスさせる 結合を「避ける」のではなく「バランスさせる」 • 「結合の強さ」が⾼いなら「距離」を短く ◦ -> Feature内部は⾼凝集 • 「距離」が⻑いなら「結合」を弱く ◦ -> Feature間は疎結合
8. Feature内のディレクトリ構成 • domain/ ◦ 純粋関数のみ • infrastructure/ ◦ DBアクセスなどI/O • server/(api) ◦ オーケストレーション domainとinfrastructureを組み⽴てる • index.ts ◦ Public API 外部に公開するものだけをexport
9. Featureを横断するケー ス
10. パターン1: shared/ 複数featureが使う共通ロジックを切り出す • 純粋関数をsrc/shared/lib/に置く • 依存⽅向は常に features/ → shared/
11. パターン2: routes/ 複数featureを組み合わせるページ • 各featureのPublic APIをimportして統合する • featureは互いの存在を知らない
12. 条件2: 価値の⾼いテスト
13. テストの4つの柱 『単体テストの考え⽅/使い⽅』より • 退⾏保護: バグを⾒逃さない • リファクタリング耐性: 内部を変えても壊れない • 迅速なフィードバック: すぐ結果がわかる • 保守しやすさ: テスト⾃体がシンプル
14. 出⼒値ベーステスト • Inputを⼊れてOutputを検証する • 内部実装に依存しない → リファクタリング耐性が⾼い • モック不要でAIに書かせやすい • テスト実⾏が速い → AIの試⾏錯誤ループが速く回る
15. domain層の純粋関数 • Inputを受け取り、純粋関数を組み合わせて計算し、 Outputを返す • DB参照なし、副作⽤なし、I/Oなし
16. domain層の関数のテスト • テストはInputを組み⽴て 関数を呼び、Outputを検証するシンプルなもの • モック不要、DI不要
17. Functional Core + Imperative Shell I/Oとロジックを分離し、副作⽤を端においやる • Functional Core ◦ domain/ : 純粋関数でビジネスロジック • Imperative Shell ◦ infrastructure/: DBアクセスなどI/O操作 ◦ server/ : API層。組み⽴ててエンドポイントを提供する
18. 設計を決定論的に 守らせる仕組み
19. なぜ「決定論的」的に守る必要があるか • ルールを教えただけでは守らないことがある • AIの出⼒速度に⼈間のレビューが追いつかない -> 決定論的に守る「ガードレールが必要」
20. ガードレールの条件 • 決定的であること ◦ AGENT.mdは確率的 → 守られないことがある -> 決定的なシステムが必 要 • 速くフィードバックできること（Shift Left） ◦ AIの試⾏錯誤ループの中でフィードバックしたい
21. 静的解析 dependency-cruiser
22. dependency-cruiserで設計を強制する import⽂を静的解析して依存関係のルール違反を検出する ツール • 設計思想をdependency-cruiserのルールとする • 新規プロダクトでは12個のルールを定義
23. ルール定義①: 純粋なドメイン層 domain/からinfrastructure/やserver/をimportす るとエラー
24. ルール定義②: Feature間の疎結合 同⼀feature内はOK。別featureを直接importするとエラー
25. ルール定義③: Public API境界 index.tsを通さずにfeature内部を参照するとエラー
26. その他の静的解析ツール • knip: 未使⽤コードを検出 ◦ AI実装で⽣まれる未使⽤exportやファイルを⾃動検出 • Biome: コード品質を統⼀ ◦ any型禁⽌、⾮nullアサーション禁⽌、awaitされていないPromise検出
27. Git hooksで統合する
28. lefthook: コミット前に⾃動で弾く • pre-commit: Biomeのチェック + dependency-cruiser • pre-push: 型チェック + knip + テスト
29. 開発フロー アウトプットではなく、プロセスを信頼できるものにす る 1. AIにコードを書かせる 2. git commit a. Biome + dependency-cruiser が⾛る b. 設計違反があればエラー c. → AIが⾃動修正 3. git push a. → 型チェック + knip + テスト が⾛る
30. まとめ
31. 設計条件を振り返る • 関⼼の分離 ◦ 関⼼事ごとにファイルをまとめる ◦ AIのコンテキストに載せやすく、並列開発でもコンフリクトしにくい • 価値の⾼いテスト ◦ domain層を純粋関数で構成し、出⼒値ベースの単体テストを書く ◦ モック不要でリファクタリングに強い。質の⾼いテストを書きやすい構 造が整う • 依存⽅向の決定 ◦ 層ごとのルールを明確にする ◦ AIが迷わず、静的解析で機械的に強制できる
32. 設計を決定論的に守らせる dependency-cruiserで設計思想をガードレールに • domain層から他の層をimportしたらエラー • 別featureを直接importしたらエラー • index.tsを通さずfeature内部を参照したらエラー knip + Biome も活⽤し、lefthookで確定的に実⾏
33. 良い設計をちゃんと守る
34. 株式会社カミナシ https://kaminashi.jp