developer-onboarding-doc

# 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

```bash
# 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

```bash
[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

```bash
# 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
- [ ] Li