Antigravity の DevContainer で「環境を秒で再現できる」開発フローを作る

新しいメンバーがプロジェクトに加わったとき、最初の30分が「環境構築の説明」で消える光景は珍しくありません。私の場合、Antigravity を使い始めた当初も、ローカルにインストールしたツールチェーンのバージョンが微妙にズレて、エージェントが同じプロンプトでも違う結果を返す、というトラブルがありました。

DevContainer を組み合わせる方法を見つけてからは、この問題はほぼ消えました。Antigravity ディレクトリごと Docker コンテナにすれば、新メンバーは VS Code から「Reopen in Container」を1回押すだけで、私と同じ環境が立ち上がります。今回はその設定の中身と、私が現場でハマったポイントをまとめます。

なぜ Antigravity と DevContainer の相性が良いのか

Antigravity プロジェクトは、エージェント設定（.antigravity/）、ツールスクリプト、依存パッケージ、認証情報、と意外と多くのファイルが絡みます。チームで使うとき、「私の手元では動くんですよ」を一掃するためには、これらをコンテナに閉じ込めるのが一番シンプルです。

Docker コンテナで動かすと、

• Node / Python のバージョンが固定される
• グローバルにインストールしたツール（gcloud, gh, direnv など）が常に存在する
• エージェント実行時の作業ディレクトリと環境変数が保証される
• ホスト OS の差（macOS / Linux / WSL）の影響を受けない

これは Antigravity のような「エージェントに環境を任せる」ツールでは特に効きます。エージェントが意図せずホスト固有のパスを叩く事故が減ります。

最小構成の .devcontainer/devcontainer.json

まず最小限の構成から。プロジェクトルートに .devcontainer/devcontainer.json を作ります。

{
  "name": "Antigravity Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {"version": "20"},
    "ghcr.io/devcontainers/features/python:1": {"version": "3.12"},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "postCreateCommand": "npm install && pip install -r requirements.txt",
  "remoteUser": "vscode",
  "mounts": [
    "source=${localEnv:HOME}/.config/gcloud,target=/home/vscode/.config/gcloud,type=bind,consistency=cached"
  ],
  "customizations": {
    "vscode": {
      "extensions": [
        "google.gemini-cli",
        "ms-azuretools.vscode-docker"
      ]
    }
  }
}

これで Node 20 + Python 3.12 + GitHub CLI が入った Ubuntu コンテナが立ち上がります。mounts で gcloud の認証情報をホストから持ち込んでいるので、コンテナ内で gcloud auth list がそのまま使えます。

Antigravity 専用の追加設定

このまま使ってもよいのですが、Antigravity を本格的に使うなら追加で必要な設定がいくつかあります。

第一に、Antigravity CLI のインストールです。postCreateCommand を拡張して、Antigravity の最新版を取り込みます。

"postCreateCommand": "bash .devcontainer/setup.sh"

そして setup.sh の中身：

#!/bin/bash
set -e
 
# Node packages
npm ci
 
# Python deps
pip install -r requirements.txt
 
# Antigravity CLI
curl -fsSL https://antigravity.google/install.sh | bash
echo 'export PATH="$HOME/.antigravity/bin:$PATH"' >> ~/.bashrc
 
# 共有エージェント設定の検証
antigravity agents validate
 
echo "Setup complete."

antigravity agents validate を含めるのがポイントです。コンテナ起動時にエージェント設定の YAML がスキーマ検証されるので、誰かが壊れた設定をコミットしてもチーム全員のコンテナ起動時に検知できます。

API キーやトークンの扱い

エージェントが API を叩く場合、認証情報の扱いが悩みどころです。コミットしてはいけないが、毎回手で入れるのも面倒、という板挟みです。

私は次の3層で運用しています。

第一層: ローカル開発用に .env.local（.gitignore 済み）。devcontainer の runArgs で読み込みます。

"runArgs": ["--env-file", ".env.local"]

第二層: チーム共有の認証は Google Secret Manager または Doppler を使用。postCreateCommand で fetch して環境変数化します。

第三層: 個人の API キー（自分の検証用）は .env.personal で。これは各自の責任で管理。

これで「誰かのキーが他人の検証で誤って使われる」事故がなくなります。

エージェント設定ファイルのバージョン固定

.antigravity/agents/*.yaml をリポジトリに含めるのは前提として、依存するモデルバージョンの固定もしておくと安全です。

# .antigravity/agents/reviewer.yaml
name: reviewer
model: gemini-3-flash-2026-04
# ↑ "gemini-3-flash-latest" ではなく具体的なバージョンを指定

latest を使うと、Google 側でモデルが更新されたタイミングでチーム内の挙動が突然変わります。意図的にアップデートするまでは固定バージョンを使うのが安全です。

VS Code と Antigravity 拡張の連携

DevContainer では customizations.vscode.extensions で拡張機能を指定できます。Antigravity プロジェクトで入れておきたい拡張は次のあたり。

"customizations": {
  "vscode": {
    "extensions": [
      "google.gemini-cli",
      "google.antigravity-vscode",
      "ms-azuretools.vscode-docker",
      "redhat.vscode-yaml",
      "github.vscode-pull-request-github"
    ],
    "settings": {
      "yaml.schemas": {
        "https://antigravity.google/schemas/agent.json": ".antigravity/agents/*.yaml"
      }
    }
  }
}

yaml.schemas を設定しておくと、エージェント設定 YAML の編集中に補完とエラー検知が効きます。これだけでもプロパティ名のタイポによる時間ロスがほぼなくなります。

ハマったポイント1: ファイル所有権

Linux ホストで Docker を直接使う場合、コンテナ内で作成したファイルが root 所有になることがあり、ホストから編集できなくなります。

devcontainer.json で remoteUser を指定する以外に、updateRemoteUserUID を有効にすると安全です。

"remoteUser": "vscode",
"updateRemoteUserUID": true

これでコンテナ内の vscode ユーザーがホストの自分の UID と揃うようになります。

ハマったポイント2: ボリュームマウントの遅さ（macOS）

macOS で大量のファイルを扱うと、デフォルトのバインドマウントが遅くて開発体験が悪化します。consistency: cached を指定すると体感が大きく変わります。

"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached",
"workspaceFolder": "/workspace"

または、node_modules のように頻繁に書き込まれるディレクトリは named volume に逃がすのも有効です。

ハマったポイント3: GitHub Codespaces との互換性

DevContainer は GitHub Codespaces でも動きますが、Codespaces 特有の制約があります。たとえば mounts でホスト側パス（${localEnv:HOME} など）を指定すると、Codespaces 上では動きません。

両方で動かしたい場合は、postCreateCommand で動的に環境を整える方が安全です。

# setup.sh
if [ -n "$CODESPACES" ]; then
  # Codespaces の場合は Secret から認証情報を取得
  gcloud auth login --cred-file=/tmp/gcp-key.json
else
  # ローカルの場合は ~/.config/gcloud マウントを利用
  echo "Using mounted gcloud credentials"
fi

チーム導入の段取り

DevContainer をいきなり全員に強制すると反発が出ます。私は次の段取りで進めました。

最初の1週間は「使ってみたい人だけ任意」。devcontainer.json だけコミットして、既存のローカル環境はそのまま残す。

2週目: 自分が DevContainer に完全移行。問題があれば即修正。社内 Slack に「DevContainer 推奨」と告知。

3週目: 新メンバーは DevContainer のみで開始。既存メンバーには移行を強くおすすめします。

4週目: ローカル環境のセットアップドキュメントを _archived/ に移動。DevContainer を正式手順に。

このペースで進めると、誰も置き去りにせずに移行できます。

全体を振り返ってのかわりに、最初に試すべきこと

これから始める方には、まず空の Antigravity プロジェクトで devcontainer.json を最小構成（最初に貼った JSON）で1つ作って、コンテナ内でエージェントを1つ動かしてみてください。それだけで「あ、これ便利だ」と分かるはずです。

そこから API キー管理、エージェント設定の検証、VS Code 拡張、と段階的に追加していけば、1週間ほどで実用レベルの環境が整います。最初の1日に投資する価値は、確実にあります。