> ## 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.

# シナリオ: ACME Corp の成長に合わせる

> ブループリント構成が、単一のリポジトリから、共有依存関係を持つ複数リポジトリのアプリケーション、さらに複数組織にまたがる Enterprise へとどのように発展していくかを説明します。

ブループリントには、リポジトリ、組織、Enterprise の 3 つのティアがあります。そこで最もよくあるのが、*これはどのティアに置くべきか？* という疑問です。

このページでは、架空の企業 **ACME Corp** の成長を 3 つの段階に沿って追いながら、その答えを示します。各段階で新しく生じる問題は 1 つだけで、その問題は 1 つ上のティアで解決されます。自社に近い段階から読んでください。

| Stage                                                                                                  | What ACME looks like                    | What they configure              |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------- |
| [1. One repository](#stage-1-one-repository)                                                           | 1 つの Rails アプリケーション、1 つのチーム             | 1 つのリポジトリ ブループリント                |
| [2. Several repositories, shared dependencies](#stage-2-several-repositories-with-shared-dependencies) | 5 つのリポジトリ、共有の開発 CLI、相互に依存するサービス群        | 組織ブループリントと、各リポジトリに 1 つずつのブループリント |
| [3. Multiple organizations](#stage-3-multiple-organizations-the-enterprise-blueprint)                  | 複数のチームがあり、それぞれが独自の組織を持ち、さらにセキュリティチームもある | Enterprise ブループリントと、組織ごとのブループリント |

<Info>
  先に大まかな目安を示すと、**リポジトリ ブループリントはプロジェクトの依存関係をインストールし、組織ブループリントは複数のリポジトリで共有するものをインストールし、Enterprise ブループリントはすべての組織で必須のものをインストールします。** ティアは追加式で、上位から順に適用されます: Enterprise → 組織 → リポジトリをクローン → リポジトリ。
</Info>

***

<div id="stage-1-one-repository">
  ## ステージ 1: 1 つのリポジトリ
</div>

ACME には 1 つの製品、`acme-web` があります。これは Postgres と Redis を使用する Rails アプリケーションです。エンジニアは 2 人、リポジトリは 1 つです。まだ共有すべきものはないため、**すべてリポジトリブループリントに記述します**。

**設定 > 環境 > ブループリント > 追加** でリポジトリを追加し、その Editor を開いて、次のように記述します。

```yaml acme-web (repository blueprint) theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Postgres and Redis
    run: |
      sudo apt-get update -qq
      sudo apt-get install -y postgresql redis-server libpq-dev
      sudo systemctl enable --now postgresql redis-server
      sudo -u postgres createuser -s "$USER"

maintenance:
  - name: Install gems and prepare the database
    run: |
      bundle install
      bin/rails db:prepare

knowledge:
  - name: lint
    contents: bundle exec rubocop
  - name: test
    contents: bundle exec rspec
  - name: startup
    contents: bin/rails server -p 3000
```

これで設定は完了です。保存するとビルドが実行され、以後はすべてのセッションが、Ruby のインストール、Postgres の起動、gem のインストール、データベースのマイグレーションが済んだ状態で起動します。

**なぜまだ組織ブループリントがないのですか？** 1 つのリポジトリにしか使わない組織ブループリントは、単に階層を増やすだけです。同じ設定を必要とする 2 つ目のリポジトリが出てきたら導入しましょう。

<Tip>
  ACME はこれを手作業で書いたわけではありません。Devin に *"set up your environment for this repository"* と依頼し、提案カードを確認して **承認** をクリックしました。[はじめに](/ja/onboard-devin/environment/blueprints#getting-started) を参照してください。
</Tip>

***

<div id="stage-2-several-repositories-with-shared-dependencies">
  ## ステージ 2: 依存関係を共有する複数のリポジトリ
</div>

2 年後、ACME には 5 つのリポジトリがあります。

| Repository      | What it is                                                                                                                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `acme-devtools` | コンテナを起動し、サービスを連携させ、ローカルホスト名 (`acme.local`、`portal.acme.local`) を提供する CLI (`acme`) です。さらに、社内ドキュメントの検索 (`acme docs:search`) も担います。 |
| `acme-web`      | メインアプリケーションです。ほとんどの機能はここに実装されます。                                                                                                 |
| `acme-portal`   | 顧客向けポータルです。`acme-web` を呼び出します。                                                                                                   |
| `acme-sso`      | 認証サービスです。両方のアプリケーションがこれに依存しています。                                                                                                 |
| `acme-events`   | イベントコンシューマーです。                                                                                                                   |

これは興味深いケースです。というのも、これらのリポジトリは **独立していない** からです。`acme-devtools` がインストールされ、`acme-sso` が動作していなければ、`acme-portal` では意味のある作業はできません。ここで 2 つの疑問が生じます。

<div id="one-blueprint-per-application-or-just-one-for-the-development-cli">
  ### 「アプリケーションごとに 1 つのブループリントが必要ですか？ それとも開発 CLI 用に 1 つだけで十分ですか？」
</div>

**どちらも必要です。役割が異なるためです。** Devin は、設定済みの*すべての*リポジトリを含む*1 つのスナップショット*を構築するので、これは二者択一ではありません。

* **5 つのリポジトリすべて**を環境に追加し、すべてがスナップショットにクローンされるようにします。
* **リポジトリ間で共有するセットアップ**は、**組織ブループリント**に 1 回だけ記述します。たとえば、言語ランタイム、Docker、ローカルのホスト名、内部レジストリ用の認証情報です。
* 各リポジトリには、そのリポジトリ固有の依存関係と固有の `Knowledge` エントリ (lint、test、起動コマンド) のために、それぞれ専用の**リポジトリブループリント**を持たせます。

すべてを `acme-devtools` ブループリントにまとめるべきでない理由は次のとおりです。リポジトリブループリントは、すべてのリポジトリのクローンが完了したあとに実行されますが、そのステップは**そのリポジトリのディレクトリ内で**実行され、`Knowledge` エントリも Devin がそのリポジトリで作業しているときにのみ読み込まれます。`acme-devtools` がすべてをインストールしてしまうと、`acme-portal` で作業するセッションからは portal の lint コマンドや test コマンドがまったく見えません。さらに、`acme-devtools` の 1 つのステップが失敗すると、ほかの 4 つのリポジトリは正常に見えても、実際には使えない状態になってしまいます。

<div id="the-organization-blueprint">
  ### 組織のブループリント
</div>

```yaml Organization-wide setup theme={null}
initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Node.js 20
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: Install Docker and Compose
    run: |
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker "$USER"

  - name: Local hostnames for the development CLI
    run: |
      for host in acme.local portal.acme.local sso.acme.local; do
        grep -q " $host$" /etc/hosts \
          || echo "127.0.0.1 $host" | sudo tee -a /etc/hosts > /dev/null
      done

maintenance:
  - name: Authenticate to the internal registry
    run: |
      bundle config set --global https://gems.acme.internal "$ACME_REGISTRY_TOKEN"
      npm config set //npm.acme.internal/:_authToken "$ACME_REGISTRY_TOKEN"

post-build:
  - name: Verify the stack comes up
    run: |
      acme up --detach
      acme status
      acme down
```

注目すべき点は 3 つあります。

1. **`initialize` と `maintenance` の違い。** Docker、ランタイム、ホスト名は 1回限り のシステム設定なので、`initialize` に含めます。レジストリ認証情報は定期ビルドのたびに更新する必要があるため、`maintenance` に含めます。

   `acme` CLI 自体をここに含めていないのは意図的です。これは `acme-devtools` の中にあり、組織のステップは**どのリポジトリもクローンされる前に**実行されるため、そのリポジトリ自身のブループリントからインストールします (以下に記載) 。このインストールはビルド中に実行され、スナップショットにも保持されるため、他のすべてのリポジトリから利用できます。
2. **`post-build` は複数リポジトリ構成の真価を発揮する場所です。** これは *すべての* リポジトリのクローンとセットアップが完了した後に実行されるため、スタック全体がまとめて起動することを検証できる唯一の場所です。終了コードが 0 以外だとビルドは失敗するので、セッションの途中ではなくビルド時点でスタックの不具合に気づけます。[`post-build`](/ja/onboard-devin/environment/blueprint-reference#post-build) を参照してください。
3. **シークレットは各リポジトリではなく組織に属します。** 組織ブループリントの **Secrets** タブにある 1 つの `ACME_REGISTRY_TOKEN` で、すべてのリポジトリの `bundle install` と `npm install` をまかなえます。

<Warning>
  **順序に関する注意:** 組織の `initialize` と `maintenance` はどちらもリポジトリがクローンされる**前に**実行されます ([build order](/ja/onboard-devin/environment/blueprints#how-builds-work) を参照) 。チェックアウト済みのソースを必要とするもの、たとえば*自分のリポジトリの 1 つの中に*ある CLI は、組織の `maintenance` ではなく、そのリポジトリのブループリントまたは `post-build` に入れる必要があります。tarball、パッケージ、コンテナイメージなどのリリース済みアーティファクトからインストールできる場合にのみ、組織ティアに置いてください。
</Warning>

<div id="the-repository-blueprints">
  ### 各リポジトリのブループリント
</div>

共有するものはすべてすでに存在しているため、各リポジトリのブループリントは小規模なままです。

```yaml acme-devtools (repository blueprint) theme={null}
initialize: |
  ./bin/install            # スナップショット全体のPATHに`acme`を追加する

maintenance: |
  acme docs:index          # ビルドごとに内部ドキュメントインデックスを更新する

knowledge:
  - name: cli
    contents: |
      `acme` manages every local service. Common commands:
        acme up <service>     start a service and its dependencies
        acme status           list running services
        acme docs:search <q>  search internal ACME engineering documentation
      Prefer `acme docs:search` over guessing at conventions.
```

```yaml acme-portal (repository blueprint) theme={null}
maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: startup
    contents: |
      The portal needs SSO running first:
        acme up sso
        acme up portal
      Then visit https://portal.acme.local
```

`acme-web`、`acme-sso`、`acme-events` も同じ構成です。つまり、それぞれ独自の依存関係に対する `maintenance` ステップと、それぞれの lint、テスト、起動コマンド用の `Knowledge` エントリがあります。

<Tip>
  リポジトリ一覧では **`acme-devtools` を最初** に配置してください。リポジトリのブループリントは Settings に表示されている順に実行されるため、共有 CLI を提供するリポジトリは、それを呼び出すリポジトリより先にセットアップしておく必要があります。
</Tip>

<Info>
  **Knowledge はリポジトリ単位です。** 5 つのリポジトリが設定されている場合、`acme-portal` で作業するセッションから参照できるのは、portal の Knowledge エントリに加えて、組織と Enterprise の Knowledge です。`acme-web` のエントリは参照できません。だからこそ、`maintenance` セクションが 1 行だけでも、各リポジトリに専用のブループリントが必要です。
</Info>

<Tip>
  `acme` CLI はすでにあらゆる実行方法を把握しているため、これらのブループリントで最も価値が高いのは **`Knowledge`** セクションです。ここでは、どの CLI コマンドを使えばよいかを Devin に教えられます。社内向けのドキュメント検索がある場合は、そこを参照するよう指定してください。
</Tip>

<div id="if-your-services-live-in-a-monorepo-instead">
  ### 代わりにサービスをモノレポで管理している場合
</div>

考え方は同じで、適用先が1つ下のティアになるだけです。リポジトリごとに1つのブループリントを使うのではなく、[ワークスペース](/ja/onboard-devin/environment/workspaces)を利用して、単一のリポジトリ内で各パッケージごとに専用のセットアップとKnowledgeを持たせます。

***

<div id="stage-3-multiple-organizations-the-enterprise-blueprint">
  ## ステージ 3: 複数の組織 — Enterprise ブループリント
</div>

ACME には現在 400 人のエンジニアがいます。Platform、Payments、Data はそれぞれ独自の Devin **組織** を持ち、リポジトリもメンバーもスナップショットも別々に管理されています。さらに、それらすべてに共通して適用される要件がセキュリティチームから定められています。

* すべてのトラフィックは、社内認証局を備えた企業のプロキシを経由します。
* すべてのパッケージは Artifactory から取得し、公開レジストリからは取得しません。
* すべての環境に、社内の依存関係スキャンツールとシークレットスキャンツールをインストールする必要があります。
* Python は 3.12、Node.js は 20 で全社統一とし、例外は認められません。

こうした内容を組織ブループリントに入れるべきではありません。そうすると **すべての組織にコピーする** 必要があり、どこか 1 つのチームが更新を忘れた時点で内容にずれが生じてしまうからです。そこで使うのが **Enterprise ブループリント** です。これは企業全体のベース環境として、すべての組織のビルドで最初に実行されます。

```yaml Devin's base environment (enterprise blueprint) theme={null}
initialize:
  - name: Corporate certificate authority and proxy
    run: |
      sudo cp "$FILE_ACME_CA_CERT" /usr/local/share/ca-certificates/acme-ca.crt
      sudo update-ca-certificates
      cat <<'EOF' >> ~/.bashrc
      export HTTPS_PROXY=http://proxy.acme.internal:8080
      export NO_PROXY=localhost,127.0.0.1,.acme.internal
      export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/acme-ca.crt
      export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
      EOF

  - name: Standard Python runtime
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: Security tooling
    run: |
      pip install bandit safety
      curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

maintenance:
  - name: Point every package manager at Artifactory
    run: |
      pip config set global.index-url \
        "https://devin:$ARTIFACTORY_TOKEN@artifactory.acme.internal/api/pypi/pypi/simple/"
      npm config set registry https://artifactory.acme.internal/api/npm/npm/
      npm config set //artifactory.acme.internal/api/npm/npm/:_authToken "$ARTIFACTORY_TOKEN"

knowledge:
  - name: security-policy
    contents: |
      All dependencies must resolve through artifactory.acme.internal.
      Never add a public registry to a lockfile or a CI configuration.
```

`ARTIFACTORY_TOKEN` は **enterprise secret** で、**Settings > Devin's base environment > Secrets** で一度定義すれば、すべての組織のあらゆるビルドとセッションで利用できます。証明書はファイル添付として、ビルドには `$FILE_ACME_CA_CERT` として渡されます。

<div id="what-each-tier-owns-now">
  ### 各ティアの現在の担当範囲
</div>

| Tier             | Owner                 | ACME example                                                        |
| ---------------- | --------------------- | ------------------------------------------------------------------- |
| **Enterprise**   | セキュリティおよびプラットフォームの管理者 | 認証局、プロキシ、Artifactory、Python 3.12、スキャナー、共有トークン 1 つ                   |
| **Organization** | 各チームの管理者              | Payments: Docker、`acme` CLI、チームのホスト名。Data: Spark と JDK 17。          |
| **Repository**   | リポジトリの管理者             | `bundle install`、`npm install`、および lint、test、startup に関する Knowledge |

Stage 2 の Payments 組織ブループリントは**変更なし**でそのまま動作します。Enterprise ティアですでに対応しているため、Python のインストールやレジストリの設定は不要になっただけです。Data の組織ブループリントは Spark と JDK をインストールしますが、Payments には適用されません。リポジトリブループリントに変更はありません。

<div id="operating-it">
  ### 運用
</div>

* **Python を 3.12 から 3.13 にアップグレードする**場合は、1 行編集して [Enterprise 全体の再ビルド](/ja/enterprise/environment-management/overview#enterprise-wide-rebuilds) を実行するだけで、その変更はすべての組織に反映されます。
* **あるチームで別の認証情報が必要な場合** — たとえば Data 組織が独自の Artifactory realm を持っている場合 — そのチームは同じ名前の組織シークレットを定義し、それが Enterprise シークレットを**オーバーライド**します。
* **これを組織間で段階的に展開する**には、[Enterprise の移行](/ja/enterprise/environment-management/rollout) を参照してください。

***

<div id="deciding-where-something-goes">
  ## 何をどこに置くかを決める
</div>

上から順に確認してください。最初の「はい」が答えです。

<Steps>
  <Step title="会社内のすべての組織で必要ですか？">
    → **Enterprise blueprint.** 証明書、プロキシ、社内レジストリ、必須ランタイム、セキュリティツール、全社共通のシークレット。
  </Step>

  <Step title="この組織内の2つ以上のリポジトリで必要ですか？">
    → **Organization blueprint.** Docker、共有の開発用 CLI、ローカルホスト名、リポジトリ横断のサービスオーケストレーション、レジストリ認証情報。構成したスタックは `post-build` で検証してください。
  </Step>

  <Step title="このリポジトリだけで必要ですか？">
    → **Repository blueprint.** 依存関係のインストール、マイグレーション、lint・test・起動コマンド用の `Knowledge` エントリ。
  </Step>

  <Step title="実行するコマンドではなく、事実ですか？">
    → **`Knowledge`**。該当するティアに配置します。これは実行されず、Devinの前提情報に読み込まれます。
  </Step>
</Steps>

これで避けられる、よくあるミス:

* **すべてを1つのリポジトリのブループリントに入れてしまうこと。** 他のリポジトリには `Knowledge` エントリが行き渡らず、1つの壊れたステップのせいでセットアップ全体が不調に見えてしまいます。
* **共有ツールをリポジトリごとに重複して入れてしまうこと。** 2つのリポジトリが同じグローバルツールの異なるバージョンをインストールすると、最後に実行されたものが有効になります。代わりに、そのツールは組織ブループリントに置いてください。
* **リポジトリ横断の検証を省略すること。** リポジトリ同士が連携して初めて動く場合、それをセッション開始前に確認できるのは `post-build` だけです。

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

* [宣言的構成](/ja/onboard-devin/environment/blueprints) — ビルドの順序、スナップショット、トラブルシューティング
* [ブループリント リファレンス](/ja/onboard-devin/environment/blueprint-reference) — `post-build` と `clone` を含むすべてのフィールド
* [テンプレート ライブラリ](/ja/onboard-devin/environment/templates) — 言語やレジストリごとに使えるコピーペースト用ブループリント
* [ワークスペースとモノレポ](/ja/onboard-devin/environment/workspaces) — Stage 2 のモノレポ版
* [Enterprise 環境の概要](/ja/enterprise/environment-management/overview) — Stage 3 の詳細を網羅