How to Get a New Developer Productive on Day One

A new developer joins. They're keen, they're good, and they spend their first three days getting the project to run. The setup doc says to install a version of Node that no longer builds the project. The database needs a seed script that someone deleted. Two environment variables aren't documented anywhere, and the only person who knows them is on holiday.

This is so normal that teams stop noticing it. But it's expensive — days of salary per hire, a poor first impression, and a quiet signal that "nobody here writes things down." The same problem applies to contractors, to returning after six months away, and increasingly to AI agents, which need a working environment just as much as a person does.

Here's what a day-one-ready project looks like.

The goal

A new person, with a laptop and access to the repository, can:

Get a running copy of the app in under an hour,
With realistic data in it,
Make a small change, run the tests, and open a pull request —

on their first day, without asking anyone for anything except accounts.

1. Make the environment reproducible

"Install these seven things at these versions" doesn't survive contact with a different operating system, or with time. The environment should be defined in the repository and created from that definition.

The most portable way is a dev container: a devcontainer.json file that describes the tools, runtime versions, extensions, and services the project needs. VS Code, JetBrains IDEs, GitHub Codespaces, and several other tools can build a working environment from it. What Is a Dev Container? covers the format.

At minimum, even without containers:

Pin runtime versions in files tools understand: .nvmrc or engines in package.json for Node, .python-version for Python, .tool-versions for asdf/mise.
Commit the lockfile. Everyone installs the same dependency versions.
Define local services — the database, Redis, anything else — in a docker-compose.yml, so they start with one command at the right versions.

2. One command to set up, one to run

A new developer shouldn't have to read a page of steps. They should run:

./scripts/setup    # install dependencies, create the database, run migrations, load seed data
./scripts/dev      # start everything

Or make setup / make dev, or npm scripts — the mechanism doesn't matter. What matters is that the steps live in a script that actually runs, rather than in prose that slowly stops being true. A script that fails is noticed and fixed; a README that's wrong just wastes the next person's day.

3. Seed data that looks real

An empty app is hard to understand and hard to test. The setup should load seed data: a handful of users with different roles, some realistic records, the edge cases that matter (a user with no orders, an order with fifty items, a cancelled subscription).

Two rules:

Never copy production data to development machines. It's personal data, and it's a breach waiting to happen. Generate fake data instead.
Keep the seed script in the repository and run it as part of setup, so it stays in step with the schema. Migrations change the database; the seed script has to keep up. (What Are Database Migrations?.)

4. Environment variables, documented

Every variable the app needs should be listed in a committed .env.example, with safe development values or clear placeholders and a one-line comment each:

# Postgres connection for local development (docker-compose starts this)
DATABASE_URL=postgres://dev:dev@localhost:5432/app_dev

# Stripe test-mode key — get your own from the Stripe dashboard (test mode)
STRIPE_SECRET_KEY=sk_test_replace_me

Setup copies it to .env. Real secrets never go in the example file. Where a new developer needs their own credentials for a third-party service, the comment says exactly where to get them.

5. A short, honest README

Not a wiki. One page, in the repository, covering:

What the app is, in two sentences.
How to set up and run it (the two commands).
How to run the tests.
How the code is organised — the five directories that matter.
How to get changes merged: branching, reviews, and how deploys happen.
Who to ask about what.

If it's longer than a page, the extra belongs in linked documents. If a section is wrong, fix it the moment someone trips over it — ideally the new person, as their first pull request.

The same content, in shorter, rule-shaped form, makes a good CLAUDE.md for AI agents working in the repo. Humans and agents need the same facts. (How to Write a CLAUDE.md That Actually Helps.)

6. A good first task

Have a small, real, low-risk task ready: a copy change, a minor bug, a missing test. The point isn't the task. It's walking through the whole path — branch, change, test, pull request, review, deploy — once, with help nearby, on day one.

7. Access, prepared in advance

Half of lost onboarding time is waiting for accounts. Before day one: the code host, the issue tracker, chat, the error tracker, a development account on any third-party service they'll need. A checklist that someone runs the week before avoids the "who can add me to…" scramble.

Cloud workspaces: skipping the laptop entirely

A reproducible environment in the repository gets setup down to an hour. Cloud development environments can get it close to zero: the environment runs on a server, built from the same definition, and a new developer opens it in a browser or connects their editor to it. Nothing to install locally, and a powerful machine regardless of what laptop they were given.

They're also a clean answer for contractors — the code never has to live on their personal machine — and for AI agents, which need an always-on environment of their own. There are trade-offs in cost and latency; we lay them out in Cloud Development Environments vs Local Setup.

Test it without hiring anyone

You don't need a new hire to find out whether onboarding works:

Fresh-clone test. Once a month, someone clones the repo into a new directory (or a new container) and follows the README from scratch. Time it. Fix whatever breaks.
Automate it. Run the setup script in CI on every change. If setup breaks, you find out that day, not on someone's first morning.
Ask the last hire. "What did you have to ask about in your first week?" Every answer is a missing line in the README or script.
Let an agent try. Point an AI coding agent at a fresh clone and ask it to get the app running and the tests passing using only what's in the repository. Where it gets stuck is exactly where a new human will.

The checklist

Environment defined in the repo (dev container, or pinned versions + compose file)
One command to set up, one to run
Generated seed data, loaded by setup — never production data
.env.example with every variable documented
A one-page README that's actually true
A starter task ready
Accounts set up before day one
Setup tested from a fresh clone, ideally in CI

EasySpawn gives every project a persistent cloud workspace — code, dependencies, database, and environment variables in place — that a new developer, a contractor, or Claude Code can open from a browser, phone, or SSH. See how it works or join the waitlist.