feat: Migrate from Makefile/venv to Dev Container development

- Add comprehensive Dev Container configuration for VS Code
- Create Docker-based development environment with all dependencies
- Add VS Code tasks and launch configurations for integrated development
- Update documentation to prioritize Dev Container workflow
- Maintain Makefile compatibility for legacy support
- Add migration guide for developers switching from venv setup

Benefits:
- Zero-setup development environment
- Consistent environment across all developers
- Integrated VS Code debugging and testing
- Docker volume persistence for data and VOICEVOX models
- Automatic dependency and VOICEVOX Core installation

Files added:
- .devcontainer/ - Complete Dev Container setup
- .vscode/ - VS Code tasks and launch configurations
- MIGRATION.md - Migration guide from Makefile/venv
- docker-compose.dev.yml - Alternative docker-compose setup

.devcontainer/Dockerfile

@@ -0,0 +1,54 @@
+# Development container for Yomitalk
+FROM python:3.11-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    wget \
+    make \
+    build-essential \
+    ffmpeg \
+    sudo \
+    # For playwright browsers
+    libnss3 \
+    libatk-bridge2.0-0 \
+    libdrm2 \
+    libxkbcommon0 \
+    libgtk-3-0 \
+    libgbm1 \
+    libasound2 \
+    # For VS Code development
+    ca-certificates \
+    gnupg \
+    lsb-release \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create vscode user for development
+RUN groupadd --gid 1000 vscode \
+    && useradd --uid 1000 --gid vscode --shell /bin/bash --create-home vscode \
+    && echo 'vscode ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+
+# Set up working directory
+WORKDIR /workspace
+
+# Install Python development tools globally (no venv needed in container)
+COPY requirements.in requirements-lint.txt ./
+RUN pip install --upgrade pip && \
+    pip install --timeout 600 --retries 5 torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu && \
+    pip install --timeout 300 --retries 3 -r requirements-lint.txt
+
+# Install pip-tools for requirements management
+RUN pip install pip-tools
+
+# Switch to vscode user
+USER vscode
+
+# Set environment variables for development
+ENV PYTHONPATH=/workspace
+ENV VOICEVOX_ACCEPT_AGREEMENT=true
+ENV PAGER=cat
+ENV LESSCHARSET=utf-8
+
+# Default command (will be overridden by devcontainer)
+CMD ["sleep", "infinity"]

.devcontainer/README.md

@@ -0,0 +1,221 @@
+# Yomitalk Development Container
+
+This directory contains the development container configuration for Yomitalk, enabling a consistent and reproducible development environment using VS Code Dev Containers.
+
+## Quick Start
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [VS Code](https://code.visualstudio.com/)
+- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+### Getting Started
+
+1. **Clone the repository:**
+   ```bash
+   git clone <repository-url>
+   cd yomitalk
+   ```
+
+2. **Open in VS Code:**
+   ```bash
+   code .
+   ```
+
+3. **Open in Dev Container:**
+   - Press `F1` and select "Dev Containers: Reopen in Container"
+   - Or click the popup notification to reopen in container
+   - Wait for the container to build and setup to complete
+
+4. **Start developing:**
+   - The environment will be automatically configured
+   - VOICEVOX Core will be downloaded and installed
+   - All Python dependencies will be installed
+   - Pre-commit hooks will be configured
+
+## Development Workflow
+
+### Running the Application
+
+```bash
+# Run the Yomitalk web application
+python app.py
+
+# Or use VS Code task (Ctrl+Shift+P -> "Tasks: Run Task" -> "Run Yomitalk App")
+```
+
+The application will be available at `http://localhost:7860`
+
+### Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run unit tests only
+pytest tests/unit/
+
+# Run E2E tests only
+E2E_TEST_MODE=true pytest tests/e2e/
+
+# Use VS Code tasks for better integration
+```
+
+### Code Quality
+
+```bash
+# Format code
+black . && isort .
+
+# Run linting
+flake8 . && mypy .
+
+# Run pre-commit hooks
+pre-commit run --all-files
+```
+
+### Common Commands
+
+| Task | Command | VS Code Task |
+|------|---------|-------------|
+| Run app | `python app.py` | "Run Yomitalk App" |
+| All tests | `pytest tests/` | "Run All Tests" |
+| Unit tests | `pytest tests/unit/` | "Run Unit Tests" |
+| E2E tests | `E2E_TEST_MODE=true pytest tests/e2e/` | "Run E2E Tests" |
+| Format | `black . && isort .` | "Format Code" |
+| Lint | `flake8 . && mypy .` | "Run Linting" |
+| Pre-commit | `pre-commit run --all-files` | "Run Pre-commit" |
+
+## Container Architecture
+
+### Base Image
+- **Python 3.11 slim**: Official Python image for consistent Python environment
+- **System packages**: FFmpeg, build tools, and browser dependencies for Playwright
+
+### Development Features
+- **Non-root user**: `vscode` user for security and VS Code integration
+- **Persistent volumes**: Separate volumes for data and VOICEVOX models
+- **Port forwarding**: Automatic port 7860 forwarding for web access
+- **Extensions**: Pre-configured VS Code extensions for Python development
+
+### File Structure
+
+```
+.devcontainer/
+├── devcontainer.json    # Main configuration file
+├── docker-compose.yml   # Multi-service container setup
+├── Dockerfile          # Development container image
+├── setup.sh            # Post-creation setup script
+└── README.md           # This file
+```
+
+## Customization
+
+### Adding Extensions
+
+Edit `.devcontainer/devcontainer.json`:
+
+```json
+{
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "existing-extensions...",
+        "new.extension.id"
+      ]
+    }
+  }
+}
+```
+
+### Environment Variables
+
+Add to `containerEnv` in `devcontainer.json`:
+
+```json
+{
+  "containerEnv": {
+    "NEW_VAR": "value"
+  }
+}
+```
+
+### System Packages
+
+Edit `.devcontainer/Dockerfile` and add to the `RUN apt-get install` command.
+
+## Troubleshooting
+
+### Container Build Issues
+
+1. **Clean rebuild:**
+   ```bash
+   # Remove container and rebuild
+   # In VS Code: "Dev Containers: Rebuild Container"
+   ```
+
+2. **VOICEVOX download fails:**
+   ```bash
+   # Manually run setup in container terminal
+   bash .devcontainer/setup.sh
+   ```
+
+3. **Permission issues:**
+   ```bash
+   # Fix ownership (run in container terminal)
+   sudo chown -R vscode:vscode /workspace
+   ```
+
+### Performance Issues
+
+1. **Slow file access:**
+   - Ensure using volume mounts for large directories (data, voicevox_core)
+   - Check Docker Desktop resource allocation
+
+2. **Memory issues:**
+   - Increase Docker Desktop memory limit
+   - VOICEVOX and ML models require significant RAM
+
+### Network Issues
+
+1. **Port forwarding not working:**
+   - Check VS Code port forwarding tab
+   - Ensure application binds to `0.0.0.0:7860`, not `localhost:7860`
+
+2. **Internet access for downloads:**
+   - Check Docker network configuration
+   - Verify proxy settings if behind corporate firewall
+
+## Migration from Makefile/venv
+
+### Key Changes
+
+- **No virtual environment**: Python packages installed globally in container
+- **No make commands**: Use VS Code tasks or direct commands
+- **Persistent data**: Data and models stored in Docker volumes
+- **Integrated tools**: Linting, formatting, and testing integrated with VS Code
+
+### Old vs New Commands
+
+| Old (Makefile) | New (Devcontainer) |
+|----------------|-------------------|
+| `make setup` | Automatic via `postCreateCommand` |
+| `make run` | `python app.py` or VS Code task |
+| `make test` | `pytest tests/` or VS Code task |
+| `make lint` | `flake8 . && mypy .` or VS Code task |
+| `make format` | `black . && isort .` or VS Code task |
+| `make clean` | "Dev Containers: Rebuild Container" |
+
+## Benefits
+
+### Developer Experience
+- **Zero setup**: One-click development environment
+- **Consistency**: Same environment across all developers
+- **Isolation**: No conflicts with host system packages
+- **Integration**: Deep VS Code integration with debugging, testing, and formatting
+
+### CI/CD Alignment
+- **Same base**: Development and production environments share base image
+- **Reproducible**: Exact same dependencies and versions
+- **Testable**: E2E tests run in similar environment to production

.devcontainer/devcontainer.json

@@ -0,0 +1,97 @@
+{
+  "name": "Yomitalk Development Environment",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "yomitalk-dev",
+  "workspaceFolder": "/workspace",
+  "shutdownAction": "stopCompose",
+
+  // Features to add to the dev container. More info: https://containers.dev/features.
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "latest",
+      "ppa": true
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "latest"
+    }
+  },
+
+  // Configure tool-specific properties.
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.defaultInterpreterPath": "/usr/local/bin/python",
+        "python.terminal.activateEnvironment": false,
+        "python.linting.enabled": true,
+        "python.linting.pylintEnabled": false,
+        "python.linting.flake8Enabled": true,
+        "python.linting.mypyEnabled": true,
+        "python.formatting.provider": "black",
+        "python.sortImports.provider": "isort",
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": [
+          "tests/"
+        ],
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+          "source.organizeImports": true
+        },
+        "files.exclude": {
+          "**/__pycache__": true,
+          "**/.pytest_cache": true,
+          "**/data/temp": true,
+          "**/data/output": true,
+          "**/voicevox_core": true
+        },
+        "git.enableCommitSigning": false,
+        "terminal.integrated.defaultProfile.linux": "bash"
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.flake8",
+        "ms-python.mypy-type-checker",
+        "ms-python.black-formatter",
+        "ms-python.isort",
+        "ms-toolsai.jupyter",
+        "wholroyd.jinja",
+        "redhat.vscode-yaml",
+        "ms-vscode.makefile-tools",
+        "GitHub.copilot",
+        "GitHub.copilot-chat",
+        "ms-playwright.playwright",
+        "ms-vscode.test-adapter-converter",
+        "littlefoxteam.vscode-python-test-adapter",
+        "streetsidesoftware.code-spell-checker"
+      ]
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [7860],
+  "portsAttributes": {
+    "7860": {
+      "label": "Yomitalk Web App",
+      "onAutoForward": "notify"
+    }
+  },
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  "postCreateCommand": "bash .devcontainer/setup.sh",
+
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "vscode",
+
+  // Environment variables
+  "containerEnv": {
+    "VOICEVOX_ACCEPT_AGREEMENT": "true",
+    "PAGER": "cat",
+    "LESSCHARSET": "utf-8",
+    "E2E_TEST_MODE": "false"
+  },
+
+  // Mounts for persistent data
+  "mounts": [
+    "source=yomitalk-data,target=/workspace/data,type=volume",
+    "source=yomitalk-voicevox,target=/workspace/voicevox_core,type=volume"
+  ]
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,29 @@
+version: '3.8'
+
+services:
+  yomitalk-dev:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    volumes:
+      - ..:/workspace:cached
+      - yomitalk-data:/workspace/data
+      - yomitalk-voicevox:/workspace/voicevox_core
+    environment:
+      - VOICEVOX_ACCEPT_AGREEMENT=true
+      - PAGER=cat
+      - LESSCHARSET=utf-8
+      - E2E_TEST_MODE=false
+    ports:
+      - "7860:7860"
+    # Keep container running for development
+    command: sleep infinity
+    # Add capabilities for audio processing if needed
+    cap_add:
+      - SYS_PTRACE
+    security_opt:
+      - seccomp:unconfined
+
+volumes:
+  yomitalk-data:
+  yomitalk-voicevox:

.devcontainer/setup.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Post-create setup script for Yomitalk devcontainer
+set -e
+
+echo "🚀 Setting up Yomitalk development environment..."
+
+# Install Python dependencies
+echo "📦 Installing Python dependencies..."
+pip install --timeout 300 --retries 3 -r requirements.txt
+
+# Install VOICEVOX Core if not already present
+if [ ! -d "voicevox_core" ] || [ -z "$(ls -A voicevox_core 2>/dev/null)" ]; then
+    echo "🎤 Setting up VOICEVOX Core..."
+    chmod +x scripts/download_voicevox.sh
+    scripts/download_voicevox.sh \
+        --version 0.16.0 \
+        --dir voicevox_core \
+        --skip-if-exists \
+        --accept-agreement
+fi
+
+# Install VOICEVOX Core Python module
+echo "🐍 Installing VOICEVOX Core Python module..."
+OS_TYPE="manylinux_2_34_x86_64"
+VOICEVOX_VERSION="0.16.0"
+WHEEL_URL="https://github.com/VOICEVOX/voicevox_core/releases/download/${VOICEVOX_VERSION}/voicevox_core-${VOICEVOX_VERSION}-cp310-abi3-${OS_TYPE}.whl"
+pip install "${WHEEL_URL}" || echo "⚠️  Warning: Failed to install VOICEVOX Core wheel. You may need to install it manually."
+
+# Install playwright browsers for E2E testing
+echo "🎭 Installing Playwright browsers for E2E testing..."
+playwright install || echo "⚠️  Warning: Failed to install Playwright browsers."
+
+# Set up pre-commit hooks
+echo "🔧 Setting up pre-commit hooks..."
+pre-commit install || echo "⚠️  Warning: Failed to install pre-commit hooks."
+
+# Create necessary directories with proper permissions
+echo "📁 Creating data directories..."
+mkdir -p data/temp data/output data/logs
+chmod -R 755 data
+
+# Ensure git configuration
+echo "⚙️  Configuring git..."
+git config --global --add safe.directory /workspace
+
+echo "✅ Yomitalk development environment setup complete!"
+echo ""
+echo "🎯 Quick start commands:"
+echo "  • Run app:           python app.py"
+echo "  • Run tests:         pytest tests/"
+echo "  • Run unit tests:    pytest tests/unit/"
+echo "  • Run E2E tests:     E2E_TEST_MODE=true pytest tests/e2e/"
+echo "  • Format code:       black . && isort ."
+echo "  • Run linting:       flake8 . && mypy ."
+echo "  • Run pre-commit:    pre-commit run --all-files"
+echo ""

.gitignore

@@ -17,16 +17,22 @@ __pycache__/
 venv/
 ENV/
 
-# IDE
+# IDE関連
 .idea/
-.vscode/
+.vscode/settings.json  # User-specific settings only
 *.swp
 *.swo
-.vscode/settings.json
+
+# Dev Container
+.devcontainer/.env
 
 # Project specific
 data/temp/*
 data/output/*
+data/logs/*
+!data/temp/.gitkeep
+!data/output/.gitkeep
+!data/logs/.gitkeep
 voicevox_core/
 *.log
 .env
@@ -37,20 +43,6 @@ voicevox_core/
 htmlcov/
 tests/e2e/screenshots/
 
-# データ・キャッシュディレクトリ
-data/temp/*
-data/output/*
-data/logs/*
-!data/temp/.gitkeep
-!data/output/.gitkeep
-!data/logs/.gitkeep
-
-# IDE関連
-.idea/
-.vscode/
-*.swp
-*.swo
-
 # システム関連
 .DS_Store
 Thumbs.db
@@ -60,8 +52,5 @@ build/
 dist/
 *.spec
 
-# VOICEVOX Core
-voicevox_core/
-
 # その他の一時ファイル
 *.png

.vscode/launch.json

@@ -0,0 +1,55 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Run Yomitalk App",
+            "type": "python",
+            "request": "launch",
+            "program": "app.py",
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}",
+                "VOICEVOX_ACCEPT_AGREEMENT": "true"
+            },
+            "args": ["--debug"]
+        },
+        {
+            "name": "Debug Unit Tests",
+            "type": "python",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["tests/unit/", "-v", "--tb=short"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        },
+        {
+            "name": "Debug E2E Tests",
+            "type": "python",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["tests/e2e/", "-v", "--tb=short"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}",
+                "E2E_TEST_MODE": "true"
+            }
+        },
+        {
+            "name": "Debug Current Test File",
+            "type": "python",
+            "request": "launch",
+            "module": "pytest",
+            "args": ["${file}", "-v", "--tb=short"],
+            "console": "integratedTerminal",
+            "cwd": "${workspaceFolder}",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

.vscode/tasks.json

@@ -0,0 +1,140 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Run Yomitalk App",
+            "type": "shell",
+            "command": "python",
+            "args": ["app.py"],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run All Tests",
+            "type": "shell",
+            "command": "pytest",
+            "args": ["tests/", "--durations=10"],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run Unit Tests",
+            "type": "shell",
+            "command": "pytest",
+            "args": ["tests/unit/", "--durations=10"],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run E2E Tests",
+            "type": "shell",
+            "command": "pytest",
+            "args": ["tests/e2e/", "--durations=10"],
+            "group": "test",
+            "env": {
+                "E2E_TEST_MODE": "true"
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Format Code",
+            "type": "shell",
+            "command": "bash",
+            "args": ["-c", "black . && isort . && autoflake --in-place --remove-unused-variables --remove-all-unused-imports --recursive ."],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run Linting",
+            "type": "shell",
+            "command": "bash",
+            "args": ["-c", "flake8 . && mypy ."],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": [
+                "$flake8",
+                "$mypy-python"
+            ]
+        },
+        {
+            "label": "Run Pre-commit",
+            "type": "shell",
+            "command": "pre-commit",
+            "args": ["run", "--all-files"],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Compile Requirements",
+            "type": "shell",
+            "command": "pip-compile",
+            "args": ["-v", "requirements.in"],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Install VOICEVOX Core",
+            "type": "shell",
+            "command": "bash",
+            "args": ["scripts/download_voicevox.sh", "--version", "0.16.0", "--dir", "voicevox_core", "--accept-agreement"],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "problemMatcher": []
+        }
+    ]
+}

CLAUDE.md

@@ -12,35 +12,55 @@ Before working on this codebase, **read [docs/design.md](docs/design.md)** for c
 
 ## Essential Commands
 
-### Setup and Environment
+### Dev Container Setup (Recommended)
+
+**Open in VS Code Dev Container:**
+- Press `F1` → "Dev Containers: Reopen in Container"
+- Automatic setup: dependencies, VOICEVOX Core, pre-commit hooks
+
+**Development Commands:**
+```bash
+python app.py                    # Start the Gradio application on port 7860
+pytest tests/                    # Run all tests (unit + E2E)
+pytest tests/unit/               # Run unit tests only
+E2E_TEST_MODE=true pytest tests/e2e/  # Run E2E tests
+flake8 . && mypy .              # Run static analysis
+black . && isort .              # Auto-format code
+pre-commit run --all-files      # Run pre-commit hooks manually
+```
+
+**VS Code Integration:** Use `Ctrl+Shift+P` → "Tasks: Run Task" for GUI access to all commands
+
+### Traditional Setup (Legacy)
+
+<details>
+<summary>Makefile/venv commands (still supported)</summary>
+
 ```bash
+# Setup and Environment
 make setup              # Complete setup: deps, VOICEVOX, lint tools, pre-commit
 make venv              # Create virtual environment only
 make install           # Install Python packages only
 make download-voicevox-core  # Download VOICEVOX Core for audio generation
-```
 
-### Development
-```bash
+# Development
 make run               # Start the Gradio application on port 7860
 make lint              # Run flake8 and mypy static analysis
 make format            # Auto-format code with black, isort, autoflake, autopep8
-```
 
-### Testing
-```bash
+# Testing
 make test              # Run all tests (unit + E2E)
 make test-unit         # Run unit tests only
 make test-e2e          # Run E2E tests (sets E2E_TEST_MODE=true)
 make test-staged       # Run tests only for staged files
-```
 
-### Pre-commit Hooks
-```bash
+# Pre-commit Hooks
 make pre-commit-install  # Install pre-commit hooks
 make pre-commit-run     # Run pre-commit hooks manually
 ```
 
+</details>
+
 ## Architecture Overview
 
 **📋 For detailed architecture information, see [docs/design.md](docs/design.md)**

MIGRATION.md

@@ -0,0 +1,215 @@
+# Migration Guide: Makefile/venv → Dev Containers
+
+This guide helps you migrate from the traditional Makefile/venv setup to the new Dev Container development environment.
+
+## Why Migrate?
+
+### Benefits of Dev Containers
+- **Zero setup**: One-click development environment
+- **Consistency**: Same environment across all developers and CI/CD
+- **Isolation**: No conflicts with host system packages
+- **VS Code integration**: Seamless debugging, testing, and development tools
+- **Docker alignment**: Development environment matches production container
+
+### Before (Makefile/venv)
+```bash
+make setup           # Manual setup required
+source venv/bin/activate  # Manual activation
+make run            # Run commands
+```
+
+### After (Dev Container)
+```bash
+# Just open in VS Code and reopen in container
+# Everything is automatic!
+python app.py       # Direct commands
+```
+
+## Migration Steps
+
+### 1. Prerequisites
+
+Install required tools:
+- [Docker](https://docs.docker.com/get-docker/)
+- [VS Code](https://code.visualstudio.com/)
+- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+### 2. Clean Up Old Environment (Optional)
+
+If you want to start fresh:
+
+```bash
+# Clean up old virtual environment and generated files
+make clean
+
+# Or manually:
+rm -rf venv/
+rm -rf data/temp/* data/output/*
+rm -rf __pycache__ .pytest_cache
+```
+
+### 3. Open in Dev Container
+
+1. **Open VS Code:**
+   ```bash
+   code .
+   ```
+
+2. **Reopen in Container:**
+   - Press `F1`
+   - Type "Dev Containers: Reopen in Container"
+   - Select the command
+   - Wait for container to build and setup to complete
+
+3. **First-time setup:**
+   - Container builds automatically (5-10 minutes first time)
+   - VOICEVOX Core downloads automatically
+   - All dependencies install automatically
+   - Pre-commit hooks setup automatically
+
+### 4. Verify Setup
+
+Test that everything works:
+
+```bash
+# Run the application
+python app.py
+
+# Run tests
+pytest tests/
+
+# Check linting
+flake8 . && mypy .
+```
+
+### 5. Update Your Workflow
+
+#### Old Workflow
+```bash
+source venv/bin/activate  # Activate environment
+make run                  # Run application
+make test                 # Run tests
+make lint                 # Run linting
+make format               # Format code
+deactivate               # Deactivate environment
+```
+
+#### New Workflow
+```bash
+# No activation needed - just use commands directly
+python app.py            # Run application
+pytest tests/            # Run tests
+flake8 . && mypy .       # Run linting
+black . && isort .       # Format code
+
+# Or use VS Code tasks:
+# Ctrl+Shift+P → "Tasks: Run Task" → Select task
+```
+
+## Command Mapping
+
+| Old (Make) | New (Direct) | VS Code Task |
+|------------|--------------|-------------|
+| `make setup` | Automatic via devcontainer | N/A |
+| `make run` | `python app.py` | "Run Yomitalk App" |
+| `make test` | `pytest tests/` | "Run All Tests" |
+| `make test-unit` | `pytest tests/unit/` | "Run Unit Tests" |
+| `make test-e2e` | `E2E_TEST_MODE=true pytest tests/e2e/` | "Run E2E Tests" |
+| `make lint` | `flake8 . && mypy .` | "Run Linting" |
+| `make format` | `black . && isort .` | "Format Code" |
+| `make pre-commit-run` | `pre-commit run --all-files` | "Run Pre-commit" |
+| `make clean` | "Dev Containers: Rebuild Container" | N/A |
+
+## VS Code Integration
+
+### Tasks
+Access via `Ctrl+Shift+P` → "Tasks: Run Task":
+- Run Yomitalk App
+- Run All Tests
+- Run Unit Tests
+- Run E2E Tests
+- Format Code
+- Run Linting
+- Run Pre-commit
+
+### Debugging
+- **F5**: Debug current configuration
+- **Ctrl+F5**: Run without debugging
+- Configurations available for app, unit tests, E2E tests
+
+### Extensions
+Automatically installed and configured:
+- Python
+- Black Formatter
+- isort
+- Flake8
+- MyPy Type Checker
+- Jupyter
+- Jinja
+- Playwright
+
+## Troubleshooting
+
+### Container Won't Start
+1. Ensure Docker is running
+2. Check Docker Desktop has enough resources (4GB+ RAM recommended)
+3. Try "Dev Containers: Rebuild Container"
+
+### VOICEVOX Download Fails
+```bash
+# Run setup script manually in container terminal
+bash .devcontainer/setup.sh
+```
+
+### Port 7860 Not Accessible
+1. Check VS Code port forwarding tab
+2. Ensure app binds to `0.0.0.0:7860`, not `localhost:7860`
+3. Check firewall settings
+
+### Slow Performance
+1. Use Docker volumes for large directories (already configured)
+2. Increase Docker Desktop resource allocation
+3. Consider using WSL2 backend on Windows
+
+### Permission Issues
+```bash
+# In container terminal
+sudo chown -R vscode:vscode /workspace
+```
+
+## Keeping Both Approaches
+
+You can use both approaches simultaneously:
+
+### Dev Container (Recommended)
+- Daily development
+- Debugging and testing
+- Code review and collaboration
+
+### Makefile (Backup)
+- CI/CD environments without container support
+- Quick local testing
+- Legacy system compatibility
+
+The Makefile is still maintained and functional for those who prefer it or need it for specific scenarios.
+
+## Getting Help
+
+- **Dev Container Issues**: See `.devcontainer/README.md`
+- **Application Issues**: See main `README.md`
+- **Architecture Questions**: See `docs/design.md`
+- **Development Guidelines**: See `CLAUDE.md`
+
+## Benefits You'll Notice
+
+### Immediate
+- No more virtual environment management
+- Consistent Python environment
+- Pre-configured development tools
+- Integrated VS Code experience
+
+### Long-term
+- Same environment across team members
+- Easier onboarding for new developers
+- Better CI/CD environment alignment
+- Simplified Docker deployment

README.md

@@ -31,37 +31,61 @@ short_description: ドキュメントからポッドキャスト風の解説音
 
 ## 必要条件
 
-- Python 3.11以上
+- [Docker](https://docs.docker.com/get-docker/)
+- [VS Code](https://code.visualstudio.com/) (開発時)
+- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (開発時)
 - OpenAI API キー または Google Gemini API キー
-- VOICEVOX Core (音声生成に必要)
 
-## インストール方法
+## 開発環境セットアップ（推奨）
 
-1. リポジトリをクローン:
-   ```
+### Dev Containers を使用（推奨）
+
+1. **リポジトリをクローン:**
+   ```bash
    git clone https://github.com/yourusername/yomitalk.git
    cd yomitalk
    ```
 
-2. 環境構築
-   ```
-   make setup
+2. **VS Code で開く:**
+   ```bash
+   code .
    ```
 
-   下記等が実行されます
-   - 仮想環境の作成
-   - 依存パッケージのインストール
-   - VOICEVOX Coreのダウンロード
-   - pre-commitの設定
+3. **Dev Container で開く:**
+   - `F1` を押して "Dev Containers: Reopen in Container" を選択
+   - または通知ポップアップの "Reopen in Container" をクリック
+   - 初回は環境構築に数分かかります
+
+4. **開発開始:**
+   - すべての依存関係が自動でインストールされます
+   - VOICEVOX Core も自動でセットアップされます
+
+### 従来の方法（Makefile/venv）
+
+<details>
+<summary>Makefile を使った従来のセットアップ方法</summary>
+
+```bash
+# 環境構築
+make setup
+
+# 実行内容:
+# - 仮想環境の作成
+# - 依存パッケージのインストール
+# - VOICEVOX Coreのダウンロード
+# - pre-commitの設定
+```
+
+</details>
 
 ## 使い方
 
-1. アプリケーションを起動:
-   ```
+1. **アプリケーションを起動:**
+   ```bash
    python app.py
    ```
 
-2. ブラウザで `http://localhost:7860` にアクセス
+2. **ブラウザでアクセス:** `http://localhost:7860`
 
 3. ドキュメント（PDF、テキストファイルなど）をアップロードしてテキストを抽出
 
@@ -81,6 +105,33 @@ short_description: ドキュメントからポッドキャスト風の解説音
 
 11. 生成された音声を再生またはダウンロード
 
+## 開発者向け情報
+
+### Dev Container での開発
+
+Dev Container 環境では以下のコマンドとタスクが利用できます：
+
+| タスク | コマンド | VS Code タスク |
+|--------|----------|---------------|
+| アプリ実行 | `python app.py` | "Run Yomitalk App" |
+| 全テスト | `pytest tests/` | "Run All Tests" |
+| 単体テスト | `pytest tests/unit/` | "Run Unit Tests" |
+| E2Eテスト | `E2E_TEST_MODE=true pytest tests/e2e/` | "Run E2E Tests" |
+| コード整形 | `black . && isort .` | "Format Code" |
+| 静的解析 | `flake8 . && mypy .` | "Run Linting" |
+| Pre-commit | `pre-commit run --all-files` | "Run Pre-commit" |
+
+### ファイル構成
+
+詳細な設計情報は [`docs/design.md`](docs/design.md) を参照してください。
+
+### 開発ルール
+
+- **コミット前チェック必須**: すべてのコミットは pre-commit フックを通過する必要があります
+- **`--no-verify` 禁止**: pre-commit フックのバイパスは禁止されています
+- **型チェック**: mypy による型チェックを通過する必要があります
+- **テスト**: 新機能には適切なテストを追加してください
+
 ## APIキーの取得方法
 
 ### OpenAI APIキー

docker-compose.dev.yml

@@ -0,0 +1,36 @@
+# Development docker-compose for those preferring direct docker-compose usage
+# Usage: docker-compose -f docker-compose.dev.yml up
+version: '3.8'
+
+services:
+  yomitalk-dev:
+    build:
+      context: .
+      dockerfile: .devcontainer/Dockerfile
+    volumes:
+      - .:/workspace:cached
+      - yomitalk-data:/workspace/data
+      - yomitalk-voicevox:/workspace/voicevox_core
+      # Mount for git credentials
+      - ~/.gitconfig:/home/vscode/.gitconfig:ro
+    environment:
+      - VOICEVOX_ACCEPT_AGREEMENT=true
+      - PAGER=cat
+      - LESSCHARSET=utf-8
+      - E2E_TEST_MODE=false
+      - PYTHONPATH=/workspace
+    ports:
+      - "7860:7860"
+    # Keep container running for development
+    command: sleep infinity
+    # Add capabilities for audio processing if needed
+    cap_add:
+      - SYS_PTRACE
+    security_opt:
+      - seccomp:unconfined
+    working_dir: /workspace
+    user: vscode
+
+volumes:
+  yomitalk-data:
+  yomitalk-voicevox: