Developer Onboarding: New Engineer Setup, 30/60/90 Day Plans, and Team Integration

The cost of a bad onboarding experience is measured in months, not days. A new engineer who spends their first week fighting environment setup and asking Slack questions nobody has time to answer will be slower for months — and is significantly more likely to leave within the year.

A structured onboarding program is not just humane; it's an engineering investment that pays back faster than most technical improvements.

---

The Onboarding Metrics That Matter

Before designing your program, establish what success looks like:

If your current average time to first commit is 5 days, your environment setup is broken.

---

Automated Dev Environment Setup

The goal: a new engineer clones the repo and runs one command. Everything else is automated.

# scripts/setup.sh — run once on a fresh machine
#!/usr/bin/env bash
set -euo pipefail

echo "🚀 Setting up development environment..."

# 1. Check prerequisites
command -v brew >/dev/null 2>&1 || {
  echo "Installing Homebrew..."
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
}

# 2. Install system dependencies
brew bundle --file=Brewfile

# 3. Install Node.js via fnm (fast node manager)
if ! command -v fnm &>/dev/null; then
  curl -fsSL https://fnm.vercel.app/install | bash
fi
eval "$(fnm env)"
fnm install --lts
fnm use --lts

# 4. Install pnpm
corepack enable
corepack prepare pnpm@latest --activate

# 5. Install project dependencies
pnpm install

# 6. Copy environment file
if [ ! -f .env.local ]; then
  cp .env.example .env.local
  echo "⚠️  Created .env.local — fill in real values from 1Password vault 'Dev Secrets'"
fi

# 7. Start required services via Docker
docker compose up -d postgres redis

# 8. Wait for services to be ready
echo "Waiting for PostgreSQL..."
until docker compose exec postgres pg_isready -U postgres &>/dev/null; do
  sleep 1
done

# 9. Run database migrations
pnpm db:migrate

# 10. Seed development data
pnpm db:seed

# 11. Verify setup
pnpm type-check
pnpm test --passWithNoTests

echo ""
echo "✅ Setup complete! Run 'pnpm dev' to start the development server."
echo "📖 Next: Read CONTRIBUTING.md and check your first task in Linear."

# Brewfile — declarative macOS dependencies
brew "git"
brew "node"                # Fallback if fnm fails
brew "pnpm"
brew "postgresql@16"
brew "redis"
cask "docker"
cask "visual-studio-code"
brew "gh"                  # GitHub CLI
brew "jq"
brew "httpie"              # For API testing

# docker-compose.yml — local services
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app_development
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

---

The First Day Checklist

Don't leave this to chance. Send the checklist before day one:

# Your First Day at [Company] — Engineering Checklist

## Before You Start (send access requests 3 days early)
- [ ] GitHub org invitation accepted
- [ ] AWS IAM user created (read-only prod, full dev/staging)
- [ ] 1Password vault access granted
- [ ] Linear/Jira workspace joined
- [ ] Slack workspace + relevant channels joined
- [ ] Google Workspace account active
- [ ] PagerDuty account (observer, not on-call until week 4)
- [ ] Datadog read-only access

Day 1 Morning

• Run ./scripts/setup.sh — dev environment automated
• pnpm dev — confirm app runs locally
• Meet your onboarding buddy (1:1 scheduled for today)
• Read CONTRIBUTING.md and ARCHITECTURE.md
• Watch the codebase walkthrough recording (link in Notion)

Day 1 Afternoon

• First task: fix a typo or small bug (tagged good-first-issue)
• Submit first PR — even tiny ones count
• Join #engineering-daily standup
• Book 15-min coffees with 3 team members this week

---

Codebase Tour: The Living Document

A recorded codebase walkthrough (30–60 min) is worth more than any README. Record it quarterly. Include:

• Top-level architecture: "here's how a request flows from browser to database"
• Key files: "this is where we define all our database schemas"
• Testing approach: "we use Playwright for E2E, Jest for unit tests"
• Common debugging: "when something breaks in staging, first look here"
• Gotchas: "this file looks like it should work a certain way, but it doesn't because..."

Store recordings in Notion or Loom. Link from README.

---

30/60/90 Day Plan

Structured milestones give new engineers clarity and give managers a framework for support:

30 Days: Learn

Goals: Understand the codebase, team, and product. Ship small.

Week 1: Environment + orientation

• Dev environment working
• First PR merged (even tiny)
• 1:1s with all immediate teammates
• Understand the product: use it as a customer for 1 hour

Week 2-3: Small contributions

• Own and ship a bug fix or small feature
• Review 5 PRs (comment, learn, don't just approve)
• Read the last 3 architecture decision records (ADRs)

Week 4: Calibration

• Complete onboarding survey (anonymous, honest)
• 30-day 1:1 with manager: what's clear? What's confusing?
• Identify your first "real" project for weeks 5-8

60 Days: Contribute

Goals: Independently ship a meaningful feature.

• Own a medium-sized feature from design through deployment
• Write one ADR for a technical decision
• Participate in one on-call rotation (shadowing, not primary)
• Give feedback on onboarding to improve it for the next hire

90 Days: Own

Goals: Operate with minimal hand-holding.

• Lead a feature from kickoff to production
• Contribute to hiring: interview a candidate
• Identify and fix one piece of technical debt
• Take primary on-call shift (with backup)
• Have "career conversation" with manager: what do you want to learn?

---

## The Buddy System

Assign every new engineer a buddy — a peer (not their manager) who:
- Answers "dumb questions" without judgment
- Proactively checks in daily for the first two weeks
- Is available on Slack for real-time help
- Is not responsible for performance evaluation

Rotate the buddy role among senior engineers. Limit each person to one buddy at a time. Compensate with recognition — reduce their ticket load for the month.

---

Onboarding Documentation That Stays Current

The reason onboarding docs become stale: they're maintained by one person, and updates require heroic effort.

The solution: Make updating onboarding docs part of the onboarding process itself.

## CONTRIBUTING.md — Kept Current by New Hires

After your first week, you are required to:
1. Fix at least one inaccuracy in this document
2. Add at least one "gotcha" you discovered that wasn't documented

This is part of your onboarding task, not optional.
Submit it as a PR by the end of week 2.

Each new hire improves the docs slightly. Over a year, the documentation becomes significantly more accurate — maintained by the people who most recently went through the process.

---

Remote Onboarding Considerations

For remote engineers:

## Remote Onboarding Extras

### Equipment
- Ship laptop + peripherals 5 days before start date
- Include a handwritten welcome note (small thing, big impression)
- Budget for home office setup: $500–1,000 (chair, monitor, webcam)

### Connection
- Video call daily with buddy for week 1 (15 min)
- Virtual coffee with one new teammate per day, week 1
- Async video intro (Loom): 2-min "who I am" shared in #engineering

### Timezone considerations  
- Overlap hours clearly defined in team handbook
- Async-first decisions: GitHub Discussions, Notion, Linear comments
- Record all architecture meetings for replay

---

Working With Viprasol

We help engineering teams design onboarding programs and build the tooling that makes them work — automated environment setup scripts, onboarding checklists, documentation frameworks, and engineering handbooks. Good onboarding is the highest-ROI investment for growing engineering organizations.

→ Talk to our team about engineering culture and processes.

---

See Also

• Developer Experience — DX as an ongoing investment
• Technical Writing for Developers — documentation that stays current
• Code Review Best Practices — integrating new engineers via code review
• Engineering Metrics — measuring onboarding success
• Web Development Services — engineering team support