---
name: container-use-guide
description: container-useを使用したクローズドな開発・テスト環境の構築手順、並行作業ガイドライン、技術スタック別設定例を提供
---

# container-use 環境構築ガイド

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

## 概要

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

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

## ⚠️ 必須ルール

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

例外については [implement-issues.md](../../command/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はコンテナ内でビルド/テスト不可です。

> **詳細**: [プラットフォーム例外ポリシー](../../instructions/platform-exception.md) を参照

---

## 基本フロー

```mermaid
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: 既存環境の確認

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

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

#### 新規作成の場合

```python
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
```

#### 既存環境を開く場合

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

### Step 3: 環境設定

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

```python
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 |

```python
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"
)
```

## コマンド実行

### 基本コマンド

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

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

```python
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"
)
```

### シェル指定

```python
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"
)
```

## ファイル操作

### ファイル読み取り

```python
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"
)
```

### ファイル書き込み

```python
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"
)
```

### ファイル編集

```python
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:**

```bash
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エージェントルール](../../instructions/container-use.md) を参照

### サービスに接続できない

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状態管理](../github-issue-state-management/SKILL.md) を参照

### 状態追跡

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

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