📦

AIと作るモジュラモノリス | プロジェクト概要と初期構築編

に公開
Spring Boot
モジュラモノリス
技育祭
AI駆動開発
tech

概要

技育祭 2025 秋で登壇した時に語った「AI Drivenで開発することでOver Engineeringを解決する」という仮説を検証するためにプロジェクトを作ってGitHubにPushしたのでそのお話。

登壇時は以下のような話をしていました。

  • 「AIを使いやすくするためのアーキテクチャ」と「AIのコーディング速度で課題を解決するアーキテクチャ」の２種類が考えられる
  • コーディング速度で課題を解決するとなんか面白いことがあるかもしれないのでそっちを考えてみたい
    • 例としてSpring Modulithを採用したモジュラモノリスがある。モジュール間でやりとりするEventの設計にかかるオーバーヘッドをAIのコーディング速度で今と同じ工数ぐらいで実現できれば、拡張性が高いアーキを導入しやすくなるのではないか？
  • こういうことを考えられるアーキテクト/エンジニアが今後は求められるのではないかと思っている（キャリアに関する登壇だったので、こんなコメントもしていました）

「ライトに何か作ってみるか」ぐらいの感じだったのですが、気づいたら色々作り込んでいて完成までの道のりが長くなりそうだったので、一旦まとめてみたのが今回です。

資源は以下のRepositoryにて公開しています。この記事では全部を語りきれていないので、詳細が気になった方は参照してみてください。
https://github.com/AkioHoshikawa/spec-coding-modulith

サマリ

  • Spring Modulithを用いてAIベースに開発するときのアプリアーキを作ってみた。
    • 設計書とソースコードをMonorepoで管理
    • 人間とAIの両方にフレンドリーになれるようにmarkdownベースでの記載とPortalでの可視化
    • Processを明確に定義し、人もAIもそれに沿ってタスクを進める
  • まだ1本目のAPIを作っただけの段階なので、引き続きPoCを進めて開発のスケール性を検証していく。

プロジェクトの概要

構成

Monorepo方式になっており、現在は以下の3つに分かれている。

.
├── backend       ... Javaプロジェクト
├── doc           ... OpenAPI定義やUser Story
└── portal        ... docの中身を見やすくするためのポータルサイト資源

利用技術スタック

backend

JavaによるAPIサーバを提供するプロジェクト。

主要ライブラリ：

  • Spring Boot
  • Spring Modulith
  • H2

Modulithを利用した非同期メッセージングを内部で実装しているので、WebFluxを採用しています。API自体は同期的に応答するのですが、アプリ内部でのメッセージ待ち合わせはReactiveな実装です。

試験的なプロジェクトなのでDBはH2で簡易実装としました。

doc

設計書を格納しているディレクトリ。OpenAPI（YAML）やMarkdownなど、テキストベースの設計書にしてあります。エクセルとかパワポは使いません。

portal

doc を可視化するためのSSG。Docusaurusで実装しています。
Webでまとめて情報を見えるというのはプロジェクト上で実は重要で、開発者ではないステークホルダーが何かを調べる場合など、非技術者向けのユースケースで有用です。

GitHub Pagesでホストしているので以下から見れます。
https://akiohoshikawa.github.io/spec-coding-modulith/

特徴

Spring Modulithが提供するモジュラモノリスに関する特徴は公式の説明を読んでもらう方が確実なので以下をご参照ください。

https://docs.spring.io/spring-modulith/reference/

モジュールでドメイン境界を分割するので、コードベースの肥大化に応じてマイクロサービス化を検討できるというアーキテクチャになります。

多くのコンテキストを内包

アーキテクチャ方針書、設計書、そしてソースコードまで、開発に関わる多くの情報を内包しています。まずRepository内の情報を検索することで大半のことは解決できるため、AI Agentが情報にリーチしやすい形としています。

内包していないものとしてはタスク情報のようにJiraで管理するものや、Slackなどでのコミュニケーションログ、そしてIF連携を行う外部システムの情報などが挙げられます。これらに関してはMCPを活用して取得してくるイメージです。

Process定義

どのように開発を行うのか、シチュエーション別にProcessが定義されています。
初期段階で作成したのは以下です。

Process名 内容
要件ドキュメント更新 User Storyなど要件に関するドキュメントを更新する場合のプロセス
User StoryからAPI設計に分解する User Story定義を元に必要なAPIを特定し、OpenAPI設計書に反映する
新規API実装 OpenAPI定義とUser Storyに基づいてAPIの実装を行う

人間もAIもこのProcessを用いて作業することを想定しており、双方が作業者もしくはレビュアーになる可能性を考慮して中身を記載しています。Input, Process, Output, Checklistという4つの項目をPhaseという単位でグループ化して定義するようにしてあります。

また、各Processに対応するAgentを作成してあります。現在はGitHub Copilot向けのAgentとして記載しており、利用するToolなどを特定することによって効果的な生成を狙っています。

ポータルによる設計の可視化

Mermaidなどでシーケンスを表現する場合、VS Codeなどを使って手元で可視化することは容易ですが、開発環境を持たないメンバーもプロジェクト内には居ます。業務プロセスなどを検討してくれる業務事情に強いメンバーをイメージしており、業務視点で設計のレビューを行ってくれたり、結合テストまたはシステムテスト向けのテストシナリオを作成することもあるため、彼ら向けに可視化しておくことは重要です。

開発者であってもWebから手軽に見れる方が楽なことも多いので、なんだかんだ役に立つと思っています。

ドメインごとのイベント発行

Modulithの機能でApplication内でイベントを発行して各モジュールがやり取りをします。
このイベントをDBに保存しており、どのようなイベントが発生したのかをドメインごとに取得することが可能となっています。

これ自体はイベントの送達保証の仕組みなのですが、別のDBにレプリケートする or イベントのやり取りをKafkaなどのメッセージング基盤に差し替えることでアプリ内で起きたことがドメインごとにわかるようになります。Streamingでリアルタイムにシステムで起きていることをキャッチできるため、時系列分析などで何かの傾向が見えたらユーザに対してアプローチを開始するAgentとかを作れるのではないかと思っています。

初期構築

初期構築のタスクとしては以下を実施しました。

  • プロジェクトのコンテキスト（要件）の作成
  • ベースラインとなるAPIサーバのアプリアーキ作成
  • 1本目のAPI作成

それぞれについて、どんな作業だったのかを解説していきます。

コンテキスト（要件）の作成

要件に関してはある意味でっち上げれば良いものだったので、LLMを駆使して色々生成しました。
そのままだと冗長なところが多かったので色々削って今の形にしてあります。

APIサーバのアプリアーキ作成

ここに関しては結構手動です。AIに質問することはあれど、実際にコードを書いたりディレクトリ構造を整備するのは自分でやっていました。
AIにやってもらえるところもあると思うのですが、考えながら作っているためAIに対して明確な指示が出しづらく、思ったものをなかなか出せなかったので自前でコーディングしていました。

AIの能力が上がったり、もうちょっとアーキテクチャそのものを作成するPrompt技術を身につければ改善できる気がします。

1本目のAPI

最初はAIで生成してみたものの、結局かなり手直ししました。ルールを固めきれていないところがそこそこあり、それを固めながら作り直して行ったほうが効率的だったためです。
1本目のAPIをしっかり作り込んで今後の開発の鑑として使える品質を担保したかったというのも手直しが多めになった理由です。

(手直ししたものの、認証とか冪等性担保の仕組みは作りきれなかったのでTODOはありますが🫠）

ここまでやってみて

  • Processを定義してそれに対応するAgentを作り込んでいくやり方は上手くいきそうな感じ。
  • モジュラモノリスに関してはAIとの相性がまだ未知数。構造的には良いかもと思いつつ、もっとルールを整備しないと上手くワークしないかも。
  • WebFlux + イベント駆動はちょっとやりすぎたかも。Reactive StreamをJavaでやりつつEventも設計するのはキャッチアップの負担が大きい。
    • ただ、通常のServlet型でやるとイベントのBlock処理が難しそうなので概念的にはこの2つは相性がいいはず・・・。有識者が少なそうというトレードオフをどう考えるか次第かな。
    • Spring Modulith固有の挙動とかもありそうなので共通機能の整備も重要そう。

次回にむけて

準備に時間をかけすぎた感がありますが、もうちょっとだけProcessなどを整備すればAgentベースで開発を回せるはずなのでそれを試してレポートしたいなと思っています。あと、Event定義の設計書はあえて作っていないのですが、カタログは生成しないと厳しそうなのでその辺りの所感とか対応案みたいなものをまとめられればなと考えています。

Discussion