---

name: dev-onboarding-builder description: Creates comprehensive developer onboarding documentation and materials including step-by-step setup guides, first-task assignments, expected time per step, common troubleshooting, team introductions, and code walkthrough tours. Use when preparing "new developer onboarding", "first day setup", "junior dev training", or "team member onboarding".

Developer Onboarding Builder

Create frictionless first-day experiences for new team members.

Core Workflow

1. Assess prerequisites: Identify required tools and access
2. Create setup guide: Step-by-step environment configuration
3. Design first task: Choose appropriate starter assignment
4. Add time estimates: Set expectations for each step
5. Document common issues: Preemptive troubleshooting
6. Introduce team: Context on people and structure
7. Provide codebase tour: Walkthrough of key areas

Onboarding Documentation Structure

ONBOARDING.md Template

Copy# Welcome to [Team/Project Name]! 🎉

This guide will help you get set up and productive on your first day.

**Estimated completion time:** 2-3 hours

## Before You Start

### Access Checklist

- [ ] GitHub organization access
- [ ] Slack workspace invitation
- [ ] Email account setup
- [ ] VPN credentials (if remote)
- [ ] Cloud console access (AWS/GCP/Azure)
- [ ] CI/CD dashboard access
- [ ] Project management tool (Jira/Linear)

### Tools to Install

- [ ] Node.js 20+ (via [Volta](https://volta.sh/))
- [ ] pnpm 8+
- [ ] Docker Desktop
- [ ] PostgreSQL 15+
- [ ] VS Code or preferred editor
- [ ] Git configured with your work email

## Day 1: Environment Setup

### Step 1: Clone Repository (5 min)

```bash
git clone git@github.com:company/project-name.git
cd project-name
```

Why: Get the codebase on your machine

Troubleshooting:

• SSH key not working? See GitHub SSH setup
• Permission denied? Ask your manager to verify GitHub access

Step 2: Install Dependencies (10 min)

Copy# Install Volta (Node version manager)
curl https://get.volta.sh | bash

# Install dependencies
pnpm install

Expected output: "Dependencies installed successfully"

Troubleshooting:

• pnpm not found? Restart terminal or run volta install pnpm
• Installation hangs? Check VPN connection

Step 3: Configure Environment (10 min)

Copy# Copy environment template
cp .env.example .env

Edit .env with these values:

CopyDATABASE_URL=postgresql://postgres:password@localhost:5432/projectname_dev
REDIS_URL=redis://localhost:6379
API_KEY=ask-team-for-dev-key

Get credentials from:

• Database: Local setup (see next step)
• API keys: Ask @alice or @bob on Slack #dev-onboarding
• External services: Check 1Password vault "Dev Credentials"

Troubleshooting:

• Can't find credentials? Post in #dev-onboarding
• Missing env var? Check .env.example for all required variables

Step 4: Setup Database (15 min)

Copy# Start PostgreSQL with Docker
docker run --name project-postgres \
  -e POSTGRES_PASSWORD=password \
  -p 5432:5432 \
  -d postgres:15

# Run migrations
pnpm db:migrate

# Seed with test data
pnpm db:seed

Expected output: "Migration complete. Database seeded."

Verify: Open http://localhost:5432 and check for tables

Troubleshooting:

• Port 5432 already in use? Kill existing process: lsof -ti:5432 | xargs kill
• Migration fails? Drop and recreate: pnpm db:reset

Step 5: Start Development Server (5 min)

Copypnpm dev

Expected output:

Copy✓ Ready on http://localhost:3000

Test: Open http://localhost:3000 - you should see the homepage

Troubleshooting:

• Port 3000 in use? Kill process or change PORT in .env
• Build errors? Clear cache: rm -rf .next && pnpm dev

Step 6: Run Tests (5 min)

Copypnpm test

Expected output: All tests passing ✓

If tests fail:

• First time? This is a bug! Report in #dev-help
• Known issue? Check #dev-help pinned messages

Day 1: Your First Task

Task: Fix a Starter Issue

We've labeled some issues as good-first-issue for new team members.

Goal: Successfully complete one small PR to learn our workflow

Steps:

1. Browse good first issues
2. Pick one that interests you (or ask for suggestion in #dev-onboarding)
3. Comment on the issue: "I'll take this!"
4. Create a branch: git checkout -b fix/issue-123-description
5. Make your changes
6. Write/update tests
7. Run pnpm lint and pnpm test
8. Commit following conventions
9. Push and create PR
10. Request review from your mentor

Estimated time: 2-4 hours

Success criteria:

• Branch created with proper name
• Code changes made
• Tests written/updated
• All checks passing
• PR created with description
• Code reviewed and merged

Mentors: @alice (backend), @bob (frontend), @charlie (full-stack)

Day 2-3: Codebase Tour

Project Structure Overview

Copysrc/
├── app/              # Next.js routes (start here!)
│   ├── api/          # API endpoints
│   └── (auth)/       # Authentication pages
├── components/       # React components
│   ├── ui/           # Base UI components
│   └── features/     # Feature-specific components
├── lib/              # Utilities and helpers
│   ├── api/          # API client
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helper functions
├── services/         # Business logic layer
└── types/            # TypeScript definitions

Key Files to Understand

Walking Tour (Read These Files in Order)

1. src/app/page.tsx - Homepage (entry point)
2. src/app/api/users/route.ts - Simple API endpoint
3. src/services/user.service.ts - Business logic example
4. src/components/ui/button.tsx - UI component pattern
5. src/lib/hooks/useUser.ts - Custom hook example

Exercise: Find the code that handles user registration. Hint: Start at the API route!

Common Patterns

API Route Pattern

Copy// src/app/api/[resource]/route.ts
export async function GET(req: Request) {
  // 1. Validate auth
  // 2. Parse request
  // 3. Call service layer
  // 4. Return response
}

Service Layer Pattern

Copy// src/services/[resource].service.ts
export class UserService {
  async create(data: CreateUserDto) {
    // 1. Validate data
    // 2. Business logic
    // 3. Database operation
    // 4. Return result
  }
}

Week 1: Learning Path

Day 1

• Complete environment setup
• Fix first issue
• Meet your team (schedule 1:1s)

Day 2-3

• Read codebase tour documents
• Complete second issue (medium complexity)
• Review 2-3 PRs from teammates

Day 4-5

• Work on first feature (with mentor pairing)
• Attend team standup/planning
• Set up development tools (linters, extensions)

Team Structure

Engineering Team

Alice (@alice) - Tech Lead

• Approves architecture decisions
• Code review on complex PRs
• Ask: System design questions

Bob (@bob) - Senior Backend Engineer

• Database and API expert
• Ask: Backend, performance questions

Charlie (@charlie) - Senior Frontend Engineer

• UI/UX implementation
• Ask: React, styling questions

Your Manager (@manager)

• Weekly 1:1s on Fridays 2pm
• Career development discussions
• Ask: Process, priorities, career questions

Communication Channels

• #dev-general - General development discussion
• #dev-help - Ask questions, get unstuck
• #dev-onboarding - New member support
• #dev-releases - Release announcements
• #dev-alerts - Production alerts

Meeting Schedule

• Daily Standup - 10:00 AM (15 min)
• Sprint Planning - Mondays 2:00 PM (1 hour)
• Team Retro - Fridays 4:00 PM (45 min)
• Tech Talks - Thursdays 3:00 PM (30 min)

Development Workflow

Daily Workflow

1. Morning: Check Slack, pull latest main
2. Standup: Share yesterday, today, blockers
3. Code: Work on assigned tickets
4. Lunch: Team usually eats at 12:30
5. Afternoon: Continue coding, review PRs
6. End of day: Update ticket status, push work

PR Review Guidelines

When reviewing PRs:

• Check code quality and style
• Verify tests cover changes
• Run the code locally if significant
• Ask questions if unclear
• Approve when satisfied

Getting Code Reviewed

When requesting review:

• Self-review first
• Add clear description
• Link related issues
• Tag appropriate reviewers
• Address feedback promptly

Common Gotchas

Database

Problem: relation "users" does not exist Solution: Run migrations: pnpm db:migrate

Problem: Seed data not appearing Solution: Reset database: pnpm db:reset

Development Server

Problem: Changes not reflecting Solution:

1. Hard refresh (Cmd+Shift+R)
2. Clear .next folder: rm -rf .next
3. Restart dev server

Problem: Port already in use Solution: Kill process: lsof -ti:3000 | xargs kill

Environment

Problem: Missing environment variable Solution: Check .env.example, add to your .env

Problem: API key not working Solution: Verify it's the dev key, not prod (ask team)

Resources

Documentation

• Architecture Overview
• API Reference
• Contributing Guide
• Style Guide

Learning Resources

• Next.js Documentation
• Prisma Guides
• TypeScript Handbook

Internal Resources

• Company Wiki: https://wiki.company.com
• Design System: https://design.company.com
• API Playground: https://api-dev.company.com

Getting Help

When You're Stuck (5-15-30 Rule)

• 5 minutes: Try to solve it yourself
• 15 minutes: Search docs, Stack Overflow, past issues
• 30 minutes: Ask in #dev-help with context

Good Question Template

Copy**What I'm trying to do:** [goal]
**What I tried:** [attempts]
**Error message:** [full error]
**Environment:** [OS, Node version, etc.]
**Related code:** [link to file/line]

Who to Ask

• Setup issues: #dev-onboarding or #dev-help
• Code questions: #dev-help or your mentor
• Process questions: Your manager
• Urgent/production: #dev-alerts

Week 1 Checklist

By end of week 1, you should have:

• Completed environment setup
• Fixed 2-3 good-first-issues
• Created first feature PR
• Met with all team members
• Attended all team meetings
• Read key documentation
• Understood development workflow
• Know how to get help

Feedback

We're always improving onboarding! Please share:

• What went well?
• What was confusing?
• What's missing?

Share in: #dev-onboarding or with your manager

---

Welcome to the team! We're excited to have you here! 🚀

Copy
## Onboarding Best Practices

### Time Estimates
- Be realistic with timing
- Include buffer for troubleshooting
- Track actual time vs estimated

### Progressive Complexity
- Day 1: Setup and simple task
- Week 1: Understanding patterns
- Month 1: Independent features

### Clear Success Criteria
- Checklist for each step
- Objective completion markers
- Regular check-ins

### Preemptive Troubleshooting
- Document known issues
- Provide solutions upfront
- Update based on new dev feedback

### Human Connection
- Introduce team members
- Schedule 1:1s
- Provide mentors

## First Task Selection Criteria

Good first task should:
- [ ] Be completable in 2-4 hours
- [ ] Touch multiple areas lightly
- [ ] Have clear acceptance criteria
- [ ] Require PR and review
- [ ] Be genuinely useful (not busy work)
- [ ] Have mentor availability

**Examples:**
- Fix typo in error message (touches: frontend, i18n, testing)
- Add validation to API endpoint (touches: backend, testing, docs)
- Improve loading state (touches: frontend, UX, components)

## Documentation Components

### Essential Sections
1. Prerequisites and access
2. Step-by-step setup with time estimates
3. First task assignment
4. Codebase tour
5. Team structure
6. Communication channels
7. Common issues and solutions
8. Resources and next steps

### Optional but Valuable
- Video walkthrough
- Pair programming schedule
- Reading list
- Architecture diagrams
- Glossary of terms

## Maintenance

### Keep Updated
- Review after each new hire
- Update tool versions
- Refresh access instructions
- Add new common issues

### Collect Feedback
- Exit survey after week 1
- Regular check-ins
- Track time to productivity
- Document pain points

## Output Checklist

Complete onboarding package includes:

- [ ] ONBOARDING.md with step-by-step guide
- [ ] Time estimates for each step
- [ ] First task identified and documented
- [ ] Team structure and communication
- [ ] Troubleshooting for common issues
- [ ] Links to all necessary resources
- [ ] Checklists for progress tracking
- [ ] Feedback mechanism
- [ ] Mentor assignments
- [ ] Expected timeline (day/week/month)