Developer Onboarding Document Skill

Produce a complete developer onboarding document for a service or team — covering everything a new engineer needs to be productive within their first week.

A good onboarding doc is not a wiki dump. It answers the questions a new engineer actually has on day one, in the order they'll have them.

Required Inputs

Ask for these if not already provided:

Service name and what it does
Team responsible for it
Tech stack — language(s), framework(s), database(s), message queues, etc.
Key external dependencies — upstream services, third-party APIs
Deployment target — Kubernetes, ECS, Lambda, bare metal, etc.
Local dev setup — how to run locally (Docker Compose, local DB, etc.)
Testing approach — unit, integration, E2E; test commands
Deployment process — summary of how code gets to production
On-call setup — who's on-call, how alerts work
Contacts — tech lead, platform team, related service owners

Output Format

Developer Onboarding: [Service Name]

Team: [Team name] | Tech lead: [Name] Last updated: [Date] | Updated by: [Name]

If something in this doc is wrong or out of date, fix it now — it will affect every engineer who onboards after you.

What This Service Does

[3–5 sentences. What problem does this service solve? Who calls it, and who does it call? What would break if this service went down?]

Service type: [API / Background worker / Event consumer / Data pipeline / etc.] Consumers: [List internal services or external clients that depend on this service] Dependencies: [List upstream services, databases, and third-party APIs this service calls]

Architecture diagram: [Link or embed — even a rough ASCII diagram helps]

[Caller A] ──→ [This Service] ──→ [Database]
                      │
                      └──→ [Downstream Service]

Codebase Orientation

Repository: [Link] Main branch: [main / master] Language: [e.g. Go 1.22 / Node.js 20 / Python 3.12] Framework: [e.g. Express / FastAPI / Gin / Rails]

Key directories

[repo-root]/
├── [src/ or cmd/]          # Application code
│   ├── [handlers/]         # HTTP handlers / controllers
│   ├── [services/]         # Business logic
│   ├── [repository/]       # Database access layer
│   └── [models/]           # Data models / types
├── [tests/]                # Test files
├── [migrations/]           # Database migrations
├── [scripts/]              # Utility scripts
├── [.github/workflows/]    # CI/CD pipeline definitions
└── [docs/]                 # Additional documentation

Where to start reading: [Point to 2–3 key files that give the best orientation — e.g. main.go, routes.js, app.py]

Things that might surprise you

[Unusual pattern 1 — e.g. "We use event sourcing — state is derived from an event log, not stored directly"]
[Unusual pattern 2 — e.g. "Auth is handled by the gateway — this service trusts the X-User-Id header"]
[Unusual pattern 3 — any non-obvious decisions or legacy choices]

Local Development Setup

Estimated setup time: [X minutes for a fresh machine]

Prerequisites

[Tool 1] — version [X] — [install link]
[Tool 2] — version [X] — [install link]
Access to [repo / internal package registry] — request from [who]
[Any secrets or credentials needed] — request from [who]

Step-by-step setup

# 1. Clone the repo
git clone [repo URL]
cd [repo-name]

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env — see "Environment Variables" section below

# 3. Start dependencies (database, cache, etc.)
[docker compose up -d / make deps / etc.]

# 4. Install dependencies
[npm install / go mod download / pip install -r requirements.txt]

# 5. Run database migrations
[migration command]

# 6. Start the service
[start command]

# 7. Verify it's working
curl http://localhost:[PORT]/health
# Expected: {"status":"ok"}

If this doesn't work: Check [Troubleshooting section below] or ask in #[channel].

Environment Variables

Variable	Required	Description	Example
`DATABASE_URL`	Yes	Connection string for the primary DB	`postgres://localhost:5432/[db]`
`[VAR_2]`	Yes	[Description]	[Example]
`[VAR_3]`	No	[Description — default value]	[Example]

Secrets for local dev: [Where to get them — e.g. "Run [command] to pull from Vault" or "Ask [person] in #[channel]"]

Useful local commands

[start command]           # Start the service
[test command]            # Run all tests
[lint command]            # Run linter
[format command]          # Format code
[migration command]       # Run pending migrations
[seed command]            # Seed local database

Testing

Testing philosophy: [e.g. "We test at the integration layer — unit tests for pure functions, integration tests for anything touching the DB or external services"]

Running tests

# All tests
[test command]

# Unit tests only
[unit test command]

# Integration tests (requires local deps running)
[integration test command]

# A specific test file or test case
[test command with filter]

Test coverage: [X]% (minimum required to pass CI: [Y]%) Coverage report: [Where to find it]

Writing tests

Unit tests: [Where to put them — e.g. alongside source files as *_test.go]
Integration tests: [Where to put them — e.g. tests/integration/]
Test database: [How it works — e.g. "Each test gets a clean transaction that rolls back on teardown — see tests/helpers/db.go"]
Mocking: [Policy — e.g. "We mock at the repository layer — don't mock the DB directly"]

Making Changes

Branching

[Branch naming convention — e.g. feature/[ticket-id]-short-description, fix/[ticket-id]-short-description]

Before opening a PR

Tests pass locally
Linter passes ([lint command])
New behaviour has test coverage
Any new environment variables are added to .env.example and documented
Database migrations are backward-compatible (old code can run against new schema)

Code review

Reviewers: [Who to request review from — e.g. "Any engineer on [team]; lead review required for auth changes"]
Expected review time: [X hours / 1 business day]
PR template: [Link or auto-generated by GitHub]

Database migrations

# Create a new migration
[migration create command]

# Apply pending migrations
[migration up command]

# Roll back last migration
[migration down command]

Migration rules:

All migrations must be backward-compatible — old code must run against the new schema
Never rename or drop a column in a single migration — do it in two steps (add new, migrate data, drop old)
Test your rollback before merging

Deployment

How code gets to production: [1–2 sentence summary — link to full CI/CD playbook if it exists]

Merge to main → automatic deploy to staging
Smoke tests run on staging
Manual approval → deploy to production
Post-deploy monitoring for [X minutes]

Deployment docs: [Link to CI/CD playbook or pipeline docs]

Who can deploy: [Any engineer / Lead engineer / On-call engineer — specify]

Deployment channel: #[deployments channel]

Monitoring and Observability

Dashboard: [Datadog / Grafana / CloudWatch — link] Logs: [Log aggregation tool and link — e.g. "Logs are in Datadog under service:[name]"] Traces: [Tracing tool and link if applicable] Alerts: [Where alerts fire — e.g. PagerDuty / Slack #alerts-[service]]

Key metrics to know:

Error rate: Should be <[X]% (alert at [Y]%)
P99 latency: Should be <[X]ms
[Business metric]: [e.g. "Queue depth should be <100 items"]

On-Call

On-call schedule: [PagerDuty / Opsgenie link] Who's on-call now: [Link to current schedule or #oncall channel] Escalation: [On-call → [team lead] → [EM] — after [X] minutes unacknowledged]

If you get paged:

Acknowledge the alert
Check [dashboard link] for the first clue
Common alert runbooks: [link to oncall-runbook or runbook-writer output]
If you can't resolve in [X minutes], escalate to [person/channel]

Key Contacts

Role	Name	Best way to reach
Tech lead	[Name]	Slack: @[handle]
On-call rotation	[Team]	PagerDuty / `#on-call`
Platform / infra	[Team]	`#platform` Slack channel
Database / DBA	[Name or team]	`#database` Slack channel
[Upstream service] owner	[Name]	Slack: @[handle]

Where to ask questions:

General engineering: #engineering
This service specifically: #[service-name]
Urgent / production issues: #incidents

Troubleshooting

"The service won't start locally"

Check that Docker / dependencies are running: [command]
Check .env is populated — missing values cause silent failures
Check logs: [log command]
Ask in #[channel]

"Tests are failing locally but passing in CI"

Check your local dependency versions match CI: [version check command]
Try a clean install: [clean install command]
Integration tests need local deps running — [start deps command]

"I can't access [internal tool / system]"

Request access through [process — e.g. Okta self-serve / ask your manager]

"Something looks wrong in production"

Check [dashboard] for the error spike
Check recent deploys in #deployments
If it's an active incident, page on-call via [PagerDuty / Slack command]

Quality Checks

Local setup instructions work on a fresh machine — tested recently
Environment variables table is complete and accurate
"Things that might surprise you" captures the actual surprises (ask a recent joiner)
On-call section has real links, not placeholders
Contacts are current — team members with real Slack handles
Troubleshooting covers the top 3 actual questions new joiners ask

Anti-Patterns

Do not document the ideal setup — document the actual setup; real oddities and gotchas are what new engineers need most
Do not leave placeholder contacts like "ask your manager" — name specific people for each domain or the doc becomes useless when the new joiner has an urgent question
Do not write the onboarding doc without reviewing it with a recent joiner — the author is blind to what they take for granted
Do not include every piece of architectural detail — an onboarding doc that covers everything teaches nothing; link to deeper docs instead
Do not skip the "things that might surprise you" section — undocumented non-obvious patterns are the number one cause of wasted engineering time in the first week

Developer Onboarding Doc