Help us improve
Share bugs, ideas, or general feedback.
From pm-engineering
Generates a complete local development environment setup guide covering prerequisites, dependencies, configuration, seeding, testing, and troubleshooting.
npx claudepluginhub mohitagw15856/pm-claude-skills --plugin pm-engineeringHow this skill is triggered — by the user, by Claude, or both
Slash command
/pm-engineering:local-dev-setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Produce a complete local development environment setup guide for a service or project — walking a new engineer from zero (a clean laptop) to a working local environment with passing tests in under 30 minutes. A good setup guide reduces onboarding time, prevents the "it works on my machine" problem, and lets engineers make their first contribution with confidence. Write every step as a concrete ...
Guides developers through setting up development environments from scratch, including installing tools, configuring dependencies, and verifying setups.
Guides developers through setting up dev environments: identifies tools like Node.js/Python/Docker, provides platform-specific installs (Homebrew/apt/Chocolatey), configs env vars, verifies setups. For new projects, onboarding, machine switches.
Defines standardized development environments or onboards developers by generating setup scripts, container configs, CI workflows, toolchain pins, and dev-setup documents.
Share bugs, ideas, or general feedback.
Produce a complete local development environment setup guide for a service or project — walking a new engineer from zero (a clean laptop) to a working local environment with passing tests in under 30 minutes. A good setup guide reduces onboarding time, prevents the "it works on my machine" problem, and lets engineers make their first contribution with confidence. Write every step as a concrete command or action — not a description of what needs to happen.
Ask for these if not already provided:
Tech stack: [Language + version] | [Framework] | [Database] | [Cache] Estimated setup time: [20–30 minutes] on a clean machine Last verified: [Date] on [macOS Ventura 13.x / Ubuntu 22.04] Questions? Ask in [Slack: #[team-channel]] or ping [@tech-lead-handle]
First contribution? Complete setup first (this doc), then read [CONTRIBUTING.md] for code standards and PR process.
Install these tools before starting. The versions listed are the minimum required — newer patch versions are fine, newer major versions may have compatibility issues.
| Tool | Required version | Install |
|---|---|---|
| [Git] | 2.x+ | Pre-installed on most systems; or brew install git |
| [Language runtime — e.g. Go] | [1.22+] | [https://go.dev/dl/ or brew install go] |
| [Docker] | 24.x+ | [https://docs.docker.com/get-docker/] |
| [Docker Compose] | 2.x+ | Included with Docker Desktop; or brew install docker-compose |
| [Make] | Any | Pre-installed on macOS/Linux |
| [Tool — e.g. Node.js] | [20.x+] | [brew install node or https://nodejs.org] |
| [Tool — e.g. psql client] | [15+] | brew install postgresql@15 (client only) |
| Tool | Purpose | Install |
|---|---|---|
| [direnv] | Auto-load .envrc environment variables | brew install direnv + setup instructions |
| [jq] | Pretty-print JSON in terminal | brew install jq |
| [k9s] | Kubernetes cluster UI (if using K8s locally) | brew install k9s |
| [mkcert] | Local HTTPS certificates | brew install mkcert |
Before starting, make sure you have:
# Clone the repository
git clone git@github.com:[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
If you see a permission denied error on clone: Your SSH key is not added to GitHub. Follow GitHub's SSH key guide or use HTTPS with a personal access token instead.
The service requires environment variables for configuration. Never commit actual secrets to the repository.
cp .env.example .env.local
Open .env.local in your editor. Below is a description of every variable and where to get its value:
| Variable | Description | Where to get it | Example (not real) |
|---|---|---|---|
APP_ENV | Environment name | Set to development | development |
APP_PORT | Port the service listens on | Set to 8080 for local | 8080 |
DATABASE_URL | PostgreSQL connection string | Use value from Docker Compose (Section 3) | postgres://app:password@localhost:5432/[service]_dev |
REDIS_URL | Redis connection string | Use value from Docker Compose | redis://localhost:6379 |
SECRET_KEY | Application secret key | Generate with: openssl rand -hex 32 | [random 64-char hex] |
[EXTERNAL_SERVICE]_API_KEY | API key for [External Service] | Retrieve from [1Password vault: "Dev API Keys"] or ask [name] | — |
[EXTERNAL_SERVICE]_BASE_URL | Base URL for [External Service] | Use sandbox URL: https://sandbox.[external-service].com | https://sandbox.stripe.com |
LOG_LEVEL | Logging verbosity | Set to debug for local development | debug |
[FEATURE_FLAG_SDK_KEY] | Feature flag platform SDK key | Retrieve from [LaunchDarkly/Split dev project] | — |
Using direnv (recommended): Rename .env.local to .envrc, add dotenv at the top, and run direnv allow. Variables will load automatically when you cd into the project.
All infrastructure dependencies run in Docker Compose. You do not need to install PostgreSQL, Redis, or Kafka locally.
# 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]
| Service | Port | Purpose | Health check |
|---|---|---|---|
| PostgreSQL [version] | 5432 | Primary database | pg_isready -U app |
| Redis [version] | 6379 | Cache and session store | redis-cli ping |
| [Kafka + Zookeeper] | 9092 / 2181 | Message queue | kafka-topics.sh --list |
| [Mock server — e.g. WireMock] | 8089 | Mocks for external APIs in tests | curl localhost:8089/__admin |
| [LocalStack] | 4566 | AWS service emulation (S3, SQS, etc.) | aws --endpoint-url=http://localhost:4566 s3 ls |
If a container exits immediately: See Troubleshooting section — common causes are port conflicts and Docker memory limits.
# 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
# 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/]
# 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
What the seed creates:
[admin@example.com] / password: see .env.example for dev password variableTo reset to a clean state:
docker compose down -v # wipe database volume
docker compose up -d # start fresh
make db-migrate
make db-seed
# 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]
# 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
Expected test results:
Before pushing a PR, always run:
make lint # code linting — must pass
make test # full test suite — must pass
make build # verify compilation — must pass
Install the recommended extensions (VS Code will prompt you automatically):
// .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"
]
}
Workspace settings are in .vscode/settings.json — format on save is enabled, linter is configured automatically.
[Language]-specific setup:
[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.]
.idea/runConfigurations/ — they appear automaticallySymptom: docker compose ps shows a container as Exited (1) seconds after starting.
# 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
Symptom: Service fails to start with "connection refused" or "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
Symptom: make db-migrate errors with "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
Symptom: Integration tests fail because they cannot connect to PostgreSQL or 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 fails on a fresh checkoutSymptom: Lint errors on files you have not modified.
# 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
Symptom: Service starts but immediately fails with "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)
Before opening your first pull request, verify:
Setup complete:
make build passes with no errorsmake test passes — all tests greenmake lint passes — no lint errorsGit and GitHub:
ls .git/hooks/pre-commit should exist)main (not committing directly to main)Development workflow:
[test command for single test]docker compose down -v && docker compose up -d && make db-migrate && make db-seedFirst PR:
make test && make lint && make build all pass locally before requesting review.env.example — no undocumented variables