こんにちは！RemitAidでソフトウェアエンジニアをしているnos0611です。
本記事では先日社内で実施したリポジトリ統合について記載していきます。
従来のリポジトリ構成
RemitAidで開発しているAPIの関連リソースについて、従来は以下の3つのリポジトリに分けて管理されていました。
- Goで実装したAPI本体
- テーブル定義とマイグレーションファイル
- ドキュメント類（API定義書やER図、ADRなど）
この構成に社内でいくつか課題を感じてきたことがモノリポ化検討のきっかけです。
従来のリポジトリ構成における課題感
主な課題としては以下のようなものを感じていました。
API本体とテーブル定義が別リポジトリに分かれていることでの開発体験の悪さ
API側のリポジトリからテーブル定義をGoのモジュールとして取り込む形をとっていたのですが、両リポジトリでの同期が地味に面倒でした。
テーブル定義を修正した上でAPIの開発を行いたいが、テーブル定義側のリポジトリにまだマージされていないためにAPI側で修正をしようとするとコンパイルエラーが出てしまう、といったような現象が発生します。
また、実際よくあったわけではありませんが、修正をリバートするような場合に両リポジトリの該当コミットを適切に処理する必要があるのもややリスキーです。
AIフレンドリーではないのでは？
別のブログ記事でも何度かご紹介していますが、RemitAidでは開発にClaude Codeを使用しています。
複数のリポジトリを跨いだ指示を出すこと自体は上の階層でClaude Codeを開けば出来ますが、その場合に設定ファイルなどを置く場所が各リポジトリの外になってしまうためチームでの共有が少し煩雑になります。
また、上の階層でClaude Codeを実行する場合には関係あるリポジトリだけを参照するよう逐一指示を出す必要がありますが、モノリポの方が読み取るコンテキストが明確になる分アウトプットの精度や適切性が向上することが期待できると考えました。
新リポジトリ構成
このような課題を踏まえ、以下のようなリポジトリ構成に変更することとしました。
現在はまだ実施できていませんが、フロント側のリポジトリも統合することを見越した構成にしています。
/
├── .claude/: 共通で使用したいClaude Code設定を格納
├── .github/
│ └── workflows/: BE/FEどちらで使うものもここに格納する
├── apps/: 各アプリケーションの開発や実行に必要なファイル
│ ├── backend/
│ │ ├── src/: ビルド対象とするファイル群
│ │ ├── deployments/: 各環境でのビルドに必要なファイル群
│ │ ├── migration/: 環境を問わず使用するマイグレーションファイル
│ │ └── Makefile: backendディレクトリで使用するコマンドを記載
│ ├── （front-admin/）
│ │ ├── src/: ビルド対象とするファイル群
│ │ ├── deployments/: 各環境でのビルドに必要なファイル群
│ │ └── Makefile: front-adminディレクトリで使用するコマンドを記載
│ ├── （front-user/）
│ │ ├── src/: ビルド対象とするファイル群
│ │ ├── deployments/: 各環境でのビルドに必要なファイル群
│ │ └── Makefile: front-userディレクトリで使用するコマンドを記載
│ └── （アプリケーションを跨いで使用する定義などがあればapps配下に配置）
└── docs/: ドキュメント類
├── ADR/: ArchitectureDecisionRecord
├── openapi/: API仕様書
├── er/: ER図
└── sequence/: シーケンス図
元々別リポジトリで管理していたマイグレーションファイルを/apps/backend/migrationに移行し、そのマイグレーションから生成される型情報をapps/backend/src配下に移動したことで、アプリケーションコードとの同期が取りやすくなっています。（ついでにドキュメント類も統合したため、ER図なども同様に同期が取りやすくなっています）
また、Claude Code向けの設定ファイルもリポジトリ直下で共有しやすくなりました。
余談ですが、リポジトリの構成図を書くのにはTreeを使わせてもらいました。
タブで階層を操作できるのが直感的で使いやすいのでオススメです。
移行してみて
開発体験については格段によくなりました。
テーブル定義の修正で影響が出るアプリケーションコードも一つのPRで修正できるため、安全性が上がったというのもメリットです。
AIフレンドリーなのかどうかについては定量的な判断が難しいので何ともではありますが、「えーっと一つ階層を上がってからclaude叩いて、テンプレの指示文を用意して〜」みたいなことをしなくてよくなったのは素直に楽でいい感じです。
あとは副産物として、よくある設計ドキュメントどこに置くか問題も「モノリポにつっこんでしまった方がAIが読み込みやすいので」という形で収束したのも良かったかなと思います。
作業自体は構成を決めてしまえばあとは移動するだけという感じなのですが、構築に使用しているDocker関連やMakefile、GitHubActionsなどのパス指定をきれいに整えるのが地味に一番面倒で大変でした、、、。
また、GitHubActionsのパス指定を直して動くようにしたのですが、ドキュメントを修正しただけなのにアプリケーションのテストが無駄に回るといったことが発生してしまいました。
モノリポ化する時はGitHubActionsのトリガー範囲を調整し、ワークフローが適切に回るよう合わせて対応する必要がある点に注意が必要です。
まとめ
APIのアプリケーションコード、テーブル定義、ドキュメントのモノリポ化について紹介しました。
こんな構成にしていてオススメ！というようなものがあればぜひ教えていただけたら嬉しいです！
We Are Hiring!
RemitAid では一緒に働く仲間を募集しています。
興味がある方はこちらからどうぞ！
Podcast 「RemiTalk」を最近始めましたので、どんな会社なのかもっと知りたいという方は良ければ聴いてみてください！ RemiTalkの文字起こしはこちら
Discussion