Developer Onboarding Builder

Create frictionless first-day experiences for new team members.

Core Workflow

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

Onboarding Documentation Structure

ONBOARDING.md Template

markdown

# 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)

bash

# 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)

bash

# Copy environment template
cp .env.example .env

Edit
.env
with these values:

DATABASE_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)

bash

# 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)

bash

pnpm dev

Expected output:

✓ 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)

bash

pnpm 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:

Browse good first issues
Pick one that interests you (or ask for suggestion in #dev-onboarding)
Comment on the issue: "I'll take this!"

Create a branch:

git checkout -b fix/issue-123-description

Make your changes
Write/update tests
Run
```
pnpm lint
```
and
```
pnpm test
```
Commit following conventions
Push and create PR
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

src/
├── 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

File	What It Does	When You'll Touch It
`src/app/layout.tsx`	Root layout & providers	Adding global providers
`src/lib/db.ts`	Database client	Database queries
`src/lib/auth.ts`	Authentication logic	Auth-related features
`src/middleware.ts`	Request middleware	Adding auth/redirects

Walking Tour (Read These Files in Order)

src/app/page.tsx
- Homepage (entry point)
src/app/api/users/route.ts
- Simple API endpoint
src/services/user.service.ts
- Business logic example
src/components/ui/button.tsx
- UI component pattern
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

typescript

// 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

typescript

// 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

Morning: Check Slack, pull latest main
Standup: Share yesterday, today, blockers
Code: Work on assigned tickets
Lunch: Team usually eats at 12:30
Afternoon: Continue coding, review PRs
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:

Hard refresh (Cmd+Shift+R)
Clear .next folder:
```
rm -rf .next
```
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

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

**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! 🚀


## 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)

dev-onboarding-builder

NPX Install

Tags

SKILL.md Content

Developer Onboarding Builder

Core Workflow

Onboarding Documentation Structure

ONBOARDING.md Template

Step 2: Install Dependencies (10 min)

Step 3: Configure Environment (10 min)

Step 4: Setup Database (15 min)

Step 5: Start Development Server (5 min)

Step 6: Run Tests (5 min)

Day 1: Your First Task

Task: Fix a Starter Issue

Day 2-3: Codebase Tour

Project Structure Overview

Key Files to Understand

Walking Tour (Read These Files in Order)

Common Patterns

Week 1: Learning Path

Day 1

Day 2-3

Day 4-5

Team Structure

Engineering Team

Communication Channels

Meeting Schedule

Development Workflow

Daily Workflow

PR Review Guidelines

Getting Code Reviewed

Common Gotchas

Database

Development Server

Environment

Resources

Documentation

Learning Resources

Internal Resources

Getting Help

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

Good Question Template

Who to Ask

Week 1 Checklist

Feedback