Anatomy of AI Onboarding Kit

Get new hires productive in their first week with Claude Code.

Onboarding Kit

Get a new hire productive with Claude Code in their first week — a repeatable, self-service kit that gives engineers the context, tools, and workflows to contribute safely and ship value fast.

TL;DR

An AI onboarding kit is the modern "developer welcome packet" — equipped with CLAUDE.md, slash commands, subagents, hooks, and MCP servers.
The goal: a meaningful merged PR by end of Week 1.
The kit is the repo itself + an onboarding/ folder with a 5-day path.
Day 1 = environment + first Claude session. Day 7 = retro + share learnings.
Faster ramp · lower friction · consistent quality · scalable growth.

Why this matters

The first week shapes the next year. With AI in the loop, onboarding isn't just "read this wiki" — it's "use Claude to navigate this codebase, ship a small change, and learn our patterns." Done well, this collapses ramp time from weeks to days and propagates your engineering standards through every prompt the new hire types.

Bottom line: The best onboarding kit gets you unblocked fast — and shipping value with confidence.

The Big Picture

Bottom line: Your onboarding kit is a complete system: Context → Tools → Workflows → Contribute.

What's in the Kit — Repo Structure

onboarding/
├── README.md                   # Start here
├── 00-getting-started.md       # Prereqs & install
├── 01-codebase-tour.md         # Architecture & key concepts
├── 02-setup-env.md             # Local dev setup
├── 03-claude-code.md           # How we use Claude Code
├── 04-workflows.md             # Daily dev, PR flow, rebases
├── 05-first-contribution.md    # Good first issues, captured learnings
├── 06-team.md                  # People, ceremonies, cadences
├── 07-security.md              # Security & scope
└── 08-troubleshooting.md       # Common dev/staging issues

agents/                         # Subagents the new hire can use
hooks/                          # Lint, tests, secret-scan hooks
docs/architecture.md            # Deeper system context
docs/decisions.md               # ADRs and tradeoffs
.github/                        # CI, issue templates

💡 Tip: Keep onboarding/ at the repo root and easy to discover.

The Claude Code Stack We Provide

Layer	Purpose
Claude Code CLI	Local AI pair programmer
`CLAUDE.md`	Project memory: stack, conventions, rules
Subagents	Specialists (reviewer, test-writer, docs-writer)
Slash commands	Encoded workflows (`/plan`, `/review`, `/deploy`)
Hooks	Guardrails (lint, secret-scan, audit)
MCP servers	Tools & data (GitHub, DB, Slack)

Starter `.claude/settings.json`

{
  "model": {
    "default": "claude-sonnet-4",
    "fallback": ["claude-haiku-4"]
  },
  "features": { "autoCompact": true },
  "hooks": {
    "PreToolUse":  [{ "matcher": "*",          "hooks": [{ "type": "command", "command": "./hooks/pre-tool.sh" }] }],
    "PostToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "npm run lint" }] }]
  }
}

💡 Also commit: .mcp.json, agents/, .claude/commands/, CLAUDE.md. Starter configs let new hires go from zero → productive in < 60 minutes.

Day-1 Checklist: Get Started Fast

✅ Clone the repo and read onboarding/README.md
✅ Install prerequisites (Node, pnpm, Docker, Claude Code)
✅ Run the bootstrap script: ./bootstrap.sh
✅ Set up .env from .env.example
✅ Start local services: pnpm dev
✅ Verify tests: pnpm test
✅ Open Claude Code and run /plan "Understand this codebase"
✅ Introduce yourself in #team-channel

Example `bootstrap.sh`

#!/usr/bin/env bash
set -e
pnpm install
cp -n .env.example .env || true
echo "# edit .env"
docker compose up -d redis postgres
pnpm db:seed
echo "✅ Environment ready!"

Result: Working dev environment + first Claude Code session.

The 1-Week Ramp Plan (at a glance)

Day	Theme	Activities
Day 1	Orients & sets up	Environment, repo tour, first Claude session
Day 2	Learns & explores	Codebase tour, key flows, run the app
Day 3	Small win	Pick a good first issue, ship a tiny PR
Day 4	Deepens	Implement a feature or fix, tests
Day 5	Reviews & polishes	Merge PR, observer, docs
Day 6	Ships value	Run `/retro`, feedback, plan next week
Day 7	Reflects	Share learnings, refine onboarding kit

🎯 Outcome: By Day 6, the new hire has merged a meaningful PR.

First Week Journey (Detailed)

Day 1 — Orient & Setup

Read onboarding/README.md + CLAUDE.md
Run bootstrap; verify tests pass
Open Claude Code; run /tour
Introduce yourself in #team-channel

Day 2 — Explore & Learn

Read docs/architecture.md
Run the app end-to-end
Ask /explain <module> for any unclear area
Shadow a PR review (sit with a teammate)

Day 3 — First Contribution

Pick a good first issue (label: good-first-issue)
Use /plan and /explain to build mental model
Implement + write tests
Open a draft PR

Day 4 — Deepen

Iterate on review feedback
Refactor or extend the small change
Add docs if needed

Day 5 — Polish & Review

Run /review (via @code-reviewer)
Address comments
Clean up & squash
Prepare to merge

Day 6 — Ship Value

PR approved & merged 🎉
Observe in dev/staging
Update tests if needed

Day 7 — Reflect & Plan

Run /retro
Provide feedback on the kit itself
Plan next week's focus
Share top learnings in #team-channel

💡 Tip: Adjust the journey for the role (see Variants below) — but keep the Day-7 retro in every variant.

Key Slash Commands to Use

Command	What it does
`/plan <task>`	Break down the task, risks, and plan of attack
`/explain <file\|module>`	Explain code, architecture, or patterns
`/tour <area>`	Guided tour of a folder / feature
`/review`	Run a full code review (uses `@code-reviewer`)
`/test`	Run tests, coverage, and reports
`/docs`	Generate or update documentation
`/deploy`	Deploy to dev/staging (if you have access)
`/retro`	Reflect on the day/week; capture learnings

💡 Tip: Run /help <command> to learn how to use each one.

Agents, Commands & Hooks We Ship

Example subagent — `agents/code-reviewer.yml`

name: code-reviewer
description: Reviews PRs for quality.
model: claude-sonnet-4
tools: [Read, Bash, Grep]
permissions:
  allow: ["Read", "Bash(npm test)"]
  deny:  ["WriteOutsideWorkspace"]
system_prompt: |
  You are a senior engineer.
  Use the repo context to break down the task into steps,
  risks, and success criteria.
triggers: ["review", "pr", "audit"]

Example command — `.claude/commands/plan.md`

---
description: Plan a task.
usage: /plan <task>
---
You are a senior engineer.
Use the repo context to break down the task into steps,
risks, and success criteria.

Example hook — `hooks/pre-tool.sh`

#!/usr/bin/env bash
case "$CLAUDE_TOOL_NAME" in
  Bash)
    if echo "$CLAUDE_TOOL_INPUT" | grep -Eq "rm -rf|sudo"; then
      echo "❌ Forbidden" >&2
      exit 1
    fi ;;
esac
exit 0

💡 Tip: Review agents, commands, and hooks to understand the team's guardrails.

Good First Tasks (Pick One)

✅ Fix a minor bug with a failing test
✅ Add a small feature behind a flag
✅ Improve docs or README for a module
✅ Add tests for an untested utility
✅ Refactor a small function
✅ Update a dependency with tests

Definition of Done (DoD)

✅ Tests pass
✅ Lint & typecheck clean
✅ Docs updated (if needed)
✅ Changelog entry
✅ PR reviewed & approved

💡 Tip: Small wins build confidence. Ship early, ship often.

Communication & Rituals

Ritual	Cadence	Purpose
🌅 Daily standup	10–15 min	Plan, blockers, wins, AI learnings
🔍 PR review	Continuous	Use `/review` + peer review. Be kind, be specific.
📚 Knowledge share	Weekly	Share prompts, agents, wins in the team wiki
🎉 Demo Friday	Weekly	Show what you built + why it matters

💡 Tip: Communication closes the loop. Share patterns, not just code.

Onboarding Success Metrics

Track how well your kit is working:

Metric	Target
⏱️ Time to first PR	< 3 days
🚀 Time to first merge	< 7 days
✅ PR acceptance rate	> 85%
🔁 Rework rate	< 15%
🧠 Context resets / day	Trending ↓
🤖 AI suggestions used	> 60%

Anti-patterns to avoid

🚫 Dumping huge context blindly
🚫 Asking vague questions
🚫 Skipping /review
🚫 Copy-pasting long logs
🚫 Over-trusting AI output
🚫 Not reading CLAUDE.md

💡 Tip: Measure, iterate, and make the kit itself better every week.

Variants for Different Team Settings

👤 Solo / very small team

Onboarding = a single onboarding/README.md with 5 steps and 3 slash commands.
Day-7 retro is a 15-minute self-debrief.
One agent: @code-reviewer.

👥 Small team (2–10)

Buddy system: assign an onboarding buddy for the first week.
Daily 10-min check-in with the buddy.
Shared agents/ + .claude/commands/.
Demo Friday is non-negotiable.

🏢 Enterprise / regulated

Add onboarding/00-compliance.md and onboarding/security-training.md.
Permissions tiered: read-only Claude on Day 1; write/PR on Day 3.
All agents/hooks/commands code-reviewed before use.
SIEM audit hook on every tool call.
Mandatory training: prompt safety, data handling.

🌍 Open-source / community

Onboarding kit doubles as CONTRIBUTING.md.
/onboard slash command in the public repo.
Good first issues labeled and curated.
New contributor PR template references /review.

Bottom line: Same kit, different dials.

Anatomy of Day 3 (zoom-in — the "first win" day)

00  Coffee + read backlog
15  Pick label:good-first-issue
20  /plan "fix bug X"           → step plan + risks
45  /explain src/services/x.ts  → mental model
15  Write failing test
00  Implement fix
30  npm test                    → green
45  /review                     → polish & risks
15  Open draft PR
30  Buddy walkthrough (15 min)
00  Address comments
00  Push for review
00  Pair with reviewer on edge case
00  EOD note in #team-channel + /retro

💡 Tip: Most onboarding flunks here. Pair generously on Day 3.

Step-by-Step Setup (for the team owner)

1. Create `onboarding/` at repo root

Use the structure above. Keep each file < 200 lines.

2. Write `onboarding/README.md` as the entry point

Link to every other file in the kit. Include the 1-week ramp at the top.

3. Author `CLAUDE.md`

Stack, conventions, security, decisions. This is your team's brain.

4. Ship the Claude stack

.claude/settings.json (starter)
.claude/commands/{plan,explain,tour,review,test,docs,deploy,retro}.md
agents/code-reviewer.yml
hooks/pre-tool.sh, hooks/post-tool.sh
.mcp.json (GitHub, your DB, Slack)

5. Add `bootstrap.sh`

One command sets up the dev environment.

6. Label good-first-issues

At least 5 ready at any time. Refresh weekly.

7. Assign onboarding buddies

Rotate weekly. Buddy attends Day-1 setup and Day-3 first PR.

8. Run the Day-7 retro

Always. Capture friction; ship kit improvements next sprint.

Common Patterns & Recipes

Pattern 1 — Self-service `/tour`

---
description: Guided tour of a folder or feature
usage: /tour <area>
---
You are a friendly senior engineer.
Walk the new hire through `{{area}}`:
1. Top 3 files to read first.
2. How requests flow through.
3. Common gotchas.
4. Where to put new code.
5. Suggested first 2 tweaks to try.

Pattern 2 — `/onboard` master command

---
description: Run the full onboarding checklist
usage: /onboard
---
Walk me through Days 1–7 step by step.
At each step, confirm completion and capture any blockers.

Pattern 3 — Buddy ledger

# Buddy Ledger — {{newhire_name}}
- Day 1: [ ] env, [ ] first /tour, [ ] intro
- Day 3: [ ] first draft PR
- Day 5: [ ] PR merged
- Day 7: [ ] retro complete, [ ] kit feedback captured

Pattern 4 — Day-7 retro template

# Onboarding Retro — Week 1

## What worked
-

## What didn't
-

## Surprises
-

## Suggestions for the kit
-

## Top 3 things I learned
-

Pattern 5 — Permission ramp-up

"permissions": {
  "day1": { "allow": ["Read", "WebSearch"], "deny": ["Write", "Bash"] },
  "day3": { "allow": ["Read", "Edit", "Bash(npm *)"], "deny": ["WriteOutsideWorkspace"] },
  "day5": "team-default"
}

Best Practices ✅

Make it self-service. A new hire should make progress without waiting for anyone.
Optimize for Day 3. That's when the first win happens.
Pair generously in week 1.
Capture feedback every cycle; the kit is a product.
Encode standards in agents & commands, not slide decks.
Celebrate the first merge. Loudly.

Anti-Patterns ❌

🚫 30-page wikis nobody reads.
🚫 "Figure it out yourself" Day-1 culture.
🚫 No good-first-issues queued.
🚫 Buddy assigned in name only.
🚫 Skipping the Day-7 retro.
🚫 Static kit that hasn't been updated in 6 months.
🚫 Same kit for every role (a data engineer ≠ a frontend dev).

Troubleshooting

Symptom	Likely cause	Fix
Day 1 setup takes > 4 hrs	Bootstrap script rotten	Run it monthly in CI on a fresh container
New hire has no first issue	Backlog not curated	Standing 30-min weekly "first-issue grooming"
First PR > 2 weeks	Issue too big	Split issues into < 4-hr slices
AI suggestions ignored	Vague `CLAUDE.md`	Tighten with examples
Repeated same questions	Missing FAQ	Add to `08-troubleshooting.md`
Kit drifts from reality	No owner	Assign a kit owner; review monthly
Buddy overloaded	Single buddy for many hires	Rotate weekly; group cohort onboarding

Starter Pack (Minimal)

.claude/
├── settings.json
└── commands/
    ├── plan.md
    ├── explain.md
    ├── tour.md
    ├── review.md
    ├── test.md
    ├── docs.md
    ├── deploy.md
    └── retro.md
agents/
└── code-reviewer.yml
hooks/
├── pre-tool.sh
└── post-tool.sh
.mcp.json
CLAUDE.md
bootstrap.sh
onboarding/
├── README.md
├── 00-getting-started.md
├── 01-codebase-tour.md
├── 02-setup-env.md
├── 03-claude-code.md
├── 04-workflows.md
├── 05-first-contribution.md
├── 06-team.md
├── 07-security.md
└── 08-troubleshooting.md

💡 Tip: Start with this skeleton. Adjust for your stack and role profile.

Quick Start (for the new hire) — 7 steps

Day 1: Read onboarding/README.md + CLAUDE.md, run ./bootstrap.sh.
Day 2: /tour your way through the codebase.
Day 3: Pick a good-first-issue; /plan it; open a draft PR.
Day 4: Address feedback; iterate.
Day 5: /review; clean up; prepare to merge.
Day 6: PR merged 🎉; observe in dev/staging.
Day 7: /retro; share learnings; suggest kit improvements.

Glossary

Onboarding kit — A curated set of docs, configs, and AI workflows that ramp a new hire.
Good first issue — A well-scoped task (≤ 4 hrs) ideal for a first PR.
Buddy — A teammate who shepherds the new hire through Week 1.
DoD (Definition of Done) — Shared bar for "complete."
/tour / /explain — Slash commands that guide the new hire through the code.
Permission ramp-up — Gradually expanding what Claude is allowed to do.
Kit owner — Person responsible for keeping the kit fresh.

🪙 Your Mantras

🎯 Curate context. Feed signal, not noise.
🧠 Right model, right task, right time.
🏆 Small wins > perfect plans.
🔍 Review everything. Trust, but verify.
📝 Document as you go. Future-you will thank you.

Remember: The best onboarding kit gets you unblocked fast, shipping value with confidence.

TL;DR​

Why this matters​

The Big Picture​

What's in the Kit — Repo Structure​

The Claude Code Stack We Provide​

Starter .claude/settings.json​

Day-1 Checklist: Get Started Fast​

Example bootstrap.sh​

The 1-Week Ramp Plan (at a glance)​

First Week Journey (Detailed)​

Day 1 — Orient & Setup​

Day 2 — Explore & Learn​

Day 3 — First Contribution​

Day 4 — Deepen​

Day 5 — Polish & Review​

Day 6 — Ship Value​

Day 7 — Reflect & Plan​

Key Slash Commands to Use​

Agents, Commands & Hooks We Ship​

Example subagent — agents/code-reviewer.yml​

Example command — .claude/commands/plan.md​

Example hook — hooks/pre-tool.sh​

Good First Tasks (Pick One)​

Definition of Done (DoD)​

Communication & Rituals​

Onboarding Success Metrics​

Anti-patterns to avoid​

Variants for Different Team Settings​

👤 Solo / very small team​

👥 Small team (2–10)​

🏢 Enterprise / regulated​

🌍 Open-source / community​

Anatomy of Day 3 (zoom-in — the "first win" day)​

Step-by-Step Setup (for the team owner)​

1. Create onboarding/ at repo root​

2. Write onboarding/README.md as the entry point​

3. Author CLAUDE.md​

4. Ship the Claude stack​

5. Add bootstrap.sh​

6. Label good-first-issues​

7. Assign onboarding buddies​

8. Run the Day-7 retro​

Common Patterns & Recipes​

Pattern 1 — Self-service /tour​

Pattern 2 — /onboard master command​

Pattern 3 — Buddy ledger​

Pattern 4 — Day-7 retro template​

Pattern 5 — Permission ramp-up​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Starter Pack (Minimal)​

Quick Start (for the new hire) — 7 steps​

Glossary​

Further Reading​

🪙 Your Mantras​