Local Development

Local development should help engineers make safe changes quickly without recreating production on a laptop. Optimize for fast feedback, clear setup, and realistic boundaries.

Paved-road workflow

A good local workflow provides:

• One documented bootstrap command.
• Consistent runtime, package manager, and tool versions.
• Local service dependencies or safe remote development dependencies.
• Seed data that contains no real protected or sensitive data.
• Clear commands for tests, linting, type checks, and build checks.
• A way to reset local state when things drift.

Dependency strategy

Choose the lightest dependency model that still catches real issues.

• Use in-memory fakes for pure logic and fast unit tests.
• Use containers for databases, queues, and common infrastructure dependencies.
• Use sandbox accounts for third-party APIs when behavior matters.
• Avoid requiring production cloud access for routine local work.

Secrets in development

Development secrets must be safe by default.

• Never require production credentials locally.
• Store local secrets in approved secret managers or encrypted files.
• Use scoped sandbox keys with expiry where possible.
• Keep .env examples synthetic and non-sensitive.
• Document how to rotate a leaked local credential.

Developer experience checks

Track developer experience as an operational signal.

• Time from clone to first successful test.
• Time from clone to running the app locally.
• Frequency of environment setup failures.
• Flaky test rate and slowest feedback loops.
• Common onboarding questions.

Improving local development is platform work. Treat repeated setup pain as backlog, not as individual engineer weakness.