environment-setup-guide

環境構築ガイド

概要

開発者が開発環境をゼロから構築できるよう支援します。このスキルでは、ツールのインストール、依存関係の設定、環境変数の構成、セットアップが正しく動作することの確認について、順を追って案内します。

このスキルを使う場面

• 新しいプロジェクトを始める際に、開発環境の構築が必要な場合
• 新しいチームメンバーをプロジェクトに迎える場合
• 新しいマシンやオペレーティングシステムに切り替える場合
• 環境に関する問題のトラブルシューティングを行う場合
• プロジェクトのセットアップ手順を文書化する場合
• 開発環境のドキュメントを作成する場合

以下のバージョンは過去の例であり、現在サポートされているバージョンの推奨ではありません。インストールする前に、プロジェクトのロックファイル、ランタイムの制約、公式のサポートマトリックスを確認し、新しいメジャーバージョンに互換性があると決めつけないでください。依存関係のインストールによって、ライフサイクルスクリプトが実行される場合があります。シークレットを含む環境ファイルを保護し、gitignore に追加してください。Docker グループへの所属は、ホスト上で root と同等の制御権限を与えます。必要に応じて、ルートレス Docker を使用してください。Compose スタックはローカル開発専用です。一意の認証情報を使い、公開するポートはループバックにバインドし、depends_on がデータベースの準備完了を意味すると決めつけずに、レディネスチェックを追加してください。

仕組み

ステップ 1：要件を確認する

インストールが必要なものを特定できるよう支援します。

• プログラミング言語とバージョン（Node.js、Python、Go など）
• パッケージマネージャー（npm、pip、cargo など）
• データベースシステム（PostgreSQL、MongoDB、Redis など）
• 開発ツール（Git、Docker、IDE 拡張機能など）
• 環境変数と設定ファイル

ステップ 2：現在の環境を確認する

何かをインストールする前に、すでにインストールされているものを確認できるよう支援します。

# Check versions of installed tools
node --version
python --version
git --version
docker --version

ステップ 3：インストール手順を提示する

プラットフォームごとのインストールコマンドを案内します。

• macOS： Homebrew を使用
• Linux： apt、yum、またはパッケージマネージャーを使用
• Windows： Chocolatey、Scoop、または直接インストーラーを使用

ステップ 4：環境を設定する

以下の設定を支援します。

• 環境変数（.env ファイル）
• 設定ファイル（.gitconfig、.npmrc など）
• IDE の設定（VS Code、IntelliJ など）
• シェルの設定（.bashrc、.zshrc など）

ステップ 5：インストールを確認する

すべてが正しく動作することを確認する手順を提示します。

• バージョンを確認する
• 基本的なコマンドをテストする
• データベース接続を確認する
• 環境変数が読み込まれていることを確認する

例

例 1：Node.js プロジェクトのセットアップ

## Setting Up Node.js Development Environment

### Prerequisites
- macOS, Linux, or Windows
- Terminal/Command Prompt access
- Internet connection

### Step 1: Install Node.js

**macOS (using Homebrew):**
\`\`\`bash
# Install Homebrew if not installed
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/homebrew-install.sh" https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh
cat "$tmpdir/homebrew-install.sh"  # review the full installer before executing
/bin/bash "$tmpdir/homebrew-install.sh"

# Install Node.js
brew install node
\`\`\`

**Linux (Ubuntu/Debian):**
\`\`\`bash
# Update package list
sudo apt update

# Install Node.js and npm
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/nodesource-setup.sh" https://deb.nodesource.com/setup_20.x
cat "$tmpdir/nodesource-setup.sh"  # review the full installer before sudo
sudo -E bash "$tmpdir/nodesource-setup.sh"
sudo apt install -y nodejs
\`\`\`

**Windows (using winget):**
\`\`\`powershell
# Install Node.js
winget install OpenJS.NodeJS.LTS
\`\`\`

### Step 2: Verify Installation

\`\`\`bash
node --version  # Should show v20.x.x or higher
npm --version   # Should show 10.x.x or higher
\`\`\`

### Step 3: Install Project Dependencies

\`\`\`bash
# Clone the repository
git clone https://github.com/your-repo/project.git
cd project

# Install dependencies
npm install
\`\`\`

### Step 4: Set Up Environment Variables

Create a \`.env\` file:
\`\`\`bash
# Copy example environment file
cp .env.example .env

# Edit with your values
nano .env
\`\`\`

Example \`.env\` content:
\`\`\`
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here
\`\`\`

### Step 5: Run the Project

\`\`\`bash
# Start development server
npm run dev

# Should see: Server running on http://localhost:3000
\`\`\`

### Troubleshooting

**Problem:** "node: command not found"
**Solution:** Restart your terminal or run \`source ~/.bashrc\` (Linux) or \`source ~/.zshrc\` (macOS)

**Problem:** "Permission denied" errors
**Solution:** Don't use sudo with npm. Fix permissions:
\`\`\`bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
\`\`\`

例 2：Python プロジェクトのセットアップ

## Setting Up Python Development Environment

### Step 1: Install Python

**macOS:**
\`\`\`bash
brew install [email protected]
\`\`\`

**Linux:**
\`\`\`bash
sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip
\`\`\`

**Windows:**
\`\`\`powershell
choco install python --version=3.11
\`\`\`

### Step 2: Verify Installation

\`\`\`bash
python3 --version  # Should show Python 3.11.x
pip3 --version     # Should show pip 23.x.x
\`\`\`

### Step 3: Create Virtual Environment

\`\`\`bash
# Navigate to project directory
cd my-project

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate
\`\`\`

### Step 4: Install Dependencies

\`\`\`bash
# Install from requirements.txt
pip install -r requirements.txt

# Or install packages individually
pip install flask sqlalchemy python-dotenv
\`\`\`

### Step 5: Set Up Environment Variables

Create \`.env\` file:
\`\`\`
FLASK_APP=app.py
FLASK_ENV=development
DATABASE_URL=sqlite:///app.db
SECRET_KEY=your-secret-key-here
\`\`\`

### Step 6: Run the Application

\`\`\`bash
# Run Flask app
flask run

# Should see: Running on http://127.0.0.1:5000
\`\`\`

例 3：Docker 開発環境

## Setting Up Docker Development Environment

### Step 1: Install Docker

**macOS:**
\`\`\`bash
brew install --cask docker
# Or download Docker Desktop from docker.com
\`\`\`

**Linux:**
\`\`\`bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
cat get-docker.sh  # inspect the complete installer before execution
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
\`\`\`

**Windows:**
Download Docker Desktop from docker.com

### Step 2: Verify Installation

\`\`\`bash
docker --version        # Should show Docker version 24.x.x
docker compose --version # Should show Docker Compose version 2.x.x
\`\`\`

### Step 3: Create docker compose.yml

\`\`\`yaml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/mydb
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
\`\`\`

### Step 4: Start Services

\`\`\`bash
# Build and start containers
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down
\`\`\`

### Step 5: Verify Services

\`\`\`bash
# Check running containers
docker ps

# Test database connection
docker compose exec db psql -U postgres -d mydb
\`\`\`

ベストプラクティス

✅ こうしましょう

• すべてを文書化する - 明確なセットアップ手順を作成する
• バージョンマネージャーを使う - Node には nvm、Python には pyenv を使う
• .env.example を作成する - 必要な環境変数を示す
• クリーンなシステムでテストする - 手順がゼロからでも機能することを確認する
• トラブルシューティングを含める - よくある問題と解決策を文書化する
• Docker を使う - マシン間で一貫した環境を保つ
• バージョンを固定する - パッケージファイルに正確なバージョンを指定する
• セットアップを自動化する - 可能であればセットアップスクリプトを作成する
• 前提条件を確認する - 開始前に必要なツールを列挙する
• 確認手順を提示する - セットアップが機能することをユーザーが確認できるようにする

❌ こうしてはいけません

• ツールがインストール済みだと決めつけない - 必ず確認し、インストール手順を示す
• 環境変数を省略しない - 必要な変数をすべて文書化する
• npm で sudo を使わない - 代わりに権限を修正する
• プラットフォームごとの差異を忘れない - OS ごとの手順を示す
• 確認手順を省略しない - 必ずテスト手順を含める
• グローバルインストールを使わない - ローカル環境や仮想環境を優先する
• エラーを無視しない - よくあるエラーへの対処方法を文書化する
• データベースのセットアップを省略しない - データベースの初期化手順を含める

よくある落とし穴

問題：「Command not found」と表示される

症状： ツールをインストールしたのに、ターミナルで認識されません 解決方法：

• ターミナルを再起動するか、シェルの設定ファイルを読み込みます
• PATH 環境変数を確認します
• インストール先を確認します

# Check PATH
echo $PATH

# Add to PATH (example)
export PATH="/usr/local/bin:$PATH"

問題：npm／pip で権限エラーが発生する

症状： 「EACCES」または「Permission denied」エラーが発生します 解決方法：

• sudo は使用しないでください
• npm の権限を修正するか、nvm を使用します
• Python では仮想環境を使用します

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

問題：ポートがすでに使用されている

症状： 「Port 3000 is already in use」と表示されます 解決方法：

• そのポートを使用しているプロセスを見つけて終了します
• 別のポートを使用します

# Find process on port 3000
lsof -i :3000

# Kill process
kill -TERM <verified-owned-PID>

# Or use different port
PORT=3001 npm start

問題：データベースへの接続に失敗する

症状： 「Connection refused」または「Authentication failed」と表示されます 解決方法：

• データベースが起動していることを確認します
• 接続文字列を確認します
• 認証情報を確認します

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U postgres -d mydb

セットアップスクリプトのテンプレート

セットアップを自動化するため、setup.sh スクリプトを作成します：

#!/bin/bash
set -euo pipefail
umask 077

echo "🚀 Setting up development environment..."

# Check prerequisites
command -v node >/dev/null 2>&1 || { echo "❌ Node.js not installed"; exit 1; }
command -v git >/dev/null 2>&1 || { echo "❌ Git not installed"; exit 1; }

echo "✅ Prerequisites check passed"

# Install dependencies
echo "📦 Installing dependencies..."
npm install

# Copy environment file
if [ ! -f .env ]; then
    echo "📝 Creating .env file..."
    cp .env.example .env
    echo "⚠️  Please edit .env with your configuration"
fi

 # Confirm a disposable/local database target before running this project-specific migration.
# Run database migrations
echo "🗄️  Running database migrations..."
npm run migrate

# Verify setup
echo "🔍 Verifying setup..."
npm run test:setup

echo "✅ Setup complete! Run 'npm run dev' to start"

関連スキル

• @brainstorming - セットアップ前に環境要件を計画します
• @systematic-debugging - 環境の問題をデバッグします
• @doc-coauthoring - セットアップのドキュメントを作成します
• @git-pushing - Git の設定を行います

追加リソース

• Node.js のインストールガイド
• Python の仮想環境
• Docker のドキュメント
• Homebrew（macOS）
• Chocolatey（Windows）
• nvm（Node Version Manager）
• pyenv（Python Version Manager）

---

ヒント： セットアッププロセス全体を自動化するため、setup.sh または setup.ps1 スクリプトを作成します。クリーンなシステムでテストし、正常に動作することを確認してください！

制限事項

• タスクが上記の説明された範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境に応じた検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。