DevContainer 推奨設定ガイド

目的

組織内の全リポジトリで統一されたDevContainer環境を提供し、開発者体験を向上させる。

重要: 本ガイドの推奨設定は、Claude Code（AI開発アシスタント）が基本的に動作することを前提としています。すべての設定例は、Claude Code環境での動作を保証します。

ベースイメージ

{
  "image": "ghcr.io/keito4/config-base:latest"
}

推奨: latest タグを使用（常に最新の安定版が自動適用）

Claude Code動作のための必須設定

Claude Code（AI開発アシスタント）を動作させるための最小限の設定です。

1. ベースイメージ

{
  "image": "ghcr.io/keito4/config-base:latest"
}

config-baseイメージには@anthropic-ai/claude-code CLIが既にインストール済み
バージョン1.48.0以降を推奨

2. 必須mounts

{
  "mounts": [
    "source=${localEnv:HOME}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached"
  ]
}

マウント	目的	必須度
`.codex`	Codex設定・プロンプト・エージェント定義	必須
`.claude`	Claude認証情報・セッション履歴	必須

3. postCreateCommand

{
  "postCreateCommand": "/usr/local/bin/setup-claude.sh"
}

または既存のコマンドに追加：

{
  "postCreateCommand": "npm ci && npm run prepare && /usr/local/bin/setup-claude.sh"
}

setup-claude.shは.claudeディレクトリの初期化とClaude CLIの設定を実行
環境変数ANTHROPIC_API_KEYが必要（.devcontainer.envまたは1Passwordで管理）

4. 環境変数（推奨）

{
  "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"]
}

.devcontainer.envに以下を含める：

ANTHROPIC_API_KEY=***

5. MCP (Model Context Protocol) 設定

Claude CodeでMCPサーバーを利用する場合、.mcp.jsonの配置とマウントが必要です。

推奨配置: .claude/.mcp.json（Claude Codeが優先的に読み込む場所）

`.mcp.json`の生成方法

# postCreateCommandで自動生成（推奨）
bash script/setup-mcp.sh

setup-mcp.shは以下を実行：

credentials/mcp.envから環境変数を読み込み
.mcp.json.templateから.mcp.jsonを生成
ワークスペースルート（/workspaces/<project>/.mcp.json）に配置

MCP設定例（`.mcp.json`）

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    }
  }
}

⚠️ 重要な注意事項

セキュリティ:
- .mcp.jsonは.gitignoreに追加必須
- API KEYは環境変数テンプレートを使用
- 平文でのAPI KEY保存は避ける
配置場所の優先順位:
- Claude Codeは以下の順で.mcp.jsonを探索：
  1. .claude/.mcp.json（推奨）
  2. ~/.claude/.mcp.json（グローバル）
  3. ワークスペースルート（バージョン依存）

MCP対応のpostCreateCommand

{
  "postCreateCommand": "bash script/setup-env.sh && bash script/setup-mcp.sh && /usr/local/bin/setup-claude.sh"
}

Claude Code最小構成例

{
  "name": "Project Name",
  "image": "ghcr.io/keito4/config-base:latest",
  "mounts": [
    "source=${localEnv:HOME}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind,consistency=cached"
  ],
  "postCreateCommand": "bash script/setup-env.sh && bash script/setup-mcp.sh && /usr/local/bin/setup-claude.sh",
  "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"]
}

必須Features（全プロジェクト共通）

1. GitHub CLI

"ghcr.io/devcontainers/features/github-cli:1": {}

利用率: 100% (8/8)
用途: PR作成、Issue管理、GitHub Actions連携

2. Docker-in-Docker

"ghcr.io/devcontainers/features/docker-in-docker:2": {
  "moby": true,
  "dockerDashComposeVersion": "v2"
}

利用率: 87.5% (7/8)
用途: コンテナビルド、Docker Compose実行

主要機能:

DevContainer内からdockerコマンドを実行可能
Docker Composeワークフローのテスト
コンテナイメージのビルドとテスト
マルチコンテナアプリケーションのデバッグ

主なユースケース:

コンテナ化アプリのテスト: Docker Composeで完全なスタックをテスト
CI/CD開発: GitHub Actionsをactでローカルテスト
イメージビルド: カスタムDockerイメージをローカルビルド
マルチコンテナデバッグ: コンテナに依存するサービスのデバッグ

使用を推奨する場合:

✅ Dockerイメージをビルドするプロジェクト
✅ Docker Composeを使用するプロジェクト
✅ GitHub Actionsワークフローをローカルでテストしたい
✅ コンテナベースのE2Eテストを実行する

使用を避けるべき場合:

❌ Dockerを全く使わないプロジェクト
❌ パフォーマンスが最重要（ネイティブDockerより遅い）
❌ セキュリティ要件が厳しい環境（特権コンテナモードが必要）
❌ リソースが限られた環境（追加のメモリ/CPU使用）

セキュリティ考慮事項:

⚠️ 特権コンテナモードが必要（--privileged）
⚠️ ホストのDockerデーモンへのアクセス権限
⚠️ 本番環境での使用は推奨しない

パフォーマンス考慮事項:

ネイティブDockerと比較して若干のオーバーヘッド
追加のメモリとCPUリソースを消費
I/O操作が多い場合は特に影響が大きい

代替アプローチ:

ホストのDockerソケットをマウントする方法（より軽量だがセキュリティリスクあり）:

{
  "mounts": ["source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"]
}

推奨設定:

Docker Compose v2を使用（dockerDashComposeVersion: "v2"）
Mobyを有効化（moby: true）
VS Code + GitHub Codespacesの両方で動作

3. Git

"ghcr.io/devcontainers/features/git:1": {
  "version": "latest"
}

用途: バージョン管理（config-baseに含まれるが明示推奨）

プロジェクトタイプ別推奨Features

Node.js/TypeScriptプロジェクト

{
  "ghcr.io/devcontainers/features/node:1": {
    "version": "20"
  },
  "ghcr.io/devcontainers-extra/features/pnpm:2": {
    "version": "latest"
  },
  "ghcr.io/eitsupi/devcontainer-features/jq-likes:2": {
    "jqVersion": "latest",
    "yqVersion": "latest"
  }
}

pnpmパッケージマネージャー

pnpmを使用する場合、以下の2つの設定方法があります:

推奨: 独立したpnpm Feature

{
  "ghcr.io/devcontainers-extra/features/pnpm:2": {
    "version": "latest"
  }
}

利点

pnpmバージョン管理が明確で独立
node Featureとの依存関係を分離
最新のpnpm機能を即座に利用可能
より柔軟なバージョン管理
pnpmのみが必要なプロジェクトでも使用可能

使用を推奨する場合

✅ pnpmをパッケージマネージャーとして使用するプロジェクト
✅ pnpmのバージョンを明示的に管理したい場合
✅ Node.jsバージョンとpnpmバージョンを独立して管理したい場合
✅ monorepo構成でworkspace機能を活用する場合

代替: node:1のpnpmVersionオプション

{
  "ghcr.io/devcontainers/features/node:1": {
    "version": "20",
    "pnpmVersion": "latest"
  }
}

この方法の特徴

Node.jsインストールと同時にpnpmをセットアップ
シンプルな設定で済む
pnpmバージョンはNode.js Featureに依存

推奨アプローチ

独立したpnpm:2 Featureを使用することで、Node.jsとpnpmのバージョン管理を分離し、より明確で保守しやすい構成が可能になります。特にpnpmのバージョン管理を厳密に行いたい場合や、Node.jsのバージョンを変更してもpnpmバージョンは固定したい場合に有効です。

Supabaseプロジェクト

{
  "ghcr.io/devcontainers-extra/features/supabase-cli": {}
}

バージョン: latest（デフォルト）

利点:

データベースマイグレーション: supabase db push、supabase db diffでスキーマ管理
型生成: supabase gen types typescriptでTypeScript型を自動生成
ローカル開発環境: supabase startでローカルSupabaseスタックを起動
Edge Functions開発: supabase functions serveでローカルテスト
リモート管理: supabase linkでプロジェクトと連携

必須ケース:

✅ supabase/config.tomlが存在するプロジェクト
✅ Supabaseをバックエンドとして使用するプロジェクト
✅ データベーススキーマのバージョン管理が必要な場合
✅ Supabase Edge Functionsを開発する場合

推奨設定:

プロジェクトルートにsupabase/config.tomlが存在する場合、このFeatureを追加することを強く推奨します。

関連Feature:

Supabase Edge Functionsを開発する場合、Deno Runtimeとの併用を推奨:

{
  "ghcr.io/devcontainers-extra/features/supabase-cli": {},
  "ghcr.io/devcontainers-community/features/deno:1": {}
}

参考リンク:

Deno Runtime（Edge Functions開発）

{
  "ghcr.io/devcontainers-community/features/deno:1": {}
}

バージョン: 1 (最新のメジャーバージョン)

利点:

TypeScriptファーストサポート: 設定不要でTypeScriptを直接実行可能
Supabase Edge Functions対応: Supabase Edge Functionsの開発環境として必須
組み込みツールチェーン: deno fmt（フォーマッター）、deno lint（リンター）、deno test（テストランナー）が標準搭載
セキュアデフォルト: 権限システムによりファイルシステムやネットワークアクセスを明示的に許可
モダンエコシステム: JSR (JavaScript Registry) との統合

必須ケース:

Supabase Edge Functionsの開発
DenoベースのWebアプリケーション
TypeScript/JavaScriptのモダンランタイム環境が必要な場合

参考リンク:

E2Eテスト環境

{
  "ghcr.io/schlich/devcontainer-features/playwright:0": {}
}

利用率: 75% (6/8)
用途: ブラウザ自動テスト、E2Eテスト実行環境

主要機能:

Playwright本体とブラウザ（Chromium、Firefox、WebKit）の自動インストール
ヘッドレスブラウザ実行環境の構築
E2Eテストに必要な依存ライブラリの自動セットアップ
CI/CD環境との一貫性確保

主なユースケース:

E2Eテストの実装: ブラウザを使った統合テストの作成と実行
UIテストの自動化: フロントエンド機能の自動テスト
クロスブラウザテスト: 複数ブラウザでの動作確認
スクリーンショット/ビデオ録画: テスト実行時の視覚的記録

使用を推奨する場合:

✅ Playwrightを使用したE2Eテストがあるプロジェクト
✅ playwright.config.tsが存在するプロジェクト
✅ ブラウザベースのUIテストを実行する必要がある
✅ CI/CD環境との一貫性を保ちたい

使用を避けるべき場合:

❌ E2Eテストがないプロジェクト
❌ バックエンドのみのプロジェクト
❌ 他のE2Eテストツール（Cypress、Seleniumなど）を使用している

パフォーマンス考慮事項:

ブラウザバイナリのインストールに時間とストレージを使用
初回ビルド時に数百MBのダウンロードが発生
ヘッドレスモードでの実行を推奨（リソース効率化）

CI/CD統合:

GitHub ActionsなどのCI環境でも同じPlaywright設定を使用することで、ローカルとCI環境の一貫性を保証できます。

推奨設定:

最新バージョンのPlaywrightを使用し、ブラウザの自動アップデートを有効にする（デフォルト設定）。

インフラ/DevOpsプロジェクト

{
  "ghcr.io/devcontainers/features/terraform:1": {
    "version": "latest"
  },
  "ghcr.io/devcontainers/features/aws-cli:1": {
    "version": "latest"
  },
  "ghcr.io/devcontainers/features/azure-cli:1": {
    "version": "latest"
  },
  "ghcr.io/dhoeric/features/google-cloud-cli:1": {}
}

オプションFeatures（特定用途向け）

common-utils with Zsh（開発者体験向上）

{
  "ghcr.io/devcontainers/features/common-utils:2": {
    "configureZshAsDefaultShell": true
  }
}

機能概要:

Zsh: モダンで機能豊富なシェル
Oh-My-Zsh: 人気のZsh設定フレームワーク
共通CLIツール: curl, wget, git など
ビルドツール: gcc, make など

Zshの利点:

✅ スマートなタブ補完（Bashより高機能）
✅ 豊富なプラグインエコシステム（Oh-My-Zsh）
✅ カスタマイズ可能なプロンプト
✅ 改善されたコマンド履歴検索
✅ Gitステータスのプロンプト表示

考慮事項:

学習コストあり（Bashに慣れた開発者向け）
ほとんどのBashスクリプトはZshでも動作（一部互換性差異あり）
起動が若干遅い（実用上は無視できるレベル）

Bash派の代替設定:

{
  "ghcr.io/devcontainers/features/common-utils:2": {}
}

Zshを無効にする場合はconfigureZshAsDefaultShellオプションを省略します。

推奨環境変数（Zsh使用時）:

{
  "remoteEnv": {
    "SHELL": "/bin/zsh"
  }
}

利用シーン:

開発者の生産性向上を重視するプロジェクト
ターミナル操作が多いプロジェクト
チーム全体で統一されたシェル環境を提供したい場合

1Password統合（機密情報管理）

{
  "ghcr.io/flexwie/devcontainer-features/op:1": {
    "version": "latest"
  }
}

用途: 環境変数・シークレット管理

act（ローカルGitHub Actions実行）

{
  "ghcr.io/dhoeric/features/act:1": {}
}

用途: CI/CDワークフローのローカルテスト

Rust開発環境

{
  "ghcr.io/devcontainers/features/rust:1": {},
  "ghcr.io/lee-orr/rusty-dev-containers/cargo-binstall:0": {
    "packages": "similarity-ts"
  }
}

用途: similarity-ts 等の Rust ツールビルド

Python開発環境

{
  "ghcr.io/devcontainers/features/python:1": {
    "version": "latest"
  }
}

用途: Python を使用するプロジェクト向け

標準mounts設定

{
  "mounts": [
    "source=${localEnv:HOME}/.cursor,target=/home/vscode/.cursor,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.config/gh,target=/home/vscode/.config/gh,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.codex,target=/home/vscode/.codex,type=bind,consistency=cached",
    "source=${localEnv:HOME}/.claude,target=/home/vscode/.claude,type=bind,consistency=cached"
  ]
}

マウント解説

パス	目的	利用率	Claude Code
`.cursor`	Cursor IDE設定同期	100%	-
`.gitconfig`	Git設定継承	100%	-
`.config/gh`	GitHub CLI認証情報	87.5%	-
`.codex`	Codex設定・プロンプト・エージェント	62.5%	必須
`.claude`	Claude認証情報・セッション履歴	37.5%	必須

注意: Claude Codeを使用する場合、.codexと.claudeのマウントは必須です。

環境変数管理

runArgs設定

{
  "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"]
}

`.devcontainer.env`ファイル例

# Claude Code (必須)
ANTHROPIC_API_KEY=***

# AWS
AWS_PROFILE=default
AWS_REGION=ap-northeast-1

# Supabase
SUPABASE_ACCESS_TOKEN=***
SUPABASE_DB_PASSWORD=***

# その他
NODE_ENV=development

重要: Claude Codeを使用する場合、ANTHROPIC_API_KEYの設定は必須です。1Passwordまたは手動で設定してください。

postCreateCommand推奨パターン

重要: Claude Codeを使用する場合、すべてのパターンで /usr/local/bin/setup-claude.sh の実行が必須です。

Node.jsプロジェクト

{
  "postCreateCommand": "npm ci && npm run prepare && /usr/local/bin/setup-claude.sh"
}

モノレポ構成

{
  "postCreateCommand": "cd <project-dir> && npm ci && npm run prepare && /usr/local/bin/setup-claude.sh || true"
}

注意: || true はnpmコマンド失敗時も継続するため、setup-claude.shは確実に実行されます。

インフラプロジェクト

{
  "postCreateCommand": "bash scripts/setup.sh && /usr/local/bin/setup-claude.sh"
}

Claude Code専用（最小構成）

{
  "postCreateCommand": "/usr/local/bin/setup-claude.sh"
}

カスタマイズ設定（VSCode）

{
  "customizations": {
    "vscode": {
      "extensions": [
        "esbenp.prettier-vscode",
        "dbaeumer.vscode-eslint",
        "redhat.vscode-yaml",
        "eamodio.gitlens",
        "github.vscode-github-actions"
      ],
      "settings": {
        "npm.packageManager": "pnpm"
      }
    }
  }
}

ベストプラクティス

1. バージョン管理

ベースイメージ: セマンティックバージョニング（例: 1.48.0）を明示
Features: latest使用は最小限に、安定性重視の場合はバージョン固定
更新頻度: 四半期ごとにベースイメージ見直し

2. パフォーマンス最適化

{
  "mounts": [
    "source=${localWorkspaceFolderBasename}-node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume"
  ]
}

node_modulesをボリュームマウントして高速化

3. セキュリティ

機密情報は.devcontainer.envまたは1Passwordで管理
.devcontainer.envは.gitignoreに追加必須
runArgsでの環境変数直接埋め込みは禁止

4. チーム協調

{
  "name": "<Project Name> Development",
  "remoteUser": "vscode"
}

プロジェクト名を明示してコンテナ識別性向上

移行ガイド

古いバージョンからの更新手順

ベースイメージ更新

- "image": "ghcr.io/keito4/config-base:1.0.40"
+ "image": "ghcr.io/keito4/config-base:latest"

非推奨Feature削除
- 重複するFeature（config-baseに既に含まれるもの）を削除
mounts標準化
- 上記の標準mounts設定を適用

動作確認

# コンテナリビルド
Cmd/Ctrl + Shift + P → "Dev Containers: Rebuild Container"

# 初期化コマンド実行確認
# postCreateCommandが正常完了することを確認

トラブルシューティング

よくある問題

Claude Codeが起動しない
- .codexと.claudeのマウントを確認
- ANTHROPIC_API_KEYが.devcontainer.envに設定されているか確認
- setup-claude.shが実行されているか確認: ls -la /usr/local/bin/setup-claude.sh
- コンテナ再ビルド: Cmd/Ctrl + Shift + P → "Dev Containers: Rebuild Container"
Claude Code認証エラー
- ANTHROPIC_API_KEYの値を確認
- 1Passwordから最新のAPIキーを取得: OP_ACCOUNT=your.1password.com bash script/setup-env.sh
- 環境変数が正しく読み込まれているか確認: echo $ANTHROPIC_API_KEY
.codexや.claudeの設定が反映されない
- ホスト側でディレクトリが存在するか確認: ls -la ~/.codex ~/.claude
- ホスト側でディレクトリ作成: mkdir -p ~/.codex ~/.claude
- マウント設定がdevcontainer.jsonに正しく記載されているか確認
- コンテナ再起動後も反映されない場合は、コンテナ再ビルド
postCreateCommandが失敗する
- || trueを末尾に追加して継続実行
- スクリプトの実行権限確認: chmod +x scripts/*.sh
- ログを確認: コンテナ起動ログでsetup-claude.shのエラーメッセージを確認
mountsでPermission Denied
- ホスト側でディレクトリ事前作成: mkdir -p ~/.codex ~/.claude
- ディレクトリのパーミッション確認: ls -la ~/ | grep -E "codex|claude"
Featuresのインストールが遅い
- 不要なFeatureを削除
- ベースイメージに含まれるものは重複指定しない
MCPサーバーが動作しない
- .mcp.jsonの存在確認:
```
ls -la /workspaces/<project>/.mcp.json
ls -la ~/.claude/.mcp.json
```
- .mcp.jsonが生成されない場合:
  - credentials/mcp.envが存在するか確認
  - script/setup-env.shを先に実行
  - 手動で実行: bash script/setup-mcp.sh
- 環境変数が展開されているか確認:
```
cat .mcp.json | grep '\${'
# ${VAR_NAME}が残っている場合は未展開
```
- 推奨: .mcp.jsonを.claude/.mcp.jsonにコピー:
```
mkdir -p ~/.claude
cp .mcp.json ~/.claude/.mcp.json
```
Playwright MCPが動作しない
- Node.jsとnpxが利用可能か確認:
```
node --version
npx --version
```
- Playwrightパッケージをグローバルインストール:
```
npm install -g @playwright/mcp@latest
```
- ブラウザのインストール:
```
npx playwright install
```

参考リンク

DevContainer関連

Claude Code関連

Claude Code公式ドキュメント
Claude API Documentation
本リポジトリのClaude設定: .claude/ および .codex/

MCP (Model Context Protocol) 関連

MCP公式ドキュメント
Playwright MCP
本リポジトリのMCP設定: credentials/templates/mcp.env.template

更新日: 2025-12-30 バージョン: 1.0.0 メンテナ: keito4

FilesExpand file tree

devcontainer-recommendations.md

Latest commit

History

devcontainer-recommendations.md

File metadata and controls

DevContainer 推奨設定ガイド

目的

ベースイメージ

Claude Code動作のための必須設定

1. ベースイメージ

2. 必須mounts

3. postCreateCommand

4. 環境変数（推奨）

5. MCP (Model Context Protocol) 設定

.mcp.jsonの生成方法

MCP設定例（.mcp.json）

⚠️ 重要な注意事項

MCP対応のpostCreateCommand

Claude Code最小構成例

必須Features（全プロジェクト共通）

1. GitHub CLI

2. Docker-in-Docker

3. Git

プロジェクトタイプ別推奨Features

Node.js/TypeScriptプロジェクト

pnpmパッケージマネージャー

推奨: 独立したpnpm Feature

利点

使用を推奨する場合

代替: node:1のpnpmVersionオプション

この方法の特徴

推奨アプローチ

Supabaseプロジェクト

Deno Runtime（Edge Functions開発）

E2Eテスト環境

インフラ/DevOpsプロジェクト

オプションFeatures（特定用途向け）

common-utils with Zsh（開発者体験向上）

1Password統合（機密情報管理）

act（ローカルGitHub Actions実行）

Rust開発環境

Python開発環境

標準mounts設定

マウント解説

環境変数管理

runArgs設定

.devcontainer.envファイル例

postCreateCommand推奨パターン

Node.jsプロジェクト

モノレポ構成

インフラプロジェクト

Claude Code専用（最小構成）

カスタマイズ設定（VSCode）

ベストプラクティス

1. バージョン管理

2. パフォーマンス最適化

3. セキュリティ

4. チーム協調

移行ガイド

古いバージョンからの更新手順

トラブルシューティング

よくある問題

参考リンク

DevContainer関連

Claude Code関連

MCP (Model Context Protocol) 関連

`.mcp.json`の生成方法

MCP設定例（`.mcp.json`）

`.devcontainer.env`ファイル例