ワークスペースとモノレポ

モノレポ、複数パッケージのワークスペース、独立したサブディレクトリを持つプロジェクト向けにDevinの環境を設定します。

モノレポと複数パッケージのワークスペースでは、サブディレクトリごとに異なる言語、パッケージマネージャー、依存関係の構成を利用する場合があるため、ブループリントで追加の考慮が必要です。Devin は 2 つの方法をサポートしています。

ネイティブワークスペース（推奨）

サブディレクトリごとに個別のブループリントを作成します。各ワークスペースにはそれぞれ専用の initialize、maintenance、Knowledge セクションがあり、作業ディレクトリは自動的にそのサブディレクトリに設定されます。

サブシェル

1 つのブループリント内で (cd dir && command) を使ってサブディレクトリでコマンドを実行します。パッケージ数が少ない小規模なモノレポでは、こちらのほうがシンプルです。

---

ネイティブワークスペース

ほとんどのモノレポに推奨されます。 ネイティブワークスペースでは、各サブディレクトリに、セットアップ、Knowledge、作業ディレクトリが分離された専用のブループリントが用意されます。パッケージ数が増えても、サブシェルを使うより整理しやすく、保守も簡単です。

ネイティブワークスペースでは、各サブディレクトリに専用のブループリントが割り当てられます。そのブループリント内のコマンドは、作業ディレクトリがあらかじめそのサブディレクトリに設定された状態で実行されるため、cd やサブシェルは不要です。

ルートブループリント

ネイティブワークスペースを利用するすべてのリポジトリでは、ルートブループリントが必要です。ルートブループリントはリポジトリルートから実行され、ワークスペース単位のブループリントより前に実行されます。これは、実行環境やグローバルツールのインストール、ルートレベルでの依存関係のインストールなど、リポジトリ全体に共通するセットアップに利用します。

# ルートブループリント — リポジトリのルートから最初に実行される
initialize: |
  npm install -g pnpm

maintenance: |
  pnpm install

その後、ワークスペースのブループリントがパッケージごとのセットアップを処理し、ルートブループリントの完了後に実行されます。

ワークスペースの作成

1. Settings > Environment > Blueprints に移動します
2. リポジトリをクリックします
3. Add workspace をクリックします
4. サブディレクトリのパス (例: packages/frontend) を入力します
5. そのワークスペース用のブループリントを記述します

ワークスペースのパスは、リポジトリ内に実在するディレクトリに対応している必要があります。ビルド実行時にそのパスが存在しない場合、ビルドは失敗します。パスがリポジトリの構成と完全に一致していることを必ず確認してください (例: packages/frontend であり、pkg/frontend ではありません) 。

例

React のフロントエンドと Python のバックエンドを含むモノレポです。ルートブループリントで共有ツールをインストールし、その後は各ワークスペースがそれぞれの依存関係を管理します。

ルート

# ルートブループリント — リポジトリ全体に共通のセットアップ
initialize: |
  npm install -g pnpm
  curl -LsSf https://astral.sh/uv/install.sh | sh

knowledge:
  - name: structure
    contents: |
      Monorepo with two packages:
      - packages/frontend — React app (TypeScript, pnpm)
      - packages/backend — Python API (FastAPI, uv)

packages/frontend

# packages/frontend にスコープされたワークスペース
maintenance: |
  pnpm install

knowledge:
  - name: lint
    contents: pnpm lint
  - name: test
    contents: pnpm test
  - name: dev
    contents: pnpm dev

packages/backend

# packages/backend にスコープされたワークスペース
maintenance: |
  uv sync

knowledge:
  - name: lint
    contents: uv run ruff check .
  - name: test
    contents: uv run pytest
  - name: dev
    contents: uv run uvicorn app.main:app --reload

各ワークスペースの knowledge エントリは、そのサブディレクトリにスコープされています。Devin が packages/frontend で作業しているときは、バックエンド用ではなく、フロントエンドの lint/test/dev コマンドを参照します。

ネイティブワークスペースを利用する場面

• サブディレクトリごとに使用する言語やパッケージマネージャーが異なる
• 各パッケージごとに専用のKnowledge エントリ (lint、テスト、ビルドコマンド) が必要
• セットアップを分離したい — 1 つのワークスペースのブループリントが壊れていても、ほかのワークスペースには影響しない
• パッケージ数が増えており、単一のブループリントでは管理しづらくなっている

---

サブシェル

比較的シンプルなモノレポであれば、サブシェルを使って単一のブループリント内ですべてを管理できます。後続の手順に影響を与えずにサブディレクトリでコマンドを実行するには、コマンドを丸括弧で囲みます。

maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)

括弧 (cd ... && ...) はサブシェルを作成します。サブシェルを終了すると、作業ディレクトリは次のステップに向けてリポジトリのルートに戻ります。

括弧がない場合、cd はそれ以降のすべてのステップの作業ディレクトリを変更します。ブループリントのステップでディレクトリを切り替えるときは、必ずサブシェルを利用してください。

サブシェル が重要な理由

以下の 2 つの方法を比較してください。

正しい例（サブシェル あり）

maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)

各ステップはリポジトリのルートから実行されます。そのため、どちらのコマンドも正しい packages/ サブディレクトリを参照できます。

誤った例（サブシェル なし）

maintenance:
  - name: Frontend deps
    run: cd packages/frontend && pnpm install
  - name: Backend deps
    run: cd packages/backend && uv sync

最初のステップで作業ディレクトリが packages/frontend に変わります。すると 2 つ目のステップでは、packages/frontend からの相対パスとして cd packages/backend を実行しようとするため、失敗します。

subshellsを利用するケース

• モノレポ内のパッケージ数が少なく、セットアップがシンプル
• すべてのパッケージで同じ言語とパッケージマネージャーを使っている
• パッケージごとのKnowledgeエントリは不要

---

モノレポ向けのKnowledgeエントリ

ネイティブ ワークスペースとサブシェルのどちらを利用する場合でも、適切に構成されたKnowledgeエントリがあれば、Devinはコードベースを把握しやすくなります。

knowledge:
  - name: structure
    contents: |
      This is a monorepo with three packages:
      - `packages/frontend` — React app (TypeScript, pnpm)
      - `packages/backend` — Python API (FastAPI, uv)
      - `packages/shared` — Shared TypeScript utilities
  - name: frontend
    contents: |
      cd packages/frontend
      Dev server: pnpm dev
      Lint: pnpm lint
      Test: pnpm test
  - name: backend
    contents: |
      cd packages/backend
      Dev server: uv run uvicorn app.main:app --reload
      Lint: uv run ruff check .
      Test: uv run pytest

各ディレクトリをその使用言語とツールチェーンに対応付ける structure の Knowledge エントリがあると、Devin は repo 内をすばやく把握できます。ネイティブ ワークスペースでは、各ワークスペースがそれぞれ独自の Knowledge エントリを持つため、structure エントリが特に有用なのは、ルートのブループリント内、またはサブシェルベースのセットアップです。

使用例

Turborepo / Nx ワークスペース

Turborepo や Nx のようなモノレポ向けビルドツールで管理されるワークスペースでは、依存関係をルートにインストールし、パッケージごとの処理はツールに任せます。

initialize: |
  npm install -g pnpm turbo

maintenance: |
  pnpm install

knowledge:
  - name: structure
    contents: |
      Turborepo monorepo. Use `turbo` for building and testing:
      - `apps/web` — Next.js app
      - `apps/api` — Express API
      - `packages/ui` — Shared component library
      - `packages/config` — Shared configuration
  - name: build
    contents: turbo run build
  - name: test
    contents: turbo run test
  - name: lint
    contents: turbo run lint
  - name: dev
    contents: turbo run dev

複数のJDKバージョン

サービスごとに必要なJDKバージョンが異なるJavaモノレポ:

initialize:
  - name: Install JDK 17 (primary)
    run: |
      sudo apt-get update -qq
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-17-jdk-headless
      echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64' \
        | sudo tee /etc/profile.d/java.sh > /dev/null

  - name: Install JDK 11 (legacy service)
    run: |
      sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq openjdk-11-jdk-headless

maintenance:
  - name: Warm dependency caches
    run: |
      export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
      (cd services/api && ./gradlew dependencies --refresh-dependencies)

      export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
      (cd services/legacy && ./gradlew dependencies --refresh-dependencies)

knowledge:
  - name: build_api
    contents: |
      Build the API service (JDK 17):
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        cd services/api && ./gradlew clean build
  - name: build_legacy
    contents: |
      Build the legacy service (JDK 11):
        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        cd services/legacy && ./gradlew clean build
  - name: test_all
    contents: |
      Run tests for all services:
        JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
        (cd services/api && ./gradlew test)

        JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 \
        (cd services/legacy && ./gradlew test)

共有ツール向けの org ブループリント

モノレポ内の複数のパッケージで同じツールを共有する場合は、org-wide ブループリントに一度だけインストールします。

# 組織全体のブループリント（Settings > Environment > Blueprints > Org-wide setup）
initialize:
  - name: Install pnpm
    run: npm install -g pnpm
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install shared build tools
    run: npm install -g turbo typescript

すると、各repo ブループリントで必要になるのはプロジェクト固有のコマンドだけです:

# repo ブループリント（org ブループリントの pnpm と uv を利用）
maintenance:
  - name: Install all workspace deps
    run: pnpm install
  - name: Install Python service deps
    run: (cd services/ml-pipeline && uv sync)

ベストプラクティス

複雑なモノレポではネイティブワークスペースを優先する

各サブディレクトリで使用する言語、パッケージマネージャー、ビルドプロセスが異なる場合は、ネイティブワークスペースを使うことで各ブループリントを明確に切り分け、独立性を保てます。サブシェルは、少数のパッケージだけを扱うシンプルなケースに限って使用してください。

ディレクトリ変更には常にサブシェルを使用する

サブシェル方式を使う場合は、cd コマンドを括弧で囲んでください: (cd dir && command)。これにより、あるステップでのディレクトリ変更が次のステップに影響するのを防げます。

共有ツールは org ブループリントに置く

複数のリポジトリで使用する language runtimes や package managers は、org-wide ブループリントに含めるべきです。これにより重複を避けられ、repo ブループリントをプロジェクト固有のセットアップに集中させられます。

maintenance のステップは依存関係順に並べる

パッケージ A が、先にビルドされたパッケージ B に依存する場合は、maintenance で A のインストールステップより前に B のビルドステップを記載してください。Blueprint のステップは、記載された順に順次実行されます。

構造を示すナレッジエントリを追加する

ディレクトリと使用する言語・ツールの対応を示す structure という名前のナレッジエントリがあると、Devin がコードベースを把握しやすくなります。各サブディレクトリで使用する package manager と、パッケージ間の依存関係も含めてください。

パッケージごとのKnowledge エントリを使う

1 つの大きなKnowledge エントリにする代わりに、各パッケージごとに個別のエントリ (例: frontend、backend、ml-pipeline) を作成してください。ネイティブワークスペースでは、各ワークスペースに専用の knowledge セクションが組み込まれています。

maintenance は増分的に保つ

pnpm install --force ではなく pnpm install を、rm -rf .venv && uv sync ではなく uv sync を使ってください。増分更新のコマンドの方が、定期的な rebuild 時に高速です。

関連ページ

• 宣言型環境設定
• ブループリント リファレンス
• テンプレート ライブラリ — すぐに使えるモノレポテンプレートを収録