Antigravity の DevContainer 完全設定 — チーム開発で「私の環境では動く」を消す

私は基本的に個人開発者ですが、ここ数ヶ月、外部のフリーランスの方と一緒に Antigravity を使う機会が増えました。最初の 1 週間で何が起きたかというと、毎日のように「こちらの環境では動かないのですが」という連絡が来たのです。

原因は地味で、Node.js のバージョン違い、Python の仮想環境の構成違い、Linter の設定ファイルの読み込み順序、シェルの違いによるパスの差異、といったものでした。普段なら自分しか触らない環境なので気にしなかった部分が、共同作業で一気に噴出したわけです。

この問題を構造的に解決するために、私は DevContainer を Antigravity プロジェクトに組み込みました。これによって「Antigravity を起動すると、全員が完全に同じ Docker コンテナ内で開発する」状態が実現でき、環境差異起因のトラブルが激減しました。今回はその設定方法と、運用してわかった注意点を共有します。

DevContainer とは（Antigravity でなぜ効くのか

DevContainer はもともと VS Code 周辺で発展した仕組みで、.devcontainer/devcontainer.json というファイルにコンテナ定義を書いておくと、エディタがそのコンテナの中で開発を行ってくれる、というものです。Antigravity は VS Code 系統のエディタなので、この仕組みがそのまま使えます。

「Docker を使えば良いだけでは?」と思われるかもしれませんが、DevContainer の真価はそこではありません。Docker のセットアップ・起動・マウント・拡張機能の自動インストールまで、すべてエディタが面倒を見てくれる点が重要です。チームメンバーは「リポジトリをクローンして Antigravity で開く」だけで、何の設定もせずに同じ環境を手に入れられます。

これは個人開発者が複数の端末を使い分ける場面でも有効です。私自身、デスクトップ・MacBook・自宅 Mac mini の 3 台で開発しますが、全部の端末に Node.js やら Python やらを揃えるのは正直面倒でした。DevContainer 化してからは、Docker さえ入っていればどの端末でも同じ環境が即座に立ち上がります。

最小構成の devcontainer.json

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

{
  "name": "My Antigravity Project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

これだけで、Antigravity でプロジェクトを開くと「DevContainer で開きますか?」というダイアログが出て、Yes を押すと自動的にコンテナがビルドされ、その中で Antigravity が動き始めます。npm install も自動実行され、ESLint と Prettier の拡張機能も自動インストールされます。

image には Microsoft が公開している標準イメージを指定しています。TypeScript + Node.js なら上記のイメージが手軽です。Python なら mcr.microsoft.com/devcontainers/python:3.12、Go なら mcr.microsoft.com/devcontainers/go:1.22 のような選択肢があります。

ここまでで「同じ Node.js バージョンを全員が使う」ことは保証されます。それだけでも、私の環境では起きていた揉め事の半分は消えました。

実用的な構成 — マルチサービス対応

実際のプロジェクトでは、データベースや Redis のような周辺サービスも必要になります。これは docker-compose.yml を併用する形で書きます。

.devcontainer/docker-compose.yml:

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ..:/workspaces/${localWorkspaceFolderBasename}:cached
    command: sleep infinity
    environment:
      - DATABASE_URL=postgres://dev:dev@db:5432/devdb
      - REDIS_URL=redis://redis:6379
 
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: devdb
    volumes:
      - postgres-data:/var/lib/postgresql/data
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
 
volumes:
  postgres-data:

.devcontainer/Dockerfile:

FROM mcr.microsoft.com/devcontainers/typescript-node:20
 
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*
 
USER node

.devcontainer/devcontainer.json:

{
  "name": "My Antigravity Project",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
  "postCreateCommand": "npm install && npm run db:migrate",
  "forwardPorts": [3000, 5432, 6379],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ckolkman.vscode-postgres"
      ]
    }
  }
}

これで Antigravity を起動すると、アプリ用コンテナ、PostgreSQL、Redis が同時に立ち上がります。アプリは db というホスト名で PostgreSQL に、redis というホスト名で Redis に接続できます。

postCreateCommand でマイグレーションも自動実行しているので、新しいメンバーがリポジトリをクローンしたら、Antigravity を開くだけで「依存インストール → DB 起動 → マイグレーション完了」まで自動で進みます。これは非常に強力です。

ハマりどころ 1: ファイルの所有者問題

DevContainer を導入して最初にぶつかるのが、ファイル所有者の問題です。コンテナ内のユーザー（多くの場合 node か vscode）と、ホスト側のユーザーで UID が違うと、コンテナ内で作成したファイルがホスト側で「読めるけど編集権限がない」状態になります。

解決策は、コンテナ内のユーザーの UID をホストに合わせることです。Dockerfile の中で次のような工夫をします。

ARG USER_UID=1000
ARG USER_GID=1000
 
RUN if [ "$USER_UID" != "1000" ]; then \
    usermod -u $USER_UID node && \
    groupmod -g $USER_GID node; \
    fi

devcontainer.json の build.args で UID/GID を渡します。

{
  "build": {
    "dockerfile": "Dockerfile",
    "args": {
      "USER_UID": "${localEnv:UID}",
      "USER_GID": "${localEnv:GID}"
    }
  }
}

これで Linux ホストでも所有者問題が起きにくくなります。Mac の場合はそもそも Docker Desktop が UID マッピングを良い感じに処理してくれるので、この問題に遭遇しにくいです。

ハマりどころ 2: Antigravity 拡張機能のサーバー側 vs クライアント側

DevContainer では拡張機能の一部が「コンテナ側」で動き、一部が「ローカル側」で動きます。たとえば Antigravity の AI 機能は基本的にローカル側で動き、Linter のような言語ツールはコンテナ側で動きます。

問題は、Antigravity に組み込まれているプラグインの一部が「ローカル側で動くべきなのにコンテナ側にインストールされる」「あるいはその逆」になることです。これが起きると、機能が使えなくなったり、二重起動したりします。

対処は、devcontainer.json の customizations.vscode.extensions に書く拡張機能を「コンテナで動くべきもの」だけに絞ることです。AI 系のプラグインや、Antigravity 固有の UI 拡張は書かなくて大丈夫です。あくまで「言語サーバー」「フォーマッタ」「Linter」など、対象プロジェクトの言語に依存する拡張だけを記述します。

ハマりどころ 3: ファイル監視の限界

DevContainer 内で多数のファイルを監視するタスク（webpack-dev-server や Vite の HMR など）を動かすと、Linux ホストで inotify の上限に引っかかることがあります。エラーメッセージは ENOSPC: System limit for number of file watchers reached のような形で出ます。

対処は、Dockerfile か devcontainer.json で監視上限を緩めることです。

{
  "containerEnv": {
    "CHOKIDAR_USEPOLLING": "false"
  },
  "runArgs": [
    "--sysctl", "fs.inotify.max_user_watches=524288"
  ]
}

CHOKIDAR_USEPOLLING=true にすればポーリング方式になって inotify を使わなくなりますが、CPU 使用率が上がるのでおすすめしません。runArgs で上限を引き上げる方が筋が良いです。

チーム運用のベストプラクティス

実際にチームで運用してみてわかった、運用上の注意点をいくつか挙げます。

ひとつは、.devcontainer/ 以下のファイル変更は必ずプルリクエストで議論することです。気軽に書き換えると、他のメンバーがプロジェクトを開いたときに突然コンテナの再ビルドが走り、20 分待たされる、みたいなことが起きます。変更コストの大きさをチーム全員が共有しておく必要があります。

ふたつめは、postCreateCommand を冪等に書くことです。npm install は冪等なので問題ありませんが、マイグレーションのような副作用のあるコマンドは「すでに実行済みなら何もしない」設計が必要です。postStartCommand ではなく postCreateCommand に書く（コンテナ作成時のみ実行される）のもひとつの手です。

3 つめは、トラブルシュート用の Rebuild Container の存在をメンバーに周知することです。コンテナの状態がおかしくなったときは、Antigravity のコマンドパレットから「Rebuild Container」を選ぶと、ゼロから作り直せます。これを知っているだけで、解決時間が大幅に短くなります。

DevContainer を入れない方が良いケース

正直なところ、すべてのプロジェクトに DevContainer が向くわけではありません。

短命のプロトタイプや、自分一人でしか触らないツール類は、DevContainer のセットアップコストが見合わないことが多いです。コンテナの起動時間も毎回数分かかるので、起動の手軽さを犠牲にする価値があるかは慎重に考えるべきです。

また、ネイティブの GUI が絡む開発（Electron アプリ、モバイル開発のシミュレータ起動など）も、コンテナとの相性が悪い領域です。X11 フォワーディングなどの工夫はできますが、複雑さが一気に増します。

私自身は、「3 人以上が触るプロジェクト」「半年以上続くプロジェクト」「DB やキューといった周辺サービスを使うプロジェクト」のいずれかに該当するなら DevContainer 化する、という基準で判断しています。

明日から始める手順

最後に、明日試せる最小手順を書いておきます。

既存の Antigravity プロジェクトのルートに .devcontainer/devcontainer.json を作り、最小構成（先ほどの最初の例）を貼り付けます。Docker Desktop（または Linux なら docker engine）をインストールしておきます。Antigravity を再起動するか、コマンドパレットから「Reopen in Container」を選択すると、コンテナがビルドされて起動します。

ここまでで 30 分〜1 時間ですが、最初の起動はイメージダウンロードに時間がかかるので、コーヒーでも淹れながら待ちます。次回以降の起動は数十秒です。

「私の環境では動く」が消える快感は、想像以上に大きいものです。共同作業のストレスが減り、新メンバーのオンボーディングが半日から 5 分に短縮されます。1 度味わうと、もう DevContainer なしのプロジェクトには戻れなくなる、と私は感じています。