開発手法ガイド：モノレポ編 — AI に渡すコンテキストを設計する

🤖 AI 駆動開発でモノレポが重要な理由

AI コーディングツールに渡せるコンテキストには限りがある。巨大なリポジトリで「この機能を追加して」と指示しても、AI が無関係なファイルを読み込んで的外れな提案を返す。逆にポリレポ（複数リポジトリ）だと、横断リファクタリングで AI の射程が足りない。

モノレポ戦略は、 AI に渡すコンテキストの範囲を構造で設計する ことに直結する。AI 駆動開発での効用は 3 つ。

本記事は開発手法ガイド：概要のシリーズ 11 本目（最終回）。モノレポの本質、2025 年のツール比較、AI 駆動開発での活かし方を整理します。

🤝 モノレポの最大の威力 — フロントエンド + バックエンド同時開発

モノレポを採用する 最大の価値 は、 フロントエンドとバックエンドを同じリポジトリで同時に開発できる ことです。ポリレポでは数日かかる「API 変更 + フロント追従」が、モノレポなら 1 PR で完結 します。

ポリレポでの「面倒くささ」

1. バックエンド側で API スキーマを変更
2. バック リポジトリで PR レビュー → マージ
3. バックを dev 環境にデプロイ
4. フロント リポジトリで API 型を再生成（or 手動で書き換え）
5. フロント側のコードを修正
6. フロント PR レビュー → マージ
7. 統合テストで初めて齟齬発覚 → 1 に戻る

→ 小さな変更でも数日かかる 。「型のズレ」「契約のズレ」が常に発生し、誰かが手作業で吸収する。

モノレポなら 1 PR で完結

1 PR の中で:
  backend/apps/api 側のスキーマ変更
  shared/api-types の型を更新（自動生成 or 手動）
  frontend/apps/web 側の呼び出しコードを修正
  ↓
  ローカルで型エラーが即出る → 修正
  ↓
  CI で全関連テストが実行される → 通れば安心
  ↓
  1 PR をレビュー → マージ → 全部反映

「整合性が崩れたまま誰かがレビューする」事故が構造的に起きない 。これがモノレポの真価。

共有できる代表例（shared/ 配下）

AI 駆動開発との相性 — 「最高！」と言える理由

フロント + バック同時開発は AI 駆動開発で特に威力を発揮 します。

AI への指示テンプレート

タスク: 注文に「優先配送フラグ」を追加
変更対象:
  - backend/apps/api      : Order エンティティに priorityShipping フィールド追加
  - shared/api-types      : 型定義を更新
  - shared/validation     : Zod スキーマに boolean を追加
  - frontend/apps/web     : 注文画面にチェックボックス追加、送信時に値を含める

完了条件:
  - 型エラーがゼロ
  - backend / frontend 両方の単体テストがパス
  - E2E テスト「注文に優先フラグを付けて確定」が通る

このような 「フロント・バック横断タスク」を 1 指示で完結 させられるのは、モノレポ + AI 駆動開発の組み合わせならでは。これがモノレポを採用する 最大の動機 です。

よくある失敗

🦸 モノレポ × AI 駆動開発で「個人開発の天井」が外れる

これまで 「フロント + バック + 認証 + 決済 + DB + デプロイ」を一人で回すのは現実的ではない とされてきました。複数リポジトリを切り替え、複数ドメインの言語を切り替え、複数の依存管理を回す認知コストが、個人の限界を超えるからです。

モノレポ + AI 駆動開発の組み合わせは、この前提を破壊します。

一人で大規模 SaaS を立ち上げる時代が、現実に始まっています。

個人開発で SaaS が成立する条件

一人 SaaS の現実例

一人 SaaS 向けスタック選定の現実解（2025 年）

これらを 1 つのモノレポに収め、AI に横断作業を任せる ことで、これまで 5〜10 人チームが必要だった規模を一人で回せます。

🌍 Terraform IaC でインフラ構築も一人で

GUI でクラウドコンソールをポチポチ操作する時代は終わりつつあります。 Terraform IaC（Infrastructure as Code） を使えば、 VPC / データベース / WAF / CDN / 監視 / CI/CD まで、すべてコードで定義 でき、これも 一人で全環境を構築・運用可能 です。

モノレポに IaC を同居させる

.
├── frontend/
├── backend/
├── shared/
├── infrastructure/             ★ Terraform IaC をここに
│   ├── modules/                — 再利用可能なモジュール
│   ├── envs/
│   │   ├── dev/
│   │   ├── staging/
│   │   └── prod/
│   └── README.md
└── ...

インフラもモノレポの一部 にすることで、 アプリ変更とインフラ変更を同じ PR で扱える 。例: 新機能で外部 API を呼び出す → IAM ロール追加が同じ PR で完結する。

AI 駆動開発との接続

AI への指示テンプレート:
  - apps/api に Cognito 連携を追加（バックエンド側コード）
  - shared/api-types に認証型を追加
  - infrastructure/modules/cognito を新設
  - infrastructure/envs/{dev,prod}/main.tf で呼び出し
  
完了条件:
  - terraform plan で差分が予期通り
  - apps/api の認証テストが通る
  - フロント側の認証フローが動く

アプリ + インフラを横断する変更を 1 PR・1 セッション で完結できます。これが「一人で SaaS を回せる」という主張の現実的な裏付けです。

詳細は Terraform IaC 実践ガイド および Terraform IaC 準備編 で解説しています。

開発の流れも変わる

従来（一人開発の限界）:
  バック実装 → デプロイ → フロント着手 → 型ズレ修正 → ...
  (1 機能 = 数日、コンテキストスイッチで疲弊)

モノレポ × AI 駆動開発:
  AI に「機能 X を frontend / backend / shared 横断で実装」と指示
    ↓
  AI が3層全てに変更を生成
    ↓
  Turborepo affected で関連テスト全実行
    ↓
  1 PR でレビュー → マージ → デプロイ
  (1 機能 = 数時間、認知負荷は 1 機能分)

ただし「一人で全部」には限界もある

「一人で SaaS」は エンジニアリングの限界が下がった だけで、 事業運営 には別のスキルセットが必要。それでも、 エンジニア一人で「動く事業」を持てる時代 が始まったのは大きな変化です。

始め方

1. 小さく始める — apps/web + apps/api + shared/api-types の 3 パッケージ
2. shared を SSoT にする — 型・バリデーション・用語をフロント・バックで共有
3. AI に横断指示を出す — 「機能 X を 3 層横断で実装して」
4. CI を最初から整える — Turborepo affected + Vercel デプロイで秒速サイクル
5. 計測してから拡張 — ユーザーが付いたら、必要な領域だけ磨き込む

モノレポは「個人エンジニアが SaaS で生きる」ためのインフラになりつつある。

📜 モノレポ vs ポリレポ

定義

Google・Meta・Twitter など巨大テック企業の多くがモノレポを採用することで広まった。

トレードオフ

中小規模ではモノレポが有利 、超巨大組織でのみポリレポの権限管理が効いてくる。

🛠️ 2025 年の主要ツール比較

AI 駆動開発で使える現実的な選択肢は 3 つ。

pnpm workspaces

依存管理の基盤層。 他のツールと組み合わせて使う のが前提。

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'libs/*'

• 最速のパッケージインストール（node_modules の hoisting を最小化）
• 依存関係が厳密（phantom dependency を防ぐ）
• タスクオーケストレーション機能はない（pnpm -r run だけ）

Turborepo

pnpm workspaces に task runner をかぶせる のが典型構成。

// turbo.json
{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "test":  { "dependsOn": ["^build"], "outputs": [] }
  }
}

• 10 分で既存モノレポに追加可能 — 既存の package.json スクリプトをそのまま使える
• ローカルキャッシュ + Remote Cache（Vercel インフラ）
• Architecture ルール・generator は提供しない（モジュール境界チェックは別途）

Nx

フル機能のモノレポプラットフォーム 。

// nx.json
{
  "targetDefaults": {
    "build": { "dependsOn": ["^build"], "cache": true }
  }
}

• nx g @nx/react:component Button --project=ui のような generator
• implicitDependencies / tags によるモジュール境界制御
• 依存グラフ可視化（nx graph）
• Nx Cloud で Remote Cache + 分散 CI 実行

2025 年の現実解

「まず pnpm + Turborepo で始めて、規模が大きくなったら Nx に移行」がよくあるパス。

🏗️ AI 駆動開発向けのリポジトリ構造

典型的な配置 — frontend / backend / shared の 3 軸

.
├── frontend/                       （フロントエンド全体）
│   ├── apps/
│   │   ├── web/                   — エンドユーザー向けサイト
│   │   └── admin/                 — 管理画面
│   └── libs/
│       ├── ui/                    — Atom / Molecule / Organism
│       ├── data-access/           — API クライアント
│       └── feature-checkout/      — 機能単位ライブラリ
│
├── backend/                        （バックエンド全体）
│   ├── apps/
│   │   ├── api/                   — REST / GraphQL API
│   │   └── batch/                 — バッチ・Saga ワーカー
│   └── libs/
│       ├── domain/                — エンティティ・集約・ドメインサービス
│       ├── persistence/           — リポジトリ実装
│       └── messaging/             — イベント / Saga 基盤
│
├── shared/                         （フロント・バック共通）★最重要
│   ├── api-types/                 — OpenAPI / tRPC / GraphQL 由来の型
│   ├── validation/                — Zod スキーマ（両側で同じルール）
│   ├── constants/                 — ステータスコード・enum
│   └── domain-language/           — ユビキタス言語（Bounded Context 別）
│
├── tools/                          （ビルド・デプロイスクリプト）
├── docs/                           — ドキュメント
├── .claude/                        — Claude Code 設定
│   ├── CLAUDE.md                  — プロジェクト憲法
│   └── commands/                  — スラッシュコマンド
├── package.json
├── pnpm-workspace.yaml
└── turbo.json / nx.json

この構造のポイント

AI 駆動開発を意識した原則

🚀 差分ビルド / リモートキャッシュが AI 駆動開発を加速

モノレポの最大のレバレッジは affected-only execution と remote caching 。

Affected-only Execution

変更されたパッケージだけをビルド・テスト。

apps/web の変更
  ↓
依存している libs/ui をビルド
  ↓
apps/web をビルド
  ↓
libs/domain（変更と無関係）はスキップ

45 パッケージあっても、影響する 4 パッケージだけを実行できる。AI が小さな変更を連続で出すサイクルに超強い。

Remote Caching

チーム全員で CI のキャッシュを共有。

Alice が feature-X をビルド → キャッシュが Remote に保存
  ↓
Bob が同じ feature-X を pull → キャッシュから復元（ビルドしない）
  ↓
AI が同じブランチで再実行 → キャッシュから復元

Remote caching は ローカルキャッシュの 10 倍以上のレバレッジ がある。CI 時間が大幅短縮されるため、AI が小刻みに PR を作るワークフローが現実的になる。

🎯 AI への指示にモノレポを組み込む

指示テンプレート

パッケージ: {libs/ui / apps/web / ...}
タスク: {機能追加・変更内容}
依存可能: {import できるパッケージ}
依存禁止: {import してはいけないパッケージ}
テスト: {同パッケージ内で完結 yes/no}

例：

パッケージ: libs/ui
タスク: DatePicker コンポーネントを追加
依存可能: libs/tokens（Design Tokens）
依存禁止: libs/domain, libs/data-access, apps/*
テスト: libs/ui 内で完結。Storybook ストーリーも追加

パッケージ境界を明示することで、AI が不要な横断修正を提案するのを防げる。

CLAUDE.md をパッケージ別に配置

libs/ui/CLAUDE.md:
  このパッケージは UI コンポーネントのみ。
  - API 呼び出し・グローバル状態を含めない
  - libs/tokens だけに依存可
  - Storybook ストーリー必須

libs/domain/CLAUDE.md:
  このパッケージはビジネスロジックのみ。
  - フレームワーク・UI ライブラリに依存しない
  - 集約・値オブジェクト・ユビキタス言語を使う
  - 単体テスト必須

パッケージ単位の CLAUDE.md があると、AI が そのパッケージの文脈 で作業できる。

⚠️ モノレポ採用時のアンチパターン

1. 巨大化してキャッシュが効かない

apps/web と apps/api の CI を 1 つの script で実行し、変更がない側もビルドされる。

是正: Turborepo / Nx の affected-only execution を必ず使う。GitHub Actions のパスフィルタも併用。

2. 共通化しすぎて libs が不安定化

「似ている」だけで無理矢理 libs/common に置き、複数の apps から参照されて変更できなくなる。

是正: 早すぎる共通化は禁物 。3 回以上重複してから抽象化を検討。Duplicate is cheaper than wrong abstraction。

3. 依存グラフの腐敗

循環依存・scope 違反が蓄積し、どのパッケージも単体で動かない。

是正: Nx の tags / Turborepo 用 ESLint ルールでモジュール境界を lint で強制 。

4. パッケージ粒度が細かすぎる

1 ファイル 1 パッケージの状態になり、オーバーヘッドだけ増える。

是正: 1 パッケージは単一責務で、数ファイル〜数十ファイル規模 を目安に。

5. Remote Cache を使わない

CI の時間が長いのに Remote Cache を入れず、AI の試行回数が制限される。

是正: Turborepo なら Vercel Remote Cache（無料枠あり）、Nx なら Nx Cloud を早期導入。

🧩 AI 駆動開発でのモノレポ戦略

フェーズ別の進化

AI 駆動開発で高速にプロトタイプを出すフェーズでは pnpm workspaces + Turborepo が最小コストで最大効果。規律が必要になってから Nx への移行を検討。

AI との相性が良いポイント

• パッケージ単位でコンテキストを切れる — cd libs/ui && claude のような使い方
• 変更影響の可視化 — nx graph で AI の提案が波及する範囲を事前確認
• 差分ビルドで検証が速い — AI の提案を即座に検証できる

📚 まとめ

• モノレポは AI に渡すコンテキストの範囲を構造で設計する 手段
• 最大の威力は「フロント + バック同時開発」 。API 変更とフロント追従が 1 PR で完結する
• 共有: API 型 / ドメイン語彙 / バリデーション / ユーティリティ / 定数 — フロント・バックで二重定義しない
• モノレポ × AI 駆動開発で「個人開発の天井」が外れる 。エンジニア一人で動く SaaS を持てる時代に
• 2025 年の現実解: 中小規模は pnpm workspaces + Turborepo、大規模は Nx
• affected-only execution と remote caching が最大のレバレッジ
• パッケージ別の CLAUDE.md で AI に適切なコンテキストを渡す
• 早すぎる共通化は禁物。循環依存・scope 違反は lint で強制
• 立ち上げは軽量に、必要になってから Nx 等へ移行する段階的アプローチ

🔗 関連記事

• 開発手法ガイド：概要 — シリーズ全体の位置づけ
• 開発手法ガイド：DDD 編 — Bounded Context とパッケージ境界の対応
• 開発手法ガイド：アトミックデザイン編 — UI ライブラリのパッケージ化
• ステアリング駆動開発 — AI 駆動開発の運用フロー
• Claude Code + Claude Design 連携ワークフロー — モノレポ内で Claude を使う

📖 関連用語

• コンテキストエンジニアリング — AI に渡すコンテキストの設計
• Storybook — libs/ui/ パッケージのカタログ基盤
• オブザーバビリティ — 一人 SaaS の本番運用を支える監視基盤
• SSoT — モノレポで SSoT を保つ前提
• Astro — apps 層のフレームワーク例

📎 参考資料

• Monorepo Strategy Guide 2025: Nx vs Turborepo vs Lerna
• Monorepo in 2026: Turborepo vs Nx vs Bazel
• Nx vs. Turborepo — DEV Community
• pnpm Workspaces
• Turborepo Documentation
• Nx Documentation