1 人開発者のモノレポ vs マルチレポ — Graxel 運用 1 年後の振り返り

1 人開発者のモノレポ vs マルチレポ

ちょうど1年前、私は自身のソフトウェアエンジニアリングのキャリアにおいて、非常に重大かつ野心的なアーキテクチャ上の決断を下しました。それは、これまで複数に分散して管理していたコードベースをすべて完全に統合し、pnpm workspacesとTurborepoの強力な機能を活用した、単一の巨大な「モノレポ（Monorepo）」環境へ一斉に移行することでした。当時の私は、複数のSaaS（Software as a Service）プロダクトを同時に開発し、スケーリングさせようと孤軍奮闘している1人開発者にとって、これこそが保守性を極限まで高める究極で完璧な開発環境だと固く信じて疑いませんでした。しかし、それから1年が経過した現在、日々巨大化し複雑化していくモノレポをたった1人の力で維持するという、想像を絶する過酷な現実と直面し、私の考えは劇的に変化しました。この詳細な振り返りの記事では、私が初期に体験した魔法のような素晴らしいメリット、後に開発フローを完全に崩壊させかけた非常に苦痛なボトルネック、そして最終的に特定のプロジェクトを「マルチレポ（Multi-repo）」に再び分離するという苦渋の決断に至った深い理由を、包み隠さず共有します。

モノレポの光：Turborepoがもたらした圧倒的な恩恵

pnpm workspacesとTurborepoのモダンな組み合わせを導入したことで、私の日常的なコーディングのワークフローには即座に3つの革命的とも言える強力なメリットがもたらされました。

1. 共有パッケージ（Shared Packages）のシームレスな利便性: これが最大のメリットでした。美しくカスタマイズされたReactのUIコンポーネントや、極めて複雑なビジネスロジックを内包したユーティリティ関数をたった一度書くだけで、わざわざnpmのパブリックレジストリに公開する面倒な手間なく、5つの全く異なるWebアプリケーションで即座に使い回すことができました。この強力なビルドツールの驚くべき機能の詳細はTurborepoの公式サイトで確認できます。
2. 設定ファイルの中央集権的な完全制御: TypeScriptの厳格な型定義やESLintの複雑なルールを、ルートディレクトリで中央集権的に管理できたことは、膨大な時間の節約になりました。10個の異なるリポジトリのルールを個別にちまちまと更新する代わりに、単一の設定ファイルを変更するだけで全体に即座に適用されました。私がどれほど異常なまでにクリーンなコードの維持にこだわっているかは、私の詳しいプロフィールページをご覧ください。
3. アトミックコミット（Atomic Commit）による絶対的な整合性: コアとなるAPIのデータ構造を変更する際、バックエンドのロジック修正、フロントとバックで共有しているTypeScriptのインターフェース更新、そしてフロントエンドUIの表示変更を、すべて完全に同期した1つのGitコミットと1つのPull Requestで完結させることができました。これにより、本番環境でフロントとバックの不整合によるクラッシュが起きるリスクが完全に排除されました。

「技術スタックとドメインが完全に一致している時、モノレポは最高の効率を発揮します。しかし、全く異なる技術が混ざった瞬間、すべてを1つのリポジトリにまとめる教条主義は捨てるべきです。」

モノレポの闇：密結合が引き起こす悪夢の連鎖

しかし、モノレポの規模が徐々に拡大し、コードベースが肥大化するにつれて、1人開発者には到底対処しきれない3つの非常に深刻で致命的なデメリットが浮き彫りになりました。

• 恐ろしいバタフライエフェクト（連鎖障害）: 最もトラウマになった事件は、ある疲労困憊した金曜日の深夜に起きました。「legal-kr」という、韓国の法的プライバシーテキストを処理するだけの非常にマイナーで小さなパッケージの設定ファイルに、私がわずかなタイポ（打ち間違い）をしてしまったのです。これがなんと恐ろしいカスケード障害を引き起こし、私にとって最も重要な収益源である主力ポータルアプリケーションの本番CI/CDパイプラインが、3時間以上にわたって完全に麻痺してしまいました。すべてが強固に密結合しているため、末端の葉っぱのモジュールの小さな障害が、システム全体の木の根元のビルドを完全に破壊してしまったのです。
• 爆発的に増加するCI/CDの待ち時間: CI（継続的インテグレーション）の実行時間が劇的に悪化しました。かつてはわずか2分で気持ちよく終わっていたビルドとデプロイのプロセスが、苦痛に満ちた20分へと膨れ上がり、私のコーディングの集中力、忍耐力、そして高額なサーバーリソースを激しく消耗させました。pnpmの高度なキャッシュ戦略を駆使しても、巨大な依存関係グラフの前では限界がありました。
• フレームワークのメジャーアップグレードの絶望: React 18などのメジャーバージョンへアップグレードする際、モノレポ内の依存関係を持つすべてのプロジェクトを同時に強制的に更新し、すべてが動くか一斉にテストしなければならず、これは限られた時間しか持たない1人の開発者にとって、物理的に不可能なほど圧倒的な負担でした。

分離の決断とマルチレポへの回帰

私が最終的に限界に達し、方針転換を決意したのは、「saas-factory-trader」という全く新しい実験的なプロジェクトを開始した時でした。このアプリケーションはPythonによる高度なデータ処理と、リアルタイムのWebSocket通信に大きく依存しており、Next.jsとTypeScriptを中心とした既存のWebアプリケーションとは技術スタックもビジネスドメインも完全に異なっていました。この異質なPythonプロジェクトを、無理やりNode.js中心に最適化されたTurborepoの環境に組み込もうとしたのは、アーキテクチャ上の明らかな大失敗でした。最終的に私は自分の間違いを素直に認め、このプロジェクトを完全に独立したマルチレポとして分離する決断を下しました。

その分離の結果はどうだったでしょうか？デプロイメントパイプラインは完全に独立して他からの影響を受けなくなり、Pythonプロジェクト単体のビルド時間は瞬く間に元の1分へと劇的に回復しました。私のCI/CDに関するさらなる泥臭い苦闘の記録やアーキテクチャの変遷は、開発者ブログで詳しく読むことができます。結論として、1人開発者におけるモノレポ vs マルチレポの終わらない議論に対する、私の血と汗の滲む最終的な見解は以下の通りです。技術スタックとビジネスドメインが「完全に」一致している0〜10個のサービスを運営する場合においてのみ、モノレポのROI（投資対効果）は最大化され、開発スピードは驚異的に向上します。しかし、PythonのWebSocketサーバーとReactのWebアプリを混在させるような、根本的に異なる言語、フレームワーク、またはドメインを導入した瞬間、それらは直ちにマルチレポに分離しなければなりません。「すべてを1つの美しいリポジトリで管理する」というエンジニア特有の教条主義にとらわれて、最も重要な開発のスピードと柔軟性を絶対に犠牲にしてはならないのです。