🏗️
AI開発におけるモノレポの有用性と実践例

ueryooo
2025/07/31に公開
こんにちは、株式会社Liacの上山です。

AI時代において最新トレンドを追うことも重要ではありますが、今後数年は特に、開発の基盤となるアーキテクチャ設計への投資が重要になると考えています。

本記事では、そのアーキテクチャ設計の一端として、モノレポの有用性と実践例をまとめました。

 要約AI開発ではコンテキストが重要
モノレポ構成によりコンテキスト管理を簡素化
コード品質の標準化等、多くの副次的効果も実現

 前提本記事内では以下のツールを使用しています。
パッケージマネージャー: Bun
モノレポ管理ツール: Turborepo
AIツール: Claude Code

 はじめに多くの組織では、歴史的な経緯やBizとの兼ね合い等により、開発に必要な情報が複数のツールに分散して管理されているのが現状です。例えば、ソースコードはGitHub、要件定義書や議事録はNotion、そしてPDF等のドキュメント類はGoogle Driveといったように、情報の保管場所が多岐にわたることは少なくありません。
AI開発ではソースコードだけでなく、議事録や要件定義書などの周辺情報も重要なコンテキストです。情報が分散した状態では、AIが最適なコンテキストを参照できず、実装時に仕様変更の反映漏れ等が多発します。
MCPを用いて外部リソースを読み込むことも可能ではありますが、弊社では運用の簡潔さとSSOT（Single Source of Truth）を重視し、プロジェクトに関する全情報をモノレポで一元管理することにしました。

 モノレポ構成例と有用性AI開発において一元管理型のアーキテクチャを採用することで、開発効率の向上を実現しています。本セクションでは、具体的な活用方法と効果について解説します。
project/
├── apps/
│   ├── api/
│   │   └── CLAUDE.md          # API固有の指示
│   └── mobile/
│       └── CLAUDE.md          # モバイルアプリ固有の指示
├── packages/
│   ├── ui/                    # デザインシステム
│   ├── db/                    # データベース層
│   └── logger/                # 共通ロガー
├── configs/
│   ├── tsconfig/
│   └── vitest/
├── docs/
│   ├── mtg/                   # 議事録
│   ├── notes/                 # メモ
│   ├── requirement.yaml       # 要件定義書
│   └── requirement.schema.json # 要件定義書のスキーマ
├── CLAUDE.md                  # プロジェクト全体の指示
├── package.json
├── bun.lockb
└── turbo.json

 最新コンテキストを保った開発環境弊社では、タスク管理にGitHub IssuesとProjects、要件定義書にYAML形式を採用しています。モノレポ構成の利点を活かし、プロジェクト全体のコンテキストを一元的に把握することで、以下のような仕組みを実現しています。
ミーティング議事録から要件定義書への自動反映

Claude Codeのカスタムスラッシュコマンドを使用して、議事録の内容から要件定義書を即座に更新
要件定義書からのタスク自動生成

同様にカスタムスラッシュコマンドを活用し、要件定義書の内容をもとにGitHub Issueを自動作成
継続的な整合性チェック

GitHub Actionsを日次で実行し、コミットと要件定義書の差分を検出。不整合があれば自動的にPRを作成し、要件定義書の最新性を保証
この仕組みにより、ソースコード、要件定義書、Issueの3要素が常に同期された状態を維持できます。また、すべての変更履歴がGitで管理されるため、誰がいつ何を更新したかを完全に追跡でき、プロジェクトの透明性が格段に向上します。

 開発生産性の向上
 認知負荷の低減モノレポでは、各プロジェクトごとに1つのリポジトリを見るだけで全てを把握できるため、複数のエディターを立ち上げる必要がなく、認知負荷が大幅に軽減されます。

 具体例例えば、以下のような場面でモノレポの利点が顕著に現れます。
1. Hono RPC

ExpoとHono RPCを組み合わせた構成では、Hono側の型定義変更がクライアント側に即時反映されます。エンドポイントの追加や変更時も、型安全性を保ちながら素早く開発を進められます。
2. Worker間の直接通信

Cloudflare WorkersのService Bindingを使用すると、Worker間で直接メソッドを呼び出せます。モノレポ構成では、各Workerの型定義が同一リポジトリ内で管理されるため、Worker間の通信も型安全に実装でき、リファクタリング時の影響範囲も即座に把握できます。

 単一コマンドでの開発環境構築従来のポリレポ構成では、モバイルアプリとAPIサーバーを別々に起動し、さらに各種開発ツールも個別に立ち上げる必要がありました。モノレポとTurborepoを活用することで、bun run dev 1つですべての開発環境が同時に起動します。
Expo: モバイルアプリの開発サーバー
Hono RPC: APIサーバー（型定義の自動同期付き）
Storybook: UIコンポーネントの確認環境
Vitest: 単体テストの監視モード
その他の開発ツール
この統合環境により、開発者は複数のターミナルを行き来することなく、1つの画面で開発に集中できます。また、bun run test:e2eのような単一コマンドで、モバイルアプリとAPIの連携を含む統合テストも実行可能です。

 コード品質の標準化モノレポでは、LintやFormatterの設定をプロジェクト全体で共通化できます。Biome、markdownlint、textlintなどを導入することで、ソースコードはもちろん、ドキュメント類も一定の水準を保つことができます。

 デザインシステムの実現共通のUIコンポーネントやデザイントークンをpackages/uiに集約することで、Web、モバイル、管理画面など、すべてのアプリケーションで一貫したデザインを実現できます。

 共有の依存関係管理Bunのcatalogを活用することで、複数のパッケージ間で共通の依存バージョンを定義できます。
package.json
{
  "name": "@mycompany/monorepo",
  "private": true,
  "workspaces": {
    "packages": ["apps/*", "packages/*", "configs/*"],
    "catalog": {
      "typescript": "^5.8.0",
      "zod": "^3.25.0"
    },
    "catalogs": {
      // カテゴリ別にグループ化
      "react": {
        "react": "^19.0.0",
        "react-dom": "^19.0.0",
        "@types/react": "^19.0.0",
        "@types/react-dom": "^19.0.0"
      },
      "testing": {
        "vitest": "^3.2.0",
        "@vitest/coverage-istanbul": "^3.2.0",
        "@vitest/ui": "^3.2.0"
      }
    }
  }
}
apps/mobile/package.json
{
  "name": "@apps/mobile",
  "dependencies": {
    "react": "catalog:react",
    "zod": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "@types/react": "catalog:react",
    "vitest": "catalog:testing",
    "@vitest/coverage-istanbul": "catalog:testing",
    "@vitest/ui": "catalog:testing"
  }
}

 Claude Code Tipsモノレポ構成では、CLAUDE.mdファイルを階層的に配置することで、各ディレクトリに特化した指示をAIに提供できます。

 CLAUDE.mdの階層的な読み込みClaude Codeは、現在の作業ディレクトリから上位ディレクトリに向かって、CLAUDE.mdファイルを再帰的に探索します。例えば、apps/mobile/で作業している場合、以下の順序で指示が読み込まれます。

/apps/mobile/CLAUDE.md - モバイルアプリ固有の指示

/CLAUDE.md - プロジェクト全体の共通ルール
また、サブディレクトリのCLAUDE.mdは、そのディレクトリ内のファイルを操作する時のみ読み込まれるため、不要なコンテキストの消費を防げます。
How Claude looks up memories

 まとめ開発の基盤となるアーキテクチャ設計の具体的な実践例として、AI開発におけるモノレポの有用性を解説しました。情報の一元管理、開発効率の向上、AIツールとの親和性など、実際の開発で感じているメリットをご紹介しました。
本記事内では紹介しきれませんでしたが、TypeScriptプロジェクトのモノレポ構築ではTurborepoの活用も有効です。各パッケージ間の依存関係を整理し、ビルドキャッシュによるCI/CDの高速化など、さらなる効率化も期待できます。初期設計には手間がかかりますが、AI時代の開発においては、アーキテクチャへの投資は長期的に見て価値があるものだと感じています。
株式会社LiacPublication
要約

前提

はじめに

モノレポ構成例と有用性

最新コンテキストを保った開発環境

開発生産性の向上

認知負荷の低減

具体例

単一コマンドでの開発環境構築

コード品質の標準化

デザインシステムの実現

共有の依存関係管理

Claude Code Tips

CLAUDE.mdの階層的な読み込み

まとめ

Discussion
