local-dev-setup

ローカル開発環境セットアップスキル

サービスまたはプロジェクト向けに、ローカル開発環境のセットアップガイドを作成します。新しいエンジニアが何もない状態（クリーンなノートパソコン）から、30 分以内にテストが成功する動作可能なローカル環境を整えられるよう、手順を説明してください。優れたセットアップガイドは、オンボーディングにかかる時間を短縮し、「自分のマシンでは動く」問題を防ぎ、エンジニアが自信を持って最初の貢献を行えるようにします。何をする必要があるかの説明ではなく、すべての手順を具体的なコマンドまたは操作として記述してください。

必要な入力

まだ提供されていない場合は、以下を尋ねてください：

• サービス名とその役割
• 技術スタック — 言語、フレームワーク、データベース、キャッシュ、メッセージキュー、外部サービス
• 依存関係 — データベース、キャッシュ、メッセージキュー、外部サービス（モックまたは実サービス）
• テストフレームワーク — テストの実行方法とテストスイートの対象範囲
• CI/CD プラットフォーム — GitHub Actions、CircleCI、Jenkins など（ローカルで「CI が成功する」とは何かを把握するため）

出力形式

---

ローカル開発環境セットアップ：[Service Name]

技術スタック： [言語＋バージョン] | [フレームワーク] | [データベース] | [キャッシュ] 推定セットアップ時間： クリーンなマシンで [20～30 分] 最終確認日： [macOS Ventura 13.x / Ubuntu 22.04] で [Date] 質問がありますか？ [Slack: #[team-channel]] で質問するか、[@tech-lead-handle] に連絡してください

初めての貢献ですか？ まずセットアップ（このドキュメント）を完了してから、コード規約と PR の手順について [CONTRIBUTING.md] を読んでください。

---

前提条件

開始前に、以下のツールをインストールしてください。記載されているバージョンは最低要件です。より新しいパッチバージョンは問題ありませんが、より新しいメジャーバージョンでは互換性の問題が起きる可能性があります。

必須ツール

ツール	必要なバージョン	インストール
[Git]	2.x+	ほとんどのシステムにプリインストールされています。または brew install git
[言語ランタイム — 例：Go]	[1.22+]	[https://go.dev/dl/ または brew install go]
[Docker]	24.x+	[https://docs.docker.com/get-docker/]
[Docker Compose]	2.x+	Docker Desktop に同梱されています。または brew install docker-compose
[Make]	任意	macOS/Linux にプリインストールされています
[ツール — 例：Node.js]	[20.x+]	[brew install node または https://nodejs.org]
[ツール — 例：psql クライアント]	[15+]	brew install postgresql@15（クライアントのみ）

任意ですが推奨

ツール	用途	インストール
[direnv]	.envrc の環境変数を自動読み込み	brew install direnv ＋ セットアップ手順
[jq]	ターミナルで JSON を整形表示	brew install jq
[k9s]	Kubernetes クラスターの UI（ローカルで K8s を使用する場合）	brew install k9s
[mkcert]	ローカル HTTPS 証明書	brew install mkcert

必要なアカウントとアクセス権

開始前に、以下を確認してください：

• [org/repo] の GitHub アクセス権 — [アクセス権申請手順 / Slack: #it-help] から申請
• [開発環境] にアクセスできる [AWS / GCP / Azure] アカウント — [手順] から申請
• 開発用シークレットを取得するための [社内ツール — 例：1Password] — [手順] から申請
• 社内サービスへの接続に必要な場合は [VPN アクセス] — [手順] から申請

---

1. リポジトリのセットアップ

# Clone the repository
git clone [email protected]:[org]/[repo-name].git
cd [repo-name]

# Install git hooks (required — enforces commit message format and runs pre-commit checks)
make install-hooks
# Or manually:
# cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

# Verify your git setup
git config user.name   # should be your name
git config user.email  # should be your work email

クローン時に permission denied エラーが表示される場合： SSH キーが GitHub に追加されていません。GitHub の SSH キーガイドに従うか、代わりに HTTPS と個人用アクセストークンを使用してください。

---

2. 環境変数

サービスの設定には環境変数が必要です。実際のシークレットをリポジトリにコミットしないでください。

手順 1 — サンプルファイルをコピーする

cp .env.example .env.local

ステップ 2 — 値を入力する

エディターで .env.local を開きます。以下に、各変数の説明と値の取得先を示します。

変数	説明	取得先	例（実際の値ではありません）
APP_ENV	環境名	development に設定	development
APP_PORT	サービスがリッスンするポート	ローカル環境では 8080 に設定	8080
DATABASE_URL	PostgreSQL 接続文字列	Docker Compose の値を使用（セクション 3）	postgres://app:password@localhost:5432/[service]_dev
REDIS_URL	Redis 接続文字列	Docker Compose の値を使用	redis://localhost:6379
SECRET_KEY	アプリケーションのシークレットキー	次のコマンドで生成：openssl rand -hex 32	[random 64-char hex]
[EXTERNAL_SERVICE]_API_KEY	[External Service] の API キー	[1Password vault: "Dev API Keys"] から取得するか、[name] に尋ねます	—
[EXTERNAL_SERVICE]_BASE_URL	[External Service] のベース URL	サンドボックス URL を使用：https://sandbox.[external-service].com	https://sandbox.stripe.com
LOG_LEVEL	ログの詳細度	ローカル開発では debug に設定	debug
[FEATURE_FLAG_SDK_KEY]	フィーチャーフラグプラットフォームの SDK キー	[LaunchDarkly/Split dev project] から取得	—

direnv の使用（推奨）： .env.local を .envrc に変更し、先頭に dotenv を追加して、direnv allow を実行します。プロジェクトディレクトリーに cd すると、変数が自動的に読み込まれます。

---

3. ローカルサービスの依存関係

インフラストラクチャーの依存関係はすべて Docker Compose で実行します。PostgreSQL、Redis、Kafka をローカルにインストールする必要はありません。

# Start all dependencies (PostgreSQL, Redis, and any other services)
docker compose up -d

# Verify all containers are healthy
docker compose ps
# Expected output: all services show "healthy" status

# View logs if something is not healthy
docker compose logs [service-name]

Docker Compose で起動するサービス

サービス	ポート	用途	ヘルスチェック
PostgreSQL [version]	5432	メインデータベース	pg_isready -U app
Redis [version]	6379	キャッシュおよびセッションストア	redis-cli ping
[Kafka + Zookeeper]	9092 / 2181	メッセージキュー	kafka-topics.sh --list
[Mock server — e.g. WireMock]	8089	テストで使用する外部 API のモック	curl localhost:8089/__admin
[LocalStack]	4566	AWS サービスのエミュレーション（S3、SQS など）	aws --endpoint-url=http://localhost:4566 s3 ls

コンテナーがすぐに終了する場合： トラブルシューティングのセクションを参照してください。よくある原因は、ポートの競合と Docker のメモリー制限です。

依存関係の停止

# Stop containers (preserves data volumes)
docker compose stop

# Stop and remove containers (clears data — use when you want a fresh start)
docker compose down -v

---

4. 依存関係のインストールとビルド

# Install language dependencies
# Go:
go mod download

# Node.js:
npm install   # or: yarn install / pnpm install

# Python:
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt

# Verify build compiles cleanly
make build
# Expected: no errors; binary or compiled output in [./bin/ or ./dist/]

---

5. データベースのセットアップとシードデータの投入

# Run database migrations (creates tables and schema)
make db-migrate
# Or directly:
# [Migration command — e.g. "go run ./cmd/migrate up" or "alembic upgrade head" or "npm run db:migrate"]

# Verify migrations applied
# psql $DATABASE_URL -c "\dt"  # should list all tables

# Seed the database with development data
make db-seed
# Or directly:
# [Seed command — e.g. "go run ./cmd/seed" or "python scripts/seed.py" or "npm run db:seed"]

# Verify seed data is present
# psql $DATABASE_URL -c "SELECT COUNT(*) FROM [primary-table]"
# Expected: [N] rows

シードデータで作成されるもの：

• [N] 個のテストユーザーアカウント（認証情報は [scripts/seed/README.md or .env.example] に記載）
• 開発およびテスト用の [N] 個のサンプル [リソース]
• 管理者アカウント：[[email protected]] / パスワード：開発用パスワード変数については .env.example を参照

初期状態にリセットするには：

docker compose down -v   # wipe database volume
docker compose up -d     # start fresh
make db-migrate
make db-seed

---

6. サービスの実行

# Run the service locally
make run
# Or directly:
# [Run command — e.g. "go run ./cmd/server" or "python app.py" or "npm run dev"]

# Expected output:
# [Example of healthy startup log lines — e.g.:]
# {"level":"info","message":"Database connected","host":"localhost","port":5432}
# {"level":"info","message":"Redis connected","host":"localhost","port":6379}
# {"level":"info","message":"Server listening","port":8080}

正常に動作していることを確認する

# Health check
curl http://localhost:8080/health
# Expected: {"status":"ok","version":"[git-sha]"}

# Test a key endpoint (authenticated)
# First, get a dev token:
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[dev-user-from-seed]@example.com","password":"[dev-password-from-env]"}'
# Copy the token from the response, then:

curl http://localhost:8080/api/v1/[resource] \
  -H "Authorization: Bearer [token-from-above]"
# Expected: 200 with JSON response

ホットリロード（開発用）

# Run with hot reload — service restarts automatically on file changes
make run-dev
# Or:
# [Hot reload command — e.g. "air" for Go / "uvicorn --reload" for Python / "npm run dev" for Node]

---

7. テストの実行

# Run the full test suite
make test
# Or:
# [Test command — e.g. "go test ./..." or "pytest" or "npm test"]

# Run tests with coverage report
make test-coverage
# Coverage report: [./coverage.html or stdout]

# Run a specific test file or test case
# Go: go test ./pkg/[package]/... -run TestFunctionName
# Python: pytest tests/test_[module].py::TestClass::test_method -v
# Node: npm test -- --testPathPattern=[filename]

# Run only unit tests (fast — no external dependencies)
make test-unit

# Run only integration tests (requires Docker Compose dependencies running)
make test-integration

想定されるテスト結果：

• ユニットテスト：[N] 件、すべて合格、[<30] 秒
• 統合テスト：[N] 件、すべて合格、[<2] 分
• カバレッジ：[≥80]%（CI で適用されます。このしきい値を下回るとテストは失敗します）

PR をプッシュする前に、必ず次を実行してください：

make lint      # code linting — must pass
make test      # full test suite — must pass
make build     # verify compilation — must pass

---

8. IDE のセットアップ

VS Code（推奨）

推奨拡張機能をインストールします（VS Code が自動的に確認を表示します）。

// .vscode/extensions.json — already in the repository
{
  "recommendations": [
    "[language-extension — e.g. golang.go]",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens"
  ]
}

ワークスペースの設定は .vscode/settings.json にあります。保存時のフォーマットが有効になっており、リンターも自動的に設定されます。

[Language] 固有のセットアップ：

[e.g. Go: The gopls language server is installed automatically by the Go extension.
 Run "Go: Install/Update Tools" from the command palette after installing the extension.]

JetBrains（IntelliJ / GoLand / PyCharm / WebStorm）

• プロジェクトのルートをプロジェクトディレクトリーとして開きます
• [Language SDK]：[version] に設定します — File → Project Structure → SDKs
• 実行構成は .idea/runConfigurations/ にチェックイン済みで、自動的に表示されます
• Settings → Tools → Actions on Save で「Run formatters on save」を有効にします

---

9. よくある注意点とトラブルシューティング

Docker コンテナーが起動直後に終了する

症状： 起動して数秒後に docker compose ps を実行すると、コンテナーが Exited (1) と表示されます。

# Check the container logs for the error
docker compose logs [container-name]

# Common causes:
# 1. Port already in use — find and kill the conflicting process:
lsof -ti tcp:[port] | xargs kill -9

# 2. Docker doesn't have enough memory — allocate at least 4GB in Docker Desktop:
# Docker Desktop → Settings → Resources → Memory → 4GB

# 3. M1/M2 Mac architecture mismatch — add platform directive to docker-compose.yml:
# platform: linux/amd64

データベースへの接続が拒否される

症状： サービスの起動時に「connection refused」または「dial tcp localhost:5432: connect: connection refused」が表示されます。

# Is PostgreSQL actually running?
docker compose ps postgres
# If not running: docker compose up -d postgres

# Is it on the right port?
lsof -i :5432

# Can you connect manually?
psql postgres://app:password@localhost:5432/[service]_dev -c "SELECT 1"

# If using a custom DATABASE_URL, verify it matches the docker-compose.yml settings exactly

マイグレーションが「relation already exists」で失敗する

症状： make db-migrate が「ERROR: relation [table] already exists」でエラーになります。

# Check current migration state
[migration status command — e.g. "go run ./cmd/migrate status" or "alembic current"]

# The database may be in a partial state — reset it:
docker compose down -v
docker compose up -d
make db-migrate  # should now succeed on a clean database

テストが「connection refused」または依存関係のエラーで失敗する

症状： PostgreSQL または Redis に接続できないため、統合テストが失敗します。

# Integration tests need Docker Compose running
docker compose up -d

# Verify all containers are healthy before running tests
docker compose ps   # all should show "healthy"

# If containers are running but tests still fail, check environment variables:
make test-integration  # should pick up .env.local automatically
# If not: source .env.local && make test-integration

新しいチェックアウトで make lint が失敗する

症状： 変更していないファイルで Lint エラーが発生します。

# Formatting issue — auto-fix with:
# Go:
gofmt -w .
goimports -w .

# Python:
black .
isort .

# Node/TypeScript:
npm run lint:fix
# Or: npx eslint --fix . && npx prettier --write .

# Re-run lint to confirm
make lint

環境変数が読み込まれない

症状： サービスは起動しますが、直後に「missing required environment variable: [VAR]」で失敗します。

# Verify .env.local exists and has all required variables
cat .env.local | grep "^[A-Z]" | awk -F= '{print $1}'

# Compare against required variables in .env.example
diff <(grep "^[A-Z_]*=" .env.example | cut -d= -f1 | sort) \
     <(grep "^[A-Z_]*=" .env.local | cut -d= -f1 | sort)

# Missing variables are shown in left column only (< prefix)

---

10. 初めてのコントリビューションチェックリスト

初めてプルリクエストを作成する前に、次の項目を確認してください。

セットアップの完了：

• make build がエラーなく成功する
• make test が成功し、すべてのテストが合格する
• make lint が成功し、Lint エラーがない
• サービスが起動し、ヘルスチェックが 200 を返す
• 認証を行い、少なくとも 1 つの API エンドポイントを呼び出せる

Git と GitHub：

• [CONTRIBUTING.md] を読み、コーディング規約、コミットメッセージの形式、PR の手順を確認した
• git の user.name と user.email が正しく設定されている
• pre-commit フックがインストールされている（ls .git/hooks/pre-commit で存在を確認できます）
• main からブランチを作成した（main に直接コミットしていない）

開発ワークフロー：

• 特定のテストを実行する方法を把握している：[test command for single test]
• データベースをリセットする方法を把握している：docker compose down -v && docker compose up -d && make db-migrate && make db-seed
• [Slack: #[team-channel]] と、該当する場合は [#[service-consumers-channel] に参加した
• [アーキテクチャ概要のドキュメント／README] を読み、このサービスの役割を理解している

初めての PR：

• 変更は小さく、対象を絞っている。1 つの PR に含める変更は論理的に 1 つ
• 変更内容に応じてテストを追加または更新した
• レビューを依頼する前に、ローカル環境で make test && make lint && make build がすべて成功する
• PR の説明に変更内容と理由を記載している（必要に応じて [pr-description-writer skill] を使用してください）

---

品質チェック

• プロジェクトについて事前知識のない新しいエンジニアが、誰にも助けを求めずに、このガイドに沿って最初から最後まで作業できる
• すべてのコマンドをクリーンな環境でテストしている。記憶を頼りに書いて動作すると想定したものではない
• 環境変数の表に .env.example 内のすべての変数が記載され、説明のない変数がない
• トラブルシューティングのセクションには、オンボーディング中に実際に確認された、最も一般的な 5 つの問題が記載されている。理論上の問題ではない
• Docker Compose のバージョンと Docker Desktop のメモリ要件が明記されている
• 重要なコマンドには「期待される出力」が示され、エンジニアが手順の成功を判断できる
• セットアップ時間の見積もりが正確で、実際のオンボーディングの所要時間を計測して確認されている

避けるべきパターン

• クリーンなマシンでテストせず、記憶を頼りにセットアップ手順を書かないでください。暗黙の知識に依存して手順を省略すると、新しいエンジニアが作業できなくなります
• 環境変数の説明を省かないでください。.env.example 内のすべての変数を、説明と出典とともに「Variables」表に記載する必要があります
• 理論上の問題についてトラブルシューティングの項目を書かないでください。実際のオンボーディングで発生した問題のみを記載してください
• Docker Desktop が正しく設定されていると決めつけないでください。メモリ制限とプラットフォーム（M1/M2）との互換性を明記する必要があります
• 重要なコマンドの期待される出力を省かないでください。「期待される出力」がないと、エンジニアは手順が成功したのか、何も通知されずに失敗したのかを判断できません