From f5f281194fde3e8a1540a3f1003f5160535efb0f Mon Sep 17 00:00:00 2001 From: keito4 Date: Tue, 30 Dec 2025 17:37:14 +0900 Subject: [PATCH 1/2] feat: Add DevContainer recommendations and enhance config-base-sync-update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive DevContainer recommendations guide (.codex/devcontainer-recommendations.md) - Enhance config-base-sync-update command with automatic features detection - Update README with link to DevContainer recommendations - Ensure Claude Code compatibility in all recommended configurations Key additions: - Claude Code minimal configuration requirements - Project type-based features auto-detection (Node.js, Supabase, Terraform, etc.) - Required mounts (.codex, .claude) and postCreateCommand setup - Detailed troubleshooting section for Claude Code integration - Comprehensive features update strategy with duplicate detection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .claude/commands/config-base-sync-update.md | 251 +++++++++-- .codex/devcontainer-recommendations.md | 476 ++++++++++++++++++++ README.md | 2 + 3 files changed, 698 insertions(+), 31 deletions(-) create mode 100644 .codex/devcontainer-recommendations.md diff --git a/.claude/commands/config-base-sync-update.md b/.claude/commands/config-base-sync-update.md index d6d21880..82e8dee3 100644 --- a/.claude/commands/config-base-sync-update.md +++ b/.claude/commands/config-base-sync-update.md @@ -1,11 +1,19 @@ --- -description: Update DevContainer to latest config-base image and create PR -allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(curl:*), Bash(jq:*) +description: Update DevContainer to latest config-base image, sync recommended features, and create PR +allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(curl:*), Bash(jq:*), Bash(find:*), Bash(test:*), Bash(ls:*) argument-hint: [--version X.Y.Z] --- # DevContainer Update Workflow +このコマンドは以下を自動実行します： + +- config-baseイメージの最新バージョンへの更新 +- プロジェクトタイプに基づいた推奨featuresの自動追加 +- Claude Code動作に必要な設定の確保（mounts, postCreateCommand） +- 重複featuresの検出と報告 +- GitHub PRの自動作成 + ## Step 1: Load Settings Try to read `.claude/config-base-sync.local.md` for user configuration. @@ -74,13 +82,14 @@ If branch already exists: - Suggest: "Delete the branch with: git branch -D update-config-base-{target-version}" - Stop execution -## Step 6: Read Template Configuration +## Step 6: Read Template and Recommended Configuration Read the reference configuration from this repository: - Read `/Users/keito4/develop/github.com/keito4/config/.devcontainer/devcontainer.json` - Read `/Users/keito4/develop/github.com/keito4/config/.devcontainer/codex-config.json` - Read `/Users/keito4/develop/github.com/keito4/config/.devcontainer/claude-settings.json` +- Read `/Users/keito4/develop/github.com/keito4/config/.codex/devcontainer-recommendations.md` Extract recommended configuration based on `updateScope`: @@ -88,21 +97,97 @@ Extract recommended configuration based on `updateScope`: - **image-only**: Update only the image field - **minimal**: Update image and features only +### Recommended Features Detection + +From `devcontainer-recommendations.md`, identify: + +1. **必須Features（全プロジェクト共通）**: + - `ghcr.io/devcontainers/features/github-cli:1` + - `ghcr.io/devcontainers/features/docker-in-docker:2` + - `ghcr.io/devcontainers/features/git:1` + +2. **Claude Code必須設定**: + - `.codex` mount (必須) + - `.claude` mount (必須) + - `postCreateCommand`に`/usr/local/bin/setup-claude.sh`を含める + +3. **プロジェクトタイプ別Features**（現在のプロジェクトに基づいて判定）: + - Node.js/TypeScriptプロジェクト（package.jsonが存在）: + - `ghcr.io/devcontainers/features/node:1` + - `ghcr.io/devcontainers-extra/features/pnpm:2` + - `ghcr.io/eitsupi/devcontainer-features/jq-likes:2` + - Supabaseプロジェクト（supabase/config.tomlが存在）: + - `ghcr.io/devcontainers-extra/features/supabase-cli` + - E2Eテスト（playwright.config.tsが存在）: + - `ghcr.io/schlich/devcontainer-features/playwright:0` + - Terraformプロジェクト（\*.tfファイルが存在）: + - `ghcr.io/devcontainers/features/terraform:1` + ## Step 7: Update devcontainer.json Based on `updateScope`, update `.devcontainer/devcontainer.json`: -1. Update `image` field to `ghcr.io/keito4/config-base:{target-version}` +### 7.1: Update Image Version + +Update `image` field to `ghcr.io/keito4/config-base:{target-version}` + +### 7.2: Update Features (if updateScope is "all" or "minimal") + +**Features Update Strategy**: + +1. **必須Features追加**（存在しない場合のみ追加）: + - GitHub CLI + - Docker-in-Docker + - Git + +2. **プロジェクトタイプ別Features追加**: + - プロジェクト内のファイル存在をチェック + - 該当するfeaturesを自動追加（存在しない場合のみ） + +3. **既存Features保持**: + - ユーザーが手動追加したfeaturesは保持 + - 推奨設定に含まれるfeaturesのバージョン設定を更新 + +4. **非推奨Features検出**: + - config-baseに既に含まれるfeaturesを検出 + - ユーザーに削除推奨として報告（自動削除はしない） + +**Features更新の報告**: + +- ✅ 追加されるfeatures: [リスト] +- 📝 更新されるfeatures: [リスト] +- ⚠️ 削除推奨features: [リスト]（重複） +- ✨ 保持されるユーザー追加features: [リスト] -2. If `updateScope` is "all" or "minimal": - - Update `features` object with recommended features from template - - Preserve any user-added features not in template +### 7.3: Update Mounts (if updateScope is "all") -3. If `updateScope` is "all": - - Update `remoteEnv` with recommended environment variables - - Update `mounts` with recommended mounts (preserve user additions) - - Update `customizations` with recommended VS Code settings - - Update `postCreateCommand` if significantly different +**Claude Code必須mounts**を確認・追加: + +- `.codex` mount +- `.claude` mount + +**標準mounts**を確認・追加: + +- `.cursor` mount +- `.gitconfig` mount +- `.config/gh` mount + +既存のユーザー追加mountsは保持。 + +### 7.4: Update postCreateCommand (if updateScope is "all") + +**Claude Code必須**: + +- `postCreateCommand`に`/usr/local/bin/setup-claude.sh`が含まれているか確認 +- 含まれていない場合は末尾に追加: + ``` + 既存コマンド && /usr/local/bin/setup-claude.sh + ``` + +### 7.5: Update Other Settings (if updateScope is "all") + +- Update `remoteEnv` with recommended environment variables +- Update `customizations` with recommended VS Code settings Use the Edit tool to make precise updates to the JSON file. @@ -117,16 +202,64 @@ If `updateScope` is "all": ## Step 9: Report Changes -Display a summary of changes made: +Display a detailed summary of all changes made: + +### Image Version + +- `ghcr.io/keito4/config-base:{old-version}` → `v{target-version}` + +### Features Changes (if updateScope is "all" or "minimal") + +**✅ 追加されたFeatures**: -- Image version: old → new -- Added features (if any) -- Updated settings (if any) -- Changed commands (if any) +``` +- feature-name-1: version +- feature-name-2: version +``` + +**📝 更新されたFeatures**: + +``` +- feature-name: old-version → new-version +``` + +**⚠️ 削除推奨Features** (config-baseに含まれるため重複): + +``` +- feature-name-1 +- feature-name-2 +``` + +_注意: これらのfeaturesは自動削除されていません。必要に応じて手動で削除してください。_ + +**✨ 保持されたユーザー追加Features**: + +``` +- custom-feature-1: version +- custom-feature-2: version +``` + +### Mounts Changes (if updateScope is "all") + +**追加されたMounts**: + +- `.codex` (Claude Code必須) +- `.claude` (Claude Code必須) + +### Commands Changes (if updateScope is "all") + +**postCreateCommand**: + +- 追加: `/usr/local/bin/setup-claude.sh` (Claude Code必須) + +### Other Changes (if updateScope is "all") + +- Updated remoteEnv settings +- Updated VS Code customizations ## Step 10: Commit Changes -Create commit with conventional commit message: +Create commit with conventional commit message including features details: ```bash git add .devcontainer/ @@ -134,11 +267,17 @@ git commit -m "feat: Update config-base image to v{target-version} - Update DevContainer image from v{old-version} to v{target-version} - Sync configuration with latest recommended settings +- Add {count} new features based on project type detection +- Ensure Claude Code compatibility (mounts, postCreateCommand) - Update features, mounts, and environment variables +Features added: {list-of-added-features} + Release notes: https://github.com/keito4/config/releases/tag/v{target-version}" ``` +_Note: Replace `{count}` and `{list-of-added-features}` with actual values from Step 9._ + ## Step 11: Push and Create PR Push branch to remote: @@ -157,19 +296,44 @@ If `autoCreatePR` is true: --title "feat: Update config-base to v{target-version}" \ --body "## Summary - Updates DevContainer configuration to use the latest config-base image. + Updates DevContainer configuration to use the latest config-base image and syncs with recommended settings. ### Changes + + #### Image Version - **Image**: ghcr.io/keito4/config-base:{old-version} → v{target-version} - - **Configuration**: Synced with latest recommended settings + + #### Features + - ✅ **Added**: {added-features-list} + - 📝 **Updated**: {updated-features-list} + - ⚠️ **Recommended for removal** (duplicates): {duplicate-features-list} + - ✨ **Preserved**: {preserved-features-list} + + #### Configuration + - 📁 **Mounts**: Added Claude Code required mounts (`.codex`, `.claude`) + - 🔧 **postCreateCommand**: Ensured `/usr/local/bin/setup-claude.sh` execution + - ⚙️ **Settings**: Synced remoteEnv and VS Code customizations + + ### Claude Code Compatibility + This update ensures full Claude Code compatibility with: + - Required mounts for `.codex` and `.claude` + - Automatic Claude CLI setup via `setup-claude.sh` + - Recommended features based on project type ### Release Notes See: https://github.com/keito4/config/releases/tag/v{target-version} - ### Testing + ### Testing Checklist - [ ] DevContainer builds successfully - - [ ] All tools and features work as expected + - [ ] Claude Code works (can run claude commands) + - [ ] All project-specific tools work as expected - [ ] CI passes + - [ ] No permission issues with mounts + + ### Recommended Actions + {if duplicate-features exist} + - Consider removing duplicate features: {duplicate-features-list} + {endif} 🤖 Generated with [Claude Code](https://claude.com/claude-code) " @@ -184,19 +348,44 @@ If `autoCreatePR` is false: ## Step 12: Final Report -Provide a complete summary: +Provide a complete summary including features changes: ``` ✅ DevContainer update complete! -Version: v{old-version} → v{target-version} -Branch: update-config-base-{target-version} -PR: {PR-URL or "Manual creation required"} - -Next steps: -1. Review the pull request -2. Test the DevContainer locally -3. Merge when ready +📦 Image Version +- ghcr.io/keito4/config-base:{old-version} → v{target-version} + +🔧 Features Summary +- Added: {count} features +- Updated: {count} features +- Recommended for removal: {count} features (duplicates) +- Preserved: {count} custom features + +📁 Configuration +- Claude Code mounts: ✅ Configured +- setup-claude.sh: ✅ Included in postCreateCommand +- Standard mounts: ✅ Updated + +🌿 Git Branch +- Branch: update-config-base-{target-version} +- PR: {PR-URL or "Manual creation required"} + +📋 Next Steps +1. Review the pull request (check features changes) +2. Test the DevContainer locally: + - Rebuild container: Cmd/Ctrl + Shift + P → "Dev Containers: Rebuild Container" + - Verify Claude Code works: `claude --version` + - Check all tools are available +3. {if duplicate features exist} + Consider removing duplicate features before merging + {endif} +4. Merge when all checks pass + +💡 Tips +- Run `claude help` to verify Claude Code is working +- Check logs if container build fails +- Review `.devcontainer/devcontainer.json` for any conflicts ``` --- diff --git a/.codex/devcontainer-recommendations.md b/.codex/devcontainer-recommendations.md new file mode 100644 index 00000000..828c0b49 --- /dev/null +++ b/.codex/devcontainer-recommendations.md @@ -0,0 +1,476 @@ +# DevContainer 推奨設定ガイド + +## 目的 + +Elu-co-jp配下の全リポジトリで統一されたDevContainer環境を提供し、開発者体験を向上させる。 + +**重要**: 本ガイドの推奨設定は、**Claude Code（AI開発アシスタント）が基本的に動作すること**を前提としています。すべての設定例は、Claude Code環境での動作を保証します。 + +## ベースイメージ + +```json +{ + "image": "ghcr.io/keito4/config-base:1.13.1" +} +``` + +**最新バージョン**: 1.15.0（management_toolsで使用中） +**推奨バージョン**: 1.13.1+（安定版として広く採用） + +## Claude Code動作のための必須設定 + +Claude Code（AI開発アシスタント）を動作させるための最小限の設定です。 + +### 1. ベースイメージ + +```json +{ + "image": "ghcr.io/keito4/config-base:1.13.1" +} +``` + +- config-baseイメージには`@anthropic-ai/claude-code` CLIが既にインストール済み +- バージョン1.13.1以降を推奨 + +### 2. 必須mounts + +```json +{ + "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 + +```json +{ + "postCreateCommand": "/usr/local/bin/setup-claude.sh" +} +``` + +または既存のコマンドに追加： + +```json +{ + "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. 環境変数（推奨） + +```json +{ + "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"] +} +``` + +`.devcontainer.env`に以下を含める： + +```bash +ANTHROPIC_API_KEY=*** +``` + +### Claude Code最小構成例 + +```json +{ + "name": "Project Name", + "image": "ghcr.io/keito4/config-base:1.13.1", + "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": "/usr/local/bin/setup-claude.sh", + "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"] +} +``` + +## 必須Features（全プロジェクト共通） + +### 1. GitHub CLI + +```json +"ghcr.io/devcontainers/features/github-cli:1": {} +``` + +- 利用率: 100% (8/8) +- 用途: PR作成、Issue管理、GitHub Actions連携 + +### 2. Docker-in-Docker + +```json +"ghcr.io/devcontainers/features/docker-in-docker:2": { + "moby": true, + "dockerDashComposeVersion": "v2" +} +``` + +- 利用率: 87.5% (7/8) +- 用途: コンテナビルド、Docker Compose実行 + +### 3. Git + +```json +"ghcr.io/devcontainers/features/git:1": { + "version": "latest" +} +``` + +- 用途: バージョン管理（config-baseに含まれるが明示推奨） + +## プロジェクトタイプ別推奨Features + +### Node.js/TypeScriptプロジェクト + +```json +{ + "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" + } +} +``` + +### Supabaseプロジェクト + +```json +{ + "ghcr.io/devcontainers-extra/features/supabase-cli": { + "version": "latest" + } +} +``` + +- 利用率: 75% (6/8) +- 必須ケース: Supabase使用プロジェクト全般 + +### E2Eテスト環境 + +```json +{ + "ghcr.io/schlich/devcontainer-features/playwright:0": {} +} +``` + +- 利用率: 75% (6/8) +- 用途: ブラウザ自動テスト + +### インフラ/DevOpsプロジェクト + +```json +{ + "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（特定用途向け） + +### 1Password統合（機密情報管理） + +```json +{ + "ghcr.io/flexwie/devcontainer-features/op:1": { + "version": "latest" + } +} +``` + +- 利用例: management_tools, pulse_survey +- 用途: 環境変数・シークレット管理 + +### act（ローカルGitHub Actions実行） + +```json +{ + "ghcr.io/dhoeric/features/act:1": {} +} +``` + +- 利用例: recall_ai, package_manager +- 用途: CI/CDワークフローのローカルテスト + +### Rust開発環境 + +```json +{ + "ghcr.io/devcontainers/features/rust:1": {}, + "ghcr.io/lee-orr/rusty-dev-containers/cargo-binstall:0": { + "packages": "similarity-ts" + } +} +``` + +- 利用例: recall_ai（similarity-tsビルド用） + +### Python開発環境 + +```json +{ + "ghcr.io/devcontainers/features/python:1": { + "version": "latest" + } +} +``` + +- 利用例: management_tools, pulse_survey + +## 標準mounts設定 + +```json +{ + "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設定 + +```json +{ + "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"] +} +``` + +### `.devcontainer.env`ファイル例 + +```bash +# 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プロジェクト + +```json +{ + "postCreateCommand": "npm ci && npm run prepare && /usr/local/bin/setup-claude.sh" +} +``` + +### モノレポ構成 + +```json +{ + "postCreateCommand": "cd && npm ci && npm run prepare && /usr/local/bin/setup-claude.sh || true" +} +``` + +**注意**: `|| true` はnpmコマンド失敗時も継続するため、setup-claude.shは確実に実行されます。 + +### インフラプロジェクト + +```json +{ + "postCreateCommand": "bash scripts/setup.sh && /usr/local/bin/setup-claude.sh" +} +``` + +### Claude Code専用（最小構成） + +```json +{ + "postCreateCommand": "/usr/local/bin/setup-claude.sh" +} +``` + +## カスタマイズ設定（VSCode） + +```json +{ + "customizations": { + "vscode": { + "extensions": [ + "esbenp.prettier-vscode", + "dbaeumer.vscode-eslint", + "redhat.vscode-yaml", + "eamodio.gitlens", + "github.vscode-github-actions" + ], + "settings": { + "npm.packageManager": "pnpm" + } + } + } +} +``` + +## ベストプラクティス + +### 1. バージョン管理 + +- **ベースイメージ**: セマンティックバージョニング（例: `1.13.1`）を明示 +- **Features**: `latest`使用は最小限に、安定性重視の場合はバージョン固定 +- **更新頻度**: 四半期ごとにベースイメージ見直し + +### 2. パフォーマンス最適化 + +```json +{ + "mounts": [ + "source=${localWorkspaceFolderBasename}-node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume" + ] +} +``` + +- `node_modules`をボリュームマウントして高速化 + +### 3. セキュリティ + +- 機密情報は`.devcontainer.env`または1Passwordで管理 +- `.devcontainer.env`は`.gitignore`に追加必須 +- `runArgs`での環境変数直接埋め込みは禁止 + +### 4. チーム協調 + +```json +{ + "name": " Development", + "remoteUser": "vscode" +} +``` + +- プロジェクト名を明示してコンテナ識別性向上 + +## 移行ガイド + +### 古いバージョンからの更新手順 + +1. **ベースイメージ更新** + + ```json + - "image": "ghcr.io/keito4/config-base:1.0.40" + + "image": "ghcr.io/keito4/config-base:1.13.1" + ``` + +2. **非推奨Feature削除** + - 重複するFeature（config-baseに既に含まれるもの）を削除 + +3. **mounts標準化** + - 上記の標準mounts設定を適用 + +4. **動作確認** + + ```bash + # コンテナリビルド + Cmd/Ctrl + Shift + P → "Dev Containers: Rebuild Container" + + # 初期化コマンド実行確認 + # postCreateCommandが正常完了することを確認 + ``` + +## トラブルシューティング + +### よくある問題 + +1. **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" + +2. **Claude Code認証エラー** + - `ANTHROPIC_API_KEY`の値を確認 + - 1Passwordから最新のAPIキーを取得: `OP_ACCOUNT=your.1password.com bash script/setup-env.sh` + - 環境変数が正しく読み込まれているか確認: `echo $ANTHROPIC_API_KEY` + +3. **`.codex`や`.claude`の設定が反映されない** + - ホスト側でディレクトリが存在するか確認: `ls -la ~/.codex ~/.claude` + - ホスト側でディレクトリ作成: `mkdir -p ~/.codex ~/.claude` + - マウント設定がdevcontainer.jsonに正しく記載されているか確認 + - コンテナ再起動後も反映されない場合は、コンテナ再ビルド + +4. **postCreateCommandが失敗する** + - `|| true`を末尾に追加して継続実行 + - スクリプトの実行権限確認: `chmod +x scripts/*.sh` + - ログを確認: コンテナ起動ログでsetup-claude.shのエラーメッセージを確認 + +5. **mountsでPermission Denied** + - ホスト側でディレクトリ事前作成: `mkdir -p ~/.codex ~/.claude` + - ディレクトリのパーミッション確認: `ls -la ~/ | grep -E "codex|claude"` + +6. **Featuresのインストールが遅い** + - 不要なFeatureを削除 + - ベースイメージに含まれるものは重複指定しない + +## 参考リンク + +### DevContainer関連 + +- [DevContainers公式ドキュメント](https://containers.dev/) +- [config-base最新リリース](https://github.com/keito4/config/pkgs/container/config-base) +- [DevContainer Features検索](https://containers.dev/features) + +### Claude Code関連 + +- [Claude Code公式ドキュメント](https://docs.anthropic.com/claude/docs/claude-code) +- [Claude API Documentation](https://docs.anthropic.com/) +- 本リポジトリのClaude設定: [.claude/](./.claude/) および [.codex/](./.codex/) + +--- + +**更新日**: 2025-12-30 +**バージョン**: 1.0.0 +**メンテナ**: keito4 diff --git a/README.md b/README.md index b853f714..a1b21b59 100644 --- a/README.md +++ b/README.md @@ -568,6 +568,8 @@ The repository includes a complete DevContainer setup (`.devcontainer/`) that pr - Integrated Claude Code configuration with specialized agents and commands - Bell notification system for development workflow events +**DevContainer推奨設定**: Elu-co-jp配下のリポジトリで統一されたDevContainer環境を構築するための推奨設定とベストプラクティスについては、[.codex/devcontainer-recommendations.md](.codex/devcontainer-recommendations.md)を参照してください。 + ### Automated Releases This repository uses semantic-release for automated version management and releases based on commit messages. Follow conventional commit format: From 0a96bbcf7107eaee6e737efecbc3138578719f7e Mon Sep 17 00:00:00 2001 From: keito4 Date: Tue, 30 Dec 2025 17:43:51 +0900 Subject: [PATCH 2/2] docs: Add comprehensive MCP configuration section to DevContainer recommendations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add MCP (Model Context Protocol) setup guidelines - Document .mcp.json placement and priority order - Include security best practices for API key management - Add troubleshooting for o3 and Playwright MCP servers - Provide complete MCP configuration examples - Add MCP-related reference links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .codex/devcontainer-recommendations.md | 129 ++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 1 deletion(-) diff --git a/.codex/devcontainer-recommendations.md b/.codex/devcontainer-recommendations.md index 828c0b49..1aca517b 100644 --- a/.codex/devcontainer-recommendations.md +++ b/.codex/devcontainer-recommendations.md @@ -81,6 +81,75 @@ Claude Code（AI開発アシスタント）を動作させるための最小限 ANTHROPIC_API_KEY=*** ``` +### 5. MCP (Model Context Protocol) 設定 + +Claude CodeでMCPサーバーを利用する場合、`.mcp.json`の配置とマウントが必要です。 + +**推奨配置**: `.claude/.mcp.json`（Claude Codeが優先的に読み込む場所） + +#### `.mcp.json`の生成方法 + +```bash +# postCreateCommandで自動生成（推奨） +bash script/setup-mcp.sh +``` + +`setup-mcp.sh`は以下を実行： + +- `credentials/mcp.env`から環境変数を読み込み +- `.mcp.json.template`から`.mcp.json`を生成 +- ワークスペースルート（`/workspaces//.mcp.json`）に配置 + +#### MCP設定例（`.mcp.json`） + +```json +{ + "mcpServers": { + "o3": { + "type": "stdio", + "command": "npx", + "args": ["o3-search-mcp"], + "env": { + "OPENAI_API_KEY": "${OPENAI_API_KEY}" + } + }, + "playwright": { + "type": "stdio", + "command": "npx", + "args": ["@playwright/mcp@latest"], + "env": {} + } + } +} +``` + +#### 必須環境変数（`.devcontainer.env`） + +```bash +OPENAI_API_KEY=*** # o3 MCP用 +``` + +#### ⚠️ 重要な注意事項 + +1. **セキュリティ**: + - `.mcp.json`は`.gitignore`に追加必須 + - API KEYは環境変数テンプレート（`${OPENAI_API_KEY}`）を使用 + - 平文でのAPI KEY保存は避ける + +2. **配置場所の優先順位**: + - Claude Codeは以下の順で`.mcp.json`を探索： + 1. `.claude/.mcp.json`（推奨） + 2. `~/.claude/.mcp.json`（グローバル） + 3. ワークスペースルート（バージョン依存） + +#### MCP対応のpostCreateCommand + +```json +{ + "postCreateCommand": "bash script/setup-env.sh && bash script/setup-mcp.sh && /usr/local/bin/setup-claude.sh" +} +``` + ### Claude Code最小構成例 ```json @@ -93,7 +162,7 @@ ANTHROPIC_API_KEY=*** "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": "/usr/local/bin/setup-claude.sh", + "postCreateCommand": "bash script/setup-env.sh && bash script/setup-mcp.sh && /usr/local/bin/setup-claude.sh", "runArgs": ["--env-file=${localEnv:HOME}/.devcontainer.env"] } ``` @@ -455,6 +524,57 @@ NODE_ENV=development - 不要なFeatureを削除 - ベースイメージに含まれるものは重複指定しない +7. **MCPサーバーが動作しない** + - `.mcp.json`の存在確認: + ```bash + ls -la /workspaces//.mcp.json + ls -la ~/.claude/.mcp.json + ``` + - `.mcp.json`が生成されない場合: + - `credentials/mcp.env`が存在するか確認 + - `script/setup-env.sh`を先に実行 + - 手動で実行: `bash script/setup-mcp.sh` + - 環境変数が展開されているか確認: + ```bash + cat .mcp.json | grep OPENAI_API_KEY + # ${OPENAI_API_KEY}が残っている場合は未展開 + ``` + - 推奨: `.mcp.json`を`.claude/.mcp.json`にコピー: + ```bash + mkdir -p ~/.claude + cp .mcp.json ~/.claude/.mcp.json + ``` + +8. **o3 MCP（OpenAI検索）が使えない** + - `OPENAI_API_KEY`の設定確認: + ```bash + echo $OPENAI_API_KEY + ``` + - `credentials/mcp.env`に`OPENAI_API_KEY`が含まれているか確認 + - 1Passwordから取得: + ```bash + OP_ACCOUNT=your.1password.com bash script/setup-env.sh + ``` + - `.mcp.json`を再生成: + ```bash + bash script/setup-mcp.sh + ``` + +9. **Playwright MCPが動作しない** + - Node.jsとnpxが利用可能か確認: + ```bash + node --version + npx --version + ``` + - Playwrightパッケージをグローバルインストール: + ```bash + npm install -g @playwright/mcp@latest + ``` + - ブラウザのインストール: + ```bash + npx playwright install + ``` + ## 参考リンク ### DevContainer関連 @@ -469,6 +589,13 @@ NODE_ENV=development - [Claude API Documentation](https://docs.anthropic.com/) - 本リポジトリのClaude設定: [.claude/](./.claude/) および [.codex/](./.codex/) +### MCP (Model Context Protocol) 関連 + +- [MCP公式ドキュメント](https://modelcontextprotocol.io/) +- [Playwright MCP](https://github.com/microsoft/playwright-mcp) +- [o3 Search MCP](https://www.npmjs.com/package/o3-search-mcp) +- 本リポジトリのMCP設定: [.mcp.json.template](./.mcp.json.template) および [credentials/templates/mcp.env.template](./credentials/templates/mcp.env.template) + --- **更新日**: 2025-12-30