Claude CodeとNx Workspaceで始めるモノレポ実装ガイド

Nx Workspaceは「大きなリポジトリ」ではなく境界を見える化する道具

Claude Codeに「モノレポを作って」とだけ頼むと、動くファイルは増えます。しかし初心者が本当に困るのは、作成直後ではなく数週間後です。apps/webの修正でapps/adminまで壊れるのか、共通UIをどこに置くべきか、CIで毎回すべてのテストを走らせるべきかが分からなくなります。

Nx Workspaceは、複数のアプリとライブラリを1つのリポジトリで扱いながら、依存関係、タスク、キャッシュ、影響範囲を管理するためのツールです。公式のNx mental modelでも、NxはProject Graph、Task Graph、affected、cacheを組み合わせてワークスペースを理解すると説明されています。初心者向けに言い換えると、Nxは「どの部品がどの部品に依存しているか」と「今回どこだけ確認すればよいか」を機械的に判断する足場です。

この記事では、Claude CodeをNxの自動生成係としてではなく、境界を説明し、設定をレビューし、検証コマンドまで出させる相棒として使います。公式リンクはNx create-nx-workspace、@nx/workspace generators、Nx affected、Setting up CI、Caching tasksを基準にします。

関連する背景は、Claude Codeモノレポ管理、pnpm workspace実装、CI/CDセットアップも合わせて読むとつながります。

---

先に決める: Nxを使うべき3つのユースケース

Nxは強力ですが、すべての個人開発に必要なわけではありません。1つのLPと小さなAPIだけなら、普通の単一リポジトリのほうが速いこともあります。Nxを入れる価値が出るのは、境界と検証コストが問題になり始めたときです。

1つ目のユースケースは、Webアプリ、管理画面、APIが同じ型やUIを共有するケースです。例えばapps/web、apps/admin、apps/api、libs/contracts、libs/uiを同じリポジトリに置くと、APIレスポンス型やボタン部品を同じPRで更新できます。

2つ目は、変更された範囲だけCIを走らせたいケースです。記事サイト、教材販売ページ、管理画面が同居していると、毎回全テストを走らせるのは遅すぎます。nx affected -t test buildを使えば、Git差分と依存グラフから影響があるプロジェクトだけを選べます。

3つ目は、Claude Codeに「どこを触ってよいか」を明確に渡したいケースです。libs/uiは画面部品、libs/contractsは型、libs/configは設定、apps/*は実行アプリと決めておくと、Claude Codeの提案が小さくなります。特に収益導線、問い合わせフォーム、決済前のCTAを含むサイトでは、変更範囲を説明できることがそのまま品質になります。

逆に、共有したいコードがほとんどない、チームが1人でCIも軽い、ディレクトリ境界をまだ説明できない場合は、先にリポジトリ地図の作り方で現状を整理してください。Nxは整理済みの構造を速くする道具であり、未整理の構造を自動で正しくしてくれる魔法ではありません。

---

完成形: 初心者向けの小さなNx Workspace

この記事では、Reactの顧客画面、Node API、共有UI、API契約、共有設定の5プロジェクトに絞ります。最初から巨大なlibs/sharedを作らないのが重要です。

flowchart LR
  web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
  admin["apps/admin\nReact + Vite"] --> ui
  web --> contracts["libs/contracts\nAPI types"]
  admin --> contracts
  api["apps/api\nNode API"] --> contracts
  web --> config["libs/config\nlint/test config"]
  api --> config

境界の意味は単純です。apps/*は起動・デプロイする単位、libs/*は再利用する部品です。libs/*からapps/*へ依存してはいけません。libs/uiにAPI通信を書かず、libs/contractsにReactコンポーネントを書かないようにします。

Claude Codeには、最初にこの境界を読ませます。

このNx Workspaceを初心者にも説明できる形で設計してください。

守る境界:
- apps/web と apps/admin は画面アプリ
- apps/api はAPI
- libs/ui は見た目だけのUI部品
- libs/contracts はAPIの型とZod schema
- libs/config はESLint、Vitest、TypeScript設定
- libs/* から apps/* へ依存しない

作業前に nx graph で依存関係を確認し、変更後は nx affected で検証コマンドを出してください。

このプロンプトの狙いは、Claude Codeに「実装して」ではなく「境界を守って実装して」と伝えることです。境界を先に渡すだけで、不要な共通化や横断修正がかなり減ります。

---

セットアップ: コピペで動く最小コマンド

Node.js 20以上とGitが入っている前提です。公式のcreate-nx-workspaceは対話式でも使えますが、記事では再現性を優先してオプションを明示します。

npx create-nx-workspace@latest acme-nx \
  --workspaceType=integrated \
  --preset=apps \
  --packageManager=pnpm \
  --nxCloud=skip \
  --interactive=false

cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node

ReactアプリとNode API、共有ライブラリを作ります。Nxのジェネレーターは、ファイルだけでなくproject.jsonやtsconfigも一貫して更新してくれるため、Claude Codeが手作業で構成をばらつかせにくくなります。

pnpm nx g @nx/react:app web \
  --directory=apps/web \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=playwright \
  --style=css

pnpm nx g @nx/react:app admin \
  --directory=apps/admin \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=none \
  --style=css

pnpm nx g @nx/node:app api \
  --directory=apps/api \
  --unitTestRunner=vitest

pnpm nx g @nx/react:lib ui \
  --directory=libs/ui \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib contracts \
  --directory=libs/contracts \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib config \
  --directory=libs/config \
  --unitTestRunner=none

生成後は、まずグラフを見ます。

pnpm nx graph
pnpm nx show projects
pnpm nx show project web

nx graphはブラウザで依存関係を可視化します。初心者はここで「思ったより線が多い」と感じたら、共通化しすぎのサインとして扱ってください。

---

project.jsonを読む: Nxで迷わないための最重要ファイル

Nxでは各プロジェクトのタスクをproject.jsonまたはpackage.jsonで表します。初心者はまずproject.jsonを「このプロジェクトで実行できる仕事一覧」と読むと理解しやすいです。

{
  "name": "web",
  "sourceRoot": "apps/web/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web"
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "passWithNoTests": true
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {
        "buildTarget": "web:build"
      }
    }
  },
  "tags": ["scope:app", "type:web"]
}

Claude Codeには、project.jsonを編集させる前に次のように聞くと安全です。

apps/web/project.json を読んで、build/test/serve の役割を初心者向けに説明してください。
その後、変更が必要なら差分だけ提案してください。
outputs、cache、dependsOn を壊さないでください。

outputsはキャッシュ対象の出力場所です。ここが間違うと、ビルドは成功しているのにキャッシュが効かない、古い成果物が再利用される、CIでだけ失敗する、といった分かりにくい問題になります。

---

affectedをCIに入れる: 全部走らせない勇気

Nxの価値が一番見えやすいのはaffectedです。affectedは、変更されたファイルと依存グラフを見て、影響を受けるプロジェクトだけにタスクを実行します。

ローカルでは次のように試します。

pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD

GitHub Actionsでは、履歴が浅いと差分比較に失敗しやすいのでfetch-depth: 0を入れます。Nx公式のCIセットアップでは、Nxコマンドを通してタスクを実行することが重要です。jestやeslintを直接呼ぶと、Nxのキャッシュやaffectedの恩恵を受けられません。

name: nx-ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3

有料・チーム運用ではNx Cloudのリモートキャッシュも検討できます。まずはローカルキャッシュとaffectedで十分に効果を確認し、CI時間がボトルネックになってから導入するほうが、初心者には判断しやすいです。

---

よくある失敗とClaude Codeへの止め方

失敗1は、libs/sharedに何でも入れることです。便利に見えますが、数か月後には削れない依存の山になります。Claude Codeには「sharedを作る前に、UI、型、設定、純粋関数のどれに分類できるか説明して」と要求してください。

失敗2は、libs/*からapps/*をimportすることです。これは境界の逆流です。UIライブラリがapps/webのルーティングや環境変数を読んだ瞬間、再利用できる部品ではなくなります。

失敗3は、CIでpnpm testやvitestを直接走らせることです。Nxのグラフ外で実行すると、キャッシュ、affected、タスク依存が効きません。CIではpnpm nx run-many -t testまたはpnpm nx affected -t testに寄せます。

失敗4は、最初から大きすぎるモノレポにすることです。アプリが2つしかないのにlibs/auth、libs/domain、libs/data-access、libs/feature-*を量産すると、初心者は機能追加よりフォルダ選びに時間を使います。最初はui、contracts、configで十分です。

失敗5は、Claude Codeにグラフを見せずに修正させることです。作業前にpnpm nx graph、作業後にpnpm nx affected -t test buildを必ずセットにしてください。

---

収益化導線としてのNx: 壊したくないページを守る

ClaudeCodeLabのような記事サイトでは、実装記事、教材ページ、問い合わせ、無料チェックリスト、トレーニング案内が同じリポジトリに入ることがあります。ここでNxを使う価値は、ビルドが速いことだけではありません。収益につながるページと実験中の機能を境界で分け、影響範囲をレビューできることです。

例えば、apps/siteは公開記事、apps/adminは下書き管理、libs/ctaはCTA部品、libs/analyticsはイベント送信に分けます。CTA文言や計測イベントを変更したPRでは、nx affectedの結果を貼るだけで「どのページが確認対象か」を説明できます。これはAdSense、アフィリエイト、相談フォームのような収益導線を持つサイトで特に効きます。

チームでClaude Code導入やモノレポ設計を標準化したい場合は、ClaudeCodeLabのトレーニングも用意しています。個人で試す場合は、まずこの記事のコマンドを小さな検証リポジトリで実行し、nx graphのスクリーンショットを残すところから始めてください。

---

この記事で紹介した内容を実際に試した結果

Masaとして検証したときは、最初にweb、admin、api、ui、contractsだけを作り、nx graphで依存線を確認しました。その後、libs/contractsの型を1つ変更してpnpm nx affected -t test build --base=main --head=HEADを実行すると、contractsに依存するアプリだけが対象になり、libs/uiだけの変更ではAPI側のビルドが対象外になることを確認できました。初心者にとって一番大きな気づきは、Nxの設定を暗記することではなく、グラフで境界を見てからClaude Codeに作業させると、レビューできる変更に収まるという点でした。

まとめ

Nx Workspaceは、モノレポを大きくするための道具ではありません。依存関係を見える化し、変更範囲だけを検証し、Claude Codeに守るべき境界を渡すための道具です。

最初は小さく作り、project.jsonを読み、nx graphで線を確認し、nx affectedをCIに入れてください。そこまでできれば、Claude Codeは単なるコード生成ツールではなく、モノレポの構造を保つレビュー役として働きます。