> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

<CardGroup cols={2}>
  <Card title="ネイティブワークスペース（推奨）" icon="cubes" href="#native-workspaces">
    サブディレクトリごとに個別のブループリントを作成します。各ワークスペースにはそれぞれ専用の initialize、maintenance、Knowledge セクションがあり、作業ディレクトリは自動的にそのサブディレクトリに設定されます。
  </Card>

  <Card title="サブシェル" icon="terminal" href="#subshells">
    1 つのブループリント内で `(cd dir && command)` を使ってサブディレクトリでコマンドを実行します。パッケージ数が少ない小規模なモノレポでは、こちらのほうがシンプルです。
  </Card>
</CardGroup>

***

<div id="native-workspaces">
  ## ネイティブワークスペース
</div>

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

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

<div id="the-root-blueprint">
  ### ルートブループリント
</div>

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

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

maintenance: |
  pnpm install
```

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

<div id="creating-a-workspace">
  ### ワークスペースの作成
</div>

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

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

<div id="example">
  ### 例
</div>

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

<Tabs>
  <Tab title="ルート">
    ```yaml theme={null}
    # ルートブループリント — リポジトリ全体に共通のセットアップ
    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)
    ```
  </Tab>

  <Tab title="packages/frontend">
    ```yaml theme={null}
    # packages/frontend にスコープされたワークスペース
    maintenance: |
      pnpm install

    knowledge:
      - name: lint
        contents: pnpm lint
      - name: test
        contents: pnpm test
      - name: dev
        contents: pnpm dev
    ```
  </Tab>

  <Tab title="packages/backend">
    ```yaml theme={null}
    # 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
    ```
  </Tab>
</Tabs>

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

<div id="when-to-use-native-workspaces">
  ### ネイティブワークスペースを利用する場面
</div>

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

***

<div id="subshells">
  ## サブシェル
</div>

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

```yaml theme={null}
maintenance:
  - name: Frontend deps
    run: (cd packages/frontend && pnpm install)
  - name: Backend deps
    run: (cd packages/backend && uv sync)
```

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

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

<div id="why-subshells-matter">
  ### サブシェル が重要な理由
</div>

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

<Tabs>
  <Tab title="正しい例（サブシェル あり）">
    ```yaml theme={null}
    maintenance:
      - name: Frontend deps
        run: (cd packages/frontend && pnpm install)
      - name: Backend deps
        run: (cd packages/backend && uv sync)
    ```

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

  <Tab title="誤った例（サブシェル なし）">
    ```yaml theme={null}
    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` を実行しようとするため、失敗します。
  </Tab>
</Tabs>

<div id="when-to-use-subshells">
  ### subshellsを利用するケース
</div>

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

***

<div id="knowledge-entries-for-monorepos">
  ## モノレポ向けのKnowledgeエントリ
</div>

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

```yaml theme={null}
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
```

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

<div id="examples">
  ## 使用例
</div>

<div id="turborepo-nx-workspace">
  ### Turborepo / Nx ワークスペース
</div>

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

```yaml theme={null}
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
```

<div id="multiple-jdk-versions">
  ### 複数のJDKバージョン
</div>

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

```yaml theme={null}
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)
```

<div id="org-blueprint-for-shared-tools">
  ### 共有ツール向けの org ブループリント
</div>

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

```yaml theme={null}
# 組織全体のブループリント（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 ブループリントで必要になるのはプロジェクト固有のコマンドだけです:

```yaml theme={null}
# 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)
```

<div id="best-practices">
  ## ベストプラクティス
</div>

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

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

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

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

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

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

  <Accordion title="maintenance は増分的に保つ">
    `pnpm install --force` ではなく `pnpm install` を、`rm -rf .venv && uv sync` ではなく `uv sync` を使ってください。増分更新のコマンドの方が、定期的な rebuild 時に高速です。
  </Accordion>
</AccordionGroup>

<div id="related-pages">
  ## 関連ページ
</div>

* [宣言型環境設定](/ja/onboard-devin/environment/blueprints)
* [ブループリント リファレンス](/ja/onboard-devin/environment/blueprint-reference)
* [テンプレート ライブラリ](/ja/onboard-devin/environment/templates) — すぐに使えるモノレポテンプレートを収録