Your Local Dev Environment Is a Product (Treat It Like One)

A new engineer joins your team. They spend day one following the README. It's three years old. Half the steps fail silently. By 4pm they've asked six people for help, installed three conflicting versions of Node, and haven't run the app yet.

Day two they're still setting up.

This is not exceptional. This is what "we don't track setup time" looks like at scale.

Setup time is a KPI nobody measures

Teams measure time-to-first-PR. Rarely do they measure time-to-running-app-locally. The second metric predicts the first, and it's entirely in your control.

A reasonable target: a new engineer on a greenfield machine should have the app running locally in under 30 minutes. Under 15 minutes is excellent. Over 60 minutes means your local environment is broken and you've normalized it.

The reason teams don't measure this is that nobody runs setup from scratch. The people who know the codebase have it running already. The last person who went through setup joined 18 months ago. The README is aspirational documentation, not operational documentation.

The compounding cost of a bad DX

Setup time isn't just a new-hire problem. Every engineer on your team pays the local environment tax daily:

Environment drift. macOS updates. Docker daemon crashes. SSL certs expire. The dev environment that worked last week silently breaks.
Onboarding load. Senior engineers spend hours unblocking new hires instead of building.
Context switching. Switching between services requires re-running setup scripts that take 5 minutes each.
Fear of clean installs. Engineers avoid wiping their machines because they don't trust they can get back to working state. Technical debt compounds in ~/.zshrc.

None of this shows up in your sprint velocity. It shows up as a vague sense that "things are slower than they should be."

What a good local dev environment looks like

One command to start. make dev or npm run dev or ./dev.sh. Whatever it is, it's one thing. Not "run step 1, then step 2, then check if port 5432 is already in use, then..."

It says what's wrong. If a dependency is missing, it says which one. If a port is in use, it says which process. Silent failures are the most expensive failures — the engineer has no idea where to look.

It's versioned. The Dockerfile, the docker-compose, the .nvmrc, the .tool-versions — these live in the repo and change with the code. Not in a Notion page. Not in someone's memory.

It recovers cleanly. make clean && make dev should return you to a working state from any broken state. Engineers who can't recover quickly leave the broken environment running and work around it.

It matches production enough to matter. Not identical — local dev has legitimate shortcuts. But schema differences, missing env vars, or mocked services that behave wrong kill half your bugs in dev before they ever reach staging.

The internal product framing

Treat your local dev environment as an internal product. It has users (your engineers), it has a job to be done (get a working app running fast), and it has quality metrics (setup time, recovery time, daily reliability).

This means:

Someone owns it. Not "everyone is responsible" — a specific team or rotation. Platform engineering teams often take this on. If you don't have one, the tech lead owns it.
It gets bug reports. An engineer hits a broken setup step? That's a bug. It goes in the backlog with priority like any other bug that blocks shipping.
It gets improvements. Quarterly, someone asks: "what's the most annoying thing about our local setup?" and fixes the top answer.
It gets tested. Spin up a new VM monthly and run setup from scratch. Time it. Track it.

Common failure patterns

The README that's a wish list. npm install — sure. Set up Postgres 14 — how? Install it, or expect it to be running? Where? The README assumes context that new engineers don't have.

Docker Compose that breaks on Apple Silicon. Images built for amd64, no arm64 alternative. The fix is 10 minutes of work. The cost is 30% of new hires spending hours on it.

Environment variables with no defaults. Twelve env vars required to start. None of them have example values. The .env.example hasn't been updated in two years. Three of the vars are no longer used. Two new ones aren't in it.

Scripts that work on the author's machine. Hardcoded paths. Assumptions about shell. Commands that work in bash but break in zsh. No one tests these on a fresh machine because they assume they work.

Homebrew version drift. One engineer uses Postgres 14, another has 15, CI runs 16. The bug only reproduces on 15. Nobody knows why.

The minimum viable improvement

If your team has a bad local setup and you can't allocate a sprint to fix it fully, do this:

Have a new hire (or a willing senior) run setup from scratch and narrate every point of confusion. Record it or take notes.
Fix the three worst failures they hit. Not all of them — the three worst.
Add a line to the README: "If anything here doesn't work, open an issue." Then actually fix those issues.
Repeat every time someone new joins.

This won't get you to excellent. It will stop the bleeding and create a feedback loop.

The leverage point

Senior engineers underestimate the multiplier effect of a fast local setup. They've optimized their own environment over months. They don't run setup from scratch. They forget what it's like to start cold.

But for a five-person team, shaving 30 minutes off daily setup friction across the team is 2.5 engineer-hours recovered per day. Per week that's a full engineer-day. Per month it's three. That's a feature.

A slow local dev environment doesn't feel like a bottleneck because the cost is distributed and invisible. Track setup time. Someone owns it. Fix the worst things first. Then do it again.