container-use 環境構築ガイド

container-useを使用したクローズドな開発・テスト環境の構築手順です。

概要

container-useは、Dockerコンテナ内で開発・テストを行うためのツール群です。

メリット:

• ローカル環境を汚さない
• 再現可能な環境
• DB等のサービスを安全にテスト
• チーム間で同一環境を共有
• 複数Issueの並行作業が可能（環境分離）

⚠️ 必須ルール

実装作業は原則としてcontainer-use環境で行うこと。ホスト環境での直接実装は禁止。

例外については implement-issues.md の「プラットフォーム固有コード」セクションを参照。

🔀 並行作業ガイドライン

なぜcontainer-use環境が必須か

複数のIssueを同時に処理する場合、ホスト環境では以下の問題が発生します：

| 問題 | 影響 | |------|------| | ブランチ切り替え | 未コミット変更の退避が必要 | | 依存関係の競合 | lockファイルの変更がぶつかる | | ビルドキャッシュ | 異なるブランチの成果物が混在 | | 作業状態の保持 | 中断時に状態を失う |

container-use環境による解決

┌─────────────────────────────────────────────────────┐
│ ホスト環境 (読み取り専用)                              │
│  - gh issue/pr 操作のみ許可                          │
│  - ファイル編集禁止                                   │
└─────────────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
┌─────────────────┐  ┌─────────────────┐
│ 環境A (Issue#42)│  │ 環境B (Issue#43)│
│ env_id: abc-123 │  │ env_id: def-456 │
│                 │  │                 │
│ ブランチ:        │  │ ブランチ:        │
│ feature/42-auth │  │ feature/43-pay  │
│                 │  │                 │
│ 状態: active    │  │ 状態: active    │
└─────────────────┘  └─────────────────┘
         │                    │
         ▼                    ▼
    独立した作業           独立した作業
    （競合なし）           （競合なし）

並行作業のベストプラクティス

| ルール | 説明 | |--------|------| | 1 Issue = 1 環境 | 必ずIssueごとに環境を作成 | | 環境IDを記録 | GitHub Issue のメタデータで追跡 | | 作業再開時は既存環境を使用 | 毎回新規作成しない | | PRマージ後に環境削除 | リソース節約 |

🍎 プラットフォーム固有コードの制約

container-use環境はLinuxコンテナのため、macOS/Windows固有APIはコンテナ内でビルド/テスト不可です。

詳細: プラットフォーム例外ポリシー を参照

---

基本フロー

flowchart LR
    LIST[環境一覧確認] --> EXISTS{既存環境?}
    EXISTS -->|あり| OPEN[環境を開く]
    EXISTS -->|なし| CREATE[環境を作成]
    CREATE --> CONFIG[環境設定]
    CONFIG --> SERVICE{サービス必要?}
    OPEN --> SERVICE
    SERVICE -->|はい| ADD[サービス追加]
    SERVICE -->|いいえ| WORK
    ADD --> WORK[作業開始]

ツール一覧

| ツール | 用途 | |--------|------| | container-use_environment_list | 既存環境の一覧取得 | | container-use_environment_create | 新規環境の作成 | | container-use_environment_open | 既存環境を開く | | container-use_environment_config | 環境設定 (base image, setup commands) | | container-use_environment_add_service | サービス追加 (DB, Redis等) | | container-use_environment_run_cmd | コマンド実行 | | container-use_environment_file_read | ファイル読み取り | | container-use_environment_file_write | ファイル書き込み | | container-use_environment_file_edit | ファイル編集 | | container-use_environment_file_list | ディレクトリ一覧 | | container-use_environment_checkpoint | 環境のスナップショット保存 |

環境構築手順

Step 1: 既存環境の確認

container-use_environment_list(
    environment_source="/path/to/repo",
    explanation="Check existing environments for this project"
)

Step 2: 環境の作成または再利用

新規作成の場合

result = container-use_environment_create(
    environment_source="/path/to/repo",
    title="Issue #123 - User Authentication Feature",
    explanation="Create dev environment for auth feature"
)
env_id = result.environment_id

既存環境を開く場合

container-use_environment_open(
    environment_source="/path/to/repo",
    environment_id="existing-env-id",
    explanation="Reopen existing environment"
)

Step 3: 環境設定

プロジェクトの技術スタックに応じて設定:

container-use_environment_config(
    environment_source="/path/to/repo",
    environment_id=env_id,
    config={
        "base_image": "node:20-slim",
        "setup_commands": [
            "npm ci",
            "npm run build"
        ],
        "envs": [
            "NODE_ENV=test",
            "LOG_LEVEL=debug"
        ]
    },
    explanation="Configure Node.js environment with dependencies"
)

Step 4: サービス追加 (必要に応じて)

詳細な設定例: {{skill:tech-stack-configs}} を参照

| サービス | image | ポート | |---------|-------|--------| | PostgreSQL | postgres:15-alpine | 5432 | | MySQL | mysql:8 | 3306 | | Redis | redis:7-alpine | 6379 |

container-use_environment_add_service(
    environment_source="/path/to/repo",
    environment_id=env_id,
    name="postgres",  # サービス名 = ホスト名
    image="postgres:15-alpine",
    envs=["POSTGRES_USER=app", "POSTGRES_PASSWORD=password", "POSTGRES_DB=testdb"],
    ports=[5432],
    explanation="Add PostgreSQL for database tests"
)

コマンド実行

基本コマンド

container-use_environment_run_cmd(
    environment_source="/path/to/repo",
    environment_id=env_id,
    command="npm test",
    explanation="Run test suite"
)

バックグラウンド実行 (サーバー起動等)

container-use_environment_run_cmd(
    environment_source="/path/to/repo",
    environment_id=env_id,
    command="npm run dev",
    background=True,
    ports=[3000],
    explanation="Start dev server in background"
)

シェル指定

container-use_environment_run_cmd(
    environment_source="/path/to/repo",
    environment_id=env_id,
    command="source .env && npm test",
    shell="bash",
    explanation="Run with bash to source env file"
)

ファイル操作

ファイル読み取り

container-use_environment_file_read(
    environment_source="/path/to/repo",
    environment_id=env_id,
    target_file="src/index.ts",
    should_read_entire_file=True,
    explanation="Read source file"
)

ファイル書き込み

container-use_environment_file_write(
    environment_source="/path/to/repo",
    environment_id=env_id,
    target_file="src/feature.ts",
    contents="export const feature = () => { ... }",
    explanation="Write new feature file"
)

ファイル編集

container-use_environment_file_edit(
    environment_source="/path/to/repo",
    environment_id=env_id,
    target_file="src/index.ts",
    search_text="old code",
    replace_text="new code",
    explanation="Update import statement"
)

技術スタック別設定例

詳細: {{skill:tech-stack-configs}} を参照

| 技術スタック | base_image | 主な設定 | |-------------|-----------|---------| | Node.js/TypeScript | node:20-slim | npm ci, Playwright対応 | | Python/FastAPI | python:3.11-slim | pip install -r requirements.txt | | Go | golang:1.21-alpine | go mod download, migrate対応 | | Rust | rust:1.85-slim | cargo fetch, cargo build |

DBマイグレーションのテスト

詳細: {{skill:tech-stack-configs}} を参照

| ORM/ツール | マイグレーション | ロールバック | |-----------|----------------|-------------| | Flyway | flyway migrate | flyway undo | | Prisma | npx prisma migrate deploy | npx prisma migrate reset | | Alembic | alembic upgrade head | alembic downgrade -1 |

トラブルシューティング

Docker障害時のフォールバック

Diagnosis Commands:

docker system df     # Check disk usage
df -h                # Check available disk space
docker info          # Check daemon status

Decision Tree:

| Condition | Action | |-----------|--------| | Disk space < 10GB | docker system prune -af and retry | | Docker daemon not running | Start Docker Desktop, wait 30s, retry | | After prune still failing | User escalation required |

User Escalation (MANDATORY):

When container-use cannot function:

1. Report the failure clearly:

   ⚠️ Container-use is unavailable due to: [specific error]
   
   Attempted recovery:
   - [action 1]: [result]
   - [action 2]: [result]
   

2. Present options:

   Options:
   A) Wait for Docker recovery (manual intervention needed)
   B) Proceed with direct host operations (breaks isolation)
   C) Abort and resume later
   
   Which would you prefer?
   

3. If user chooses direct host operations:

   • Commit message: [non-containerized]
   • Add warning comment to changed files
   • Create follow-up issue to verify in container

CRITICAL: Never silently fall back. Always get explicit user approval.

セッション復旧の詳細手順: container-useエージェントルール を参照

サービスに接続できない

1. サービス名をホスト名として使用 (例: postgres, redis)
2. ポートが正しいか確認
3. サービスの起動を待つ（{{skill:tech-stack-configs}} の「サービス起動待機」参照）

依存関係のインストールに失敗

1. base imageを確認
2. setup_commandsの順序を確認
3. 必要なシステムパッケージを追加（{{skill:tech-stack-configs}} の「ネイティブモジュール対応」参照）

環境が重い

1. slimイメージを使用
2. 不要なdevDependenciesを除外
3. マルチステージビルドを検討

ベストプラクティス

1. 環境の再利用: 同じIssueの作業には同じ環境を使う
2. サービス名の統一: postgres, redis, mysql など分かりやすい名前を使う
3. 環境変数の活用: 接続情報は環境変数で管理
4. チェックポイント: 安定した状態でスナップショットを保存
5. クリーンアップ: 不要になった環境は削除

環境ID管理 (GitHub Issue)

PRレビュー後の修正作業で環境を再利用するため、環境IDをGitHub Issueで追跡します。

詳細: GitHub Issue状態管理 を参照

状態追跡

| ラベル | 説明 | |--------|------| | env:active | 作業中 | | env:blocked | 人間の介入が必要 | | env:pr-created | PR作成済み | | env:merged | マージ完了 |

メリット: container-use/worktree/ホスト環境のどこからでも gh CLI でアクセス可能。