env-setup-assistant

環境セットアップアシスタントスキル

概要

このスキルは、再現性が高く、開発者にとって使いやすい環境の構築に役立ちます。IDE の設定、ツールのインストール、依存関係の管理、オンボーディングドキュメント、クロスプラットフォーム対応を扱います。

環境セットアップの方針

原則

1. ワンコマンドでセットアップ：新しい開発者は、1 つのコマンドを実行するだけでセットアップできるようにします
2. 再現性：どこでも同じ環境を利用できるようにします
3. ドキュメント化：特殊なケースにも対応できる明確な手順を用意します
4. バージョン管理：ツールと依存関係のバージョンを固定します

目標

• 実施すること：可能な限りすべてを自動化します
• 実施すること：問題を早期に検出し、報告します
• 実施すること：複数のプラットフォーム（macOS、Linux、Windows）に対応します
• 実施しないこと：グローバルにインストールされていることを前提にしません
• 実施しないこと：ドキュメントなしで手動の作業を求めません

プロジェクトセットアップスクリプト

包括的なセットアップスクリプト

#!/bin/bash
# scripts/setup.sh

set -e  # Exit on error

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# ===================
# Check Prerequisites
# ===================
check_command() {
    if ! command -v "$1" &> /dev/null; then
        log_error "$1 is not installed"
        return 1
    fi
    log_info "$1 found: $(command -v $1)"
    return 0
}

check_prerequisites() {
    log_info "Checking prerequisites..."

    local missing=0

    check_command "node" || missing=$((missing + 1))
    check_command "npm" || missing=$((missing + 1))
    check_command "git" || missing=$((missing + 1))

    # Check Node version
    local node_version=$(node -v | cut -d'v' -f2)
    local required_version="18.0.0"
    if ! [ "$(printf '%s\n' "$required_version" "$node_version" | sort -V | head -n1)" = "$required_version" ]; then
        log_error "Node.js version must be >= $required_version (found: $node_version)"
        missing=$((missing + 1))
    fi

    if [ $missing -gt 0 ]; then
        log_error "$missing prerequisite(s) missing"
        echo ""
        echo "Install missing tools:"
        echo "  - Node.js: https://nodejs.org/ or 'nvm install 20'"
        echo "  - Git: https://git-scm.com/"
        exit 1
    fi

    log_info "All prerequisites met!"
}

# ===================
# Environment Setup
# ===================
setup_env() {
    log_info "Setting up environment..."

    if [ ! -f .env ]; then
        if [ -f .env.example ]; then
            cp .env.example .env
            log_info "Created .env from .env.example"
            log_warn "Please update .env with your values"
        else
            log_error "No .env.example found"
            exit 1
        fi
    else
        log_info ".env already exists"
    fi
}

# ===================
# Install Dependencies
# ===================
install_dependencies() {
    log_info "Installing dependencies..."

    npm ci

    log_info "Dependencies installed!"
}

# ===================
# Setup Git Hooks
# ===================
setup_git_hooks() {
    log_info "Setting up Git hooks..."

    npx husky install 2>/dev/null || log_warn "Husky not configured"

    log_info "Git hooks configured!"
}

# ===================
# Database Setup
# ===================
setup_database() {
    log_info "Setting up database..."

    # Check if database is running
    if ! pg_isready -h localhost -p 5432 &>/dev/null; then
        log_warn "PostgreSQL not running on localhost:5432"
        log_info "Start with: docker-compose up -d db"
        return
    fi

    # Run migrations
    npm run db:migrate 2>/dev/null || log_warn "No migrations to run"

    # Seed data (development only)
    if [ "$NODE_ENV" != "production" ]; then
        npm run db:seed 2>/dev/null || log_warn "No seed script found"
    fi

    log_info "Database setup complete!"
}

# ===================
# Verify Setup
# ===================
verify_setup() {
    log_info "Verifying setup..."

    # Type check
    npm run typecheck 2>/dev/null && log_info "TypeScript: OK" || log_warn "TypeScript check failed"

    # Lint
    npm run lint 2>/dev/null && log_info "Linting: OK" || log_warn "Linting issues found"

    # Build test
    npm run build 2>/dev/null && log_info "Build: OK" || log_error "Build failed"
}

# ===================
# Main
# ===================
main() {
    echo ""
    echo "================================"
    echo "  Project Setup"
    echo "================================"
    echo ""

    check_prerequisites
    echo ""

    setup_env
    echo ""

    install_dependencies
    echo ""

    setup_git_hooks
    echo ""

    setup_database
    echo ""

    verify_setup
    echo ""

    echo "================================"
    echo "  Setup Complete!"
    echo "================================"
    echo ""
    echo "Next steps:"
    echo "  1. Update .env with your values"
    echo "  2. Start development: npm run dev"
    echo "  3. Open http://localhost:3000"
    echo ""
}

main "$@"

バージョン管理

.nvmrc / .node-version

20.10.0

ツールのバージョン（asdf）

# .tool-versions
nodejs 20.10.0
pnpm 8.12.0
python 3.11.6

Volta の設定

// package.json
{
  "volta": {
    "node": "20.10.0",
    "npm": "10.2.5"
  }
}

IDE の設定

VSCode の設定

// .vscode/settings.json
{
  // Editor
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [80, 120],

  // Files
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.next": true
  },

  // TypeScript
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.tsdk": "node_modules/typescript/lib",

  // Tailwind
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],

  // ESLint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // Prettier
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

VSCode 拡張機能

// .vscode/extensions.json
{
  "recommendations": [
    // Essential
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",

    // TypeScript
    "ms-vscode.vscode-typescript-next",
    "yoavbls.pretty-ts-errors",

    // React/Next.js
    "dsznajder.es7-react-js-snippets",
    "formulahendry.auto-rename-tag",

    // Git
    "eamodio.gitlens",
    "mhutchie.git-graph",

    // Productivity
    "streetsidesoftware.code-spell-checker",
    "usernamehw.errorlens",
    "christian-kohler.path-intellisense",

    // Theme (optional)
    "GitHub.github-vscode-theme"
  ],
  "unwantedRecommendations": []
}

VSCode の起動設定

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "args": ["dev"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Jest: current file",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": [
        "${fileBasename}",
        "--config",
        "jest.config.js",
        "--runInBand"
      ],
      "console": "integratedTerminal"
    }
  ]
}

EditorConfig

# .editorconfig
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

Git の設定

.gitattributes

# .gitattributes

# Auto detect text files
* text=auto eol=lf

# Documents
*.md text
*.txt text

# Source code
*.js text
*.jsx text
*.ts text
*.tsx text
*.css text
*.scss text
*.html text
*.json text
*.yaml text
*.yml text

# Docker
Dockerfile text

# Shell
*.sh text eol=lf

# Windows
*.bat text eol=crlf

# Binary
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary
*.ttf binary
*.eot binary
*.pdf binary

pre-commit フック（Husky + lint-staged）

// package.json
{
  "scripts": {
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"

オンボーディングドキュメント

CONTRIBUTING.md テンプレート

# Contributing Guide

## Getting Started

### Prerequisites

- Node.js 20+ ([install](https://nodejs.org/) or `nvm install 20`)
- pnpm 8+ (`npm install -g pnpm`)
- Docker Desktop ([install](https://docker.com/products/docker-desktop))
- Git ([install](https://git-scm.com/))

### Quick Start

```bash
# Clone the repository
git clone https://github.com/org/project.git
cd project

# Run setup script
./scripts/setup.sh

# Start development server
npm run dev

http://localhost:3000 を開きます

手動セットアップ

セットアップスクリプトが動作しない場合：

1. 依存関係をインストールする

   npm install
   

2. 環境をセットアップする

   cp .env.example .env
   # Edit .env with your values
   

3. サービスを起動する

   docker-compose up -d
   

4. マイグレーションを実行する

   npm run db:migrate
   

開発ワークフロー

ブランチの命名

• feature/description - 新機能
• fix/description - バグ修正
• chore/description - メンテナンス
• docs/description - ドキュメント

コミットメッセージ

Conventional Commits を使用します：

type(scope): description

[optional body]

[optional footer]

種類：feat、fix、docs、style、refactor、test、chore

プルリクエスト

1. main からブランチを作成します
2. 変更を加えます
3. テストを実行します：npm test
4. リントを実行します：npm run lint
5. main に対する PR を作成します

利用可能なスクリプト

コマンド	説明
npm run dev	開発サーバーを起動します
npm run build	本番環境向けにビルドします
npm run test	テストを実行します
npm run lint	リントを実行します
npm run typecheck	TypeScript のチェックを実行します

アーキテクチャ

[プロジェクト構成の概要]

ヘルプを得る

• 既存のイシューを確認します
• Slack の #dev-help チャンネルで質問します
• @maintainer に連絡します

### Developer Onboarding Checklist

```markdown
# New Developer Onboarding

## Day 1 - Environment Setup

- [ ] Clone repository
- [ ] Run setup script
- [ ] Verify development server starts
- [ ] Install IDE extensions
- [ ] Join Slack channels: #dev, #dev-help

## Day 1 - Access

- [ ] GitHub repository access
- [ ] Vercel team access
- [ ] Supabase project access
- [ ] 1Password vault access
- [ ] Figma access

## Week 1 - Understanding

- [ ] Read CONTRIBUTING.md
- [ ] Review project architecture
- [ ] Complete starter task
- [ ] Pair with team member

## Helpful Links

- [Project Documentation](./docs/)
- [Design System](https://figma.com/...)
- [API Documentation](./docs/api/)

クロスプラットフォーム対応

プラットフォーム検出スクリプト

# scripts/detect-platform.sh
#!/bin/bash

detect_os() {
    case "$(uname -s)" in
        Darwin)
            echo "macos"
            ;;
        Linux)
            echo "linux"
            ;;
        CYGWIN*|MINGW*|MSYS*)
            echo "windows"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

detect_arch() {
    case "$(uname -m)" in
        x86_64)
            echo "amd64"
            ;;
        arm64|aarch64)
            echo "arm64"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

OS=$(detect_os)
ARCH=$(detect_arch)

echo "Detected: $OS ($ARCH)"

Windows PowerShell のセットアップ

# scripts/setup.ps1

Write-Host "Setting up development environment..." -ForegroundColor Green

# Check Node.js
if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
    Write-Host "Node.js not found. Please install from https://nodejs.org/" -ForegroundColor Red
    exit 1
}

$nodeVersion = node -v
Write-Host "Node.js version: $nodeVersion" -ForegroundColor Cyan

# Copy environment file
if (-not (Test-Path .env)) {
    if (Test-Path .env.example) {
        Copy-Item .env.example .env
        Write-Host "Created .env from .env.example" -ForegroundColor Yellow
    }
}

# Install dependencies
Write-Host "Installing dependencies..." -ForegroundColor Green
npm ci

# Setup complete
Write-Host ""
Write-Host "Setup complete!" -ForegroundColor Green
Write-Host "Run 'npm run dev' to start development server" -ForegroundColor Cyan

環境チェックリスト

プロジェクトのセットアップ

• セットアップスクリプトが macOS、Linux、Windows で動作する
• 前提条件とバージョンがドキュメント化されている
• 環境変数がドキュメント化されている
• IDE の設定がコミットされている
• Git フックが設定されている

開発者エクスペリエンス

• ワンコマンドでセットアップできる
• 明確なエラーメッセージが表示される
• オンボーディングドキュメントがある
• 便利な npm スクリプトがある
• デバッグ設定がある

コード品質

• ESLint が設定されている
• Prettier が設定されている
• TypeScript の strict モードが有効になっている
• pre-commit フックが設定されている
• エディターと連携している

このスキルを使用するタイミング

次の場合にこのスキルを呼び出します：

• 新しいプロジェクトを始めるとき
• 新しい開発者をオンボーディングするとき
• チームの環境を標準化するとき
• 開発環境のセットアップに関する問題をトラブルシューティングするとき
• セットアップの自動化を作成するとき
• IDE の設定を行うとき
• クロスプラットフォーム開発環境をセットアップするとき