Summary
この文書の要点
- モノレポの判断軸は、変更の同時性、チーム規模、AIエージェントとの相性の3つです。
- 共有は型定義とAPIクライアントに限定し、境界のルールは最小限に絞ります。
- 開発環境はAPIをコンテナ、フロントをホストで動かすハイブリッド構成が実用的です。
- CIはパスフィルタで変更されたアプリだけをテストし、デプロイは独立させます。
リポジトリ分割か、モノレポか。判断軸は3つです。
リポジトリ戦略の議論では「マイクロサービスならポリレポ、密結合ならモノレポ」という単純化がされがちですが、実際の判断軸はもう少し具体的です。私たちは次の3点で判断しました。
1つ目は、変更の同時性です。LMSの機能追加では、APIのエンドポイント追加とフロントの画面実装がほぼ常にセットで発生します。ポリレポではこの変更が2つのプルリクエストに分かれ、レビューとマージの順序調整が必要になります。モノレポなら1つのPRで「APIとUIの変更が整合しているか」をレビューできます。
2つ目は、チーム規模です。数十人規模でチームがサービス単位に分かれているなら、リポジトリの境界はチームの境界に合わせるべきです。しかし少人数で全域を見る体制では、リポジトリを分ける管理コストが利点を上回ります。
3つ目は、AIエージェントとの相性です。Claude CodeのようなAIエージェントにタスクを任せる場合、エージェントが参照できるコンテキストは基本的に1リポジトリの範囲です。API仕様とフロント実装が同じリポジトリにあれば、エージェントは「APIのレスポンス型を変えたらフロントの該当コンポーネントも直す」という横断作業を1セッションで完結できます。
実際の構成を示します。
flares.jp2026リポジトリは、apps/api にLaravel 12 + PHP 8.2のバックエンド、apps/web にReact Router 7 + Vite 7のフロントエンドを配置し、ルートに docker-compose.yml、pnpm-workspace.yaml、AIエージェント設定を置いています。
pnpm workspaceの設定は最小限です。pnpm-workspace.yamlに apps/* を宣言し、ルートのpackage.jsonには全体横断のスクリプトだけを定義します。Laravel側はComposerで依存管理されるためpnpmの管理外ですが、apps/api にもpackage.jsonを置き、開発サーバー起動やテスト実行をpnpmスクリプト経由で統一的に呼べるようにしています。
「どのアプリでも pnpm dev で開発が始まる」という統一感は、人間だけでなくAIエージェントにとっても重要です。エージェントに「テストを実行して」と指示したとき、迷わず正しいコマンドに辿り着けるからです。
型の共有と境界の規律を最小限のルールで守ります。
モノレポの最大の誘惑は「何でも共有できてしまう」ことです。私たちは共有を型定義とAPIクライアントの2つに限定しています。
APIのレスポンス型はTypeScriptのinterfaceとして定義し、フロントのloader関数で使用します。Laravel側のAPIリソースと型定義の整合は、PlaywrightのE2EテストとAPIレスポンスのスキーマ検証で担保します。重要なのは、PHPとTypeScriptの間に自動的な型生成パイプラインを最初から作り込まないという判断です。エンドポイント数が少ない段階では、生成パイプラインの保守コストが手書きの修正コストを上回ります。エンドポイントが50を超えたあたりが導入の目安だと考えています。
ルールが少ないほど、守られます。
- apps/web から apps/api のコードを直接importしない。
- 共有するものはルート直下のpackagesに切り出す（必要になってから）。
開発環境は「APIはコンテナ、フロントはホスト」で組みます。
開発環境はDocker Composeで統一しています。MySQL、Laravelのアプリケーションコンテナ、必要に応じてメール検証用のMailpitを起動し、フロントのVite開発サーバーはホスト側で直接動かします。
フロントまでコンテナに入れない理由は、HMRの速度とファイル監視の安定性です。macOS上のDockerはファイルシステムのブリッジにコストがあり、node_modulesを含むフロント開発をコンテナ内で行うと体感速度が明確に落ちます。
新しいメンバー（あるいは新しいAIエージェントのセッション）が docker compose up と pnpm dev の2コマンドで開発を始められる状態を維持することが、構成選定より重要です。
リポジトリは1つでも、デプロイは独立させます。
フロントの変更でAPIの再デプロイが走る必要はありません。CIではパスフィルタを使い、apps/web の変更ではフロントのビルドとテストのみ、apps/api の変更ではLaravelのテストのみを実行します。両方に跨る変更では両方が走ります。
この設定により「モノレポ＝CIが遅い」という典型的な不満をほぼ回避できています。
運用して見えた注意点も共有します。
良いことばかりではありません。gitログの可読性、2つのパッケージマネージャの更新管理、リポジトリの肥大化には対策が必要です。
特にnode_modulesやビルド成果物の除外設定を怠ると、AIエージェントがコンテキストを読む際のノイズになります。.gitignoreだけでなく、エージェント向けの除外設定を明文化しておくことを推奨します。
- コミットメッセージの規約（scopeにweb/apiを明記）を守らないと履歴が追いにくくなる。
- pnpmとComposerの更新サイクルを管理し、Renovateなどの自動化は両対応にする。
- エージェント向けに「読むべきでないディレクトリ」を明文化する。
リポジトリ戦略は、変更のパターンとチームの形で選びます。
フロントとAPIを1リポジトリに収める判断は、「変更の同時性が高い」「少人数で全域を見る」「AIエージェントに横断作業を任せたい」という3条件が揃うなら合理的です。
逆に、チームがサービス単位に分かれている組織や、フロントとAPIのリリースサイクルが大きく異なるプロダクトでは、ポリレポの方が摩擦は少ないでしょう。リポジトリ戦略は流行ではなく、変更のパターンとチームの形に合わせて選ぶものです。
