Onboarding and Team Workflows

Starting a new job used to mean weeks of poking around, feeling dumb, and bothering people who clearly have better things to do. You read a README that was last updated in 2022. You grep through the codebase hoping to find a pattern you recognize. You message the team's senior engineer with questions you worry are obvious.

Claude Code makes most of that optional.

A new developer can open a terminal and just ask the codebase questions. It's like having a patient, infinitely available teammate sitting next to you. No judgment. No "hey quick question" guilt.

Ask the Codebase Anything

Just ask. No special prompting syntax, no clever framing. Talk to it like you would talk to a coworker.

How does logging work in this project?

How do I create a new API endpoint? Walk me through the pattern.

What does `async move { ... }` do on line 134 of foo.rs?

What edge cases does CustomerOnboardingFlowImpl handle?

Why does this code call foo() instead of bar() on line 333?

Claude Code reads the actual source files, traces call chains, and gives you answers grounded in real code. Not documentation that might be stale. Not a colleague's half-remembered explanation from six months ago. The actual implementation, right now.

This takes huge pressure off your team. Instead of pinging a senior engineer every time you hit a confusing abstraction, you ask Claude Code first. Save the human questions for design decisions where context and intent matter more than code.

The /init Command

Every team project should have a CLAUDE.md file at its root. Run /init to generate a starter if one doesn't exist.

claude

Then inside the session:

/init

Claude Code analyzes your codebase structure, package files, build scripts, and existing configuration. It produces a CLAUDE.md covering build commands, test instructions, code style conventions, and project-specific patterns. The generated version is a solid starting point, but review it. Refine it. Make it yours.

Commit this file to version control. Every developer on the team benefits from it, and so does every Claude Code session they run. Five minutes of setup that keeps paying off in every future session.

Team Conventions in CLAUDE.md

A good CLAUDE.md goes way beyond build commands. It encodes your team's conventions so Claude Code follows them automatically. Think of it as onboarding documentation that actually gets read, every single time.

# Project Instructions
 
## Build and Test
- Build: `npm run build`
- Test: `npm run test`
- Lint: `npm run lint`
 
## Code Conventions
- Use server components by default. Only add "use client" for interactivity.
- All API routes return `{ data, error }` shape.
- Database queries go through the repository layer, never called directly from routes.
- Error messages must be user-facing friendly. Log technical details separately.
 
## Git Workflow
- Branch naming: feature/TICKET-123-short-description
- Commit messages: imperative mood, under 72 characters
- Always run tests before committing

When a new developer joins, they don't need to memorize any of this. Claude Code reads it on every session start and follows it automatically. Way better than a Confluence page nobody reads.

Shared Skills and Commands

Skills extend Claude Code with reusable workflows specific to your team. Create them as markdown files in .claude/skills/ and commit them to your repo.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
 
Analyze and fix the GitHub issue: $ARGUMENTS.
 
1. Use gh issue view to get the issue details
2. Understand the problem
3. Search the codebase for relevant code
4. Implement the fix
5. Write and run tests
6. Create a descriptive commit message
7. Push and create a PR

Any team member types /fix-issue 1234 and Claude Code follows the same structured process. Workflows that used to live in someone's head or a wiki nobody updates are now executable.

Custom slash commands work similarly. Drop markdown files in .claude/commands/ and they show up as /command-name in every session. Skills are more flexible since they support arguments and Claude Code can invoke them on its own during complex tasks.

Collaborative Patterns

Writer/Reviewer

Run two Claude Code sessions side by side. One writes, one reviews.

Session A (Writer):

Implement a rate limiter for our API endpoints using a sliding window algorithm.

Session B (Reviewer):

Review the rate limiter implementation in src/middleware/rate-limiter.ts.
Look for edge cases, race conditions, and missing error handling.

Take the review feedback back to Session A:

Here is the review feedback. Address these issues: [paste feedback]

The reviewer session has fresh context and no bias toward the code it's examining. It catches things the writer session can't see.

Subagents for Investigation

When you need Claude Code to research something without cluttering your main conversation, use subagents.

Use subagents to investigate how our authentication system handles token refresh,
and whether we have any existing OAuth utilities I should reuse.

Subagents spin up separate investigation threads, dig through files, trace dependencies, and report findings back to your main session. Your primary context stays clean.

Interview Me for Specs

For bigger features, the interview pattern builds a complete spec before a single line of code gets written.

I want to build a notification system for our app. Interview me in detail
using the AskUserQuestion tool. Ask about technical implementation, UI/UX,
edge cases, concerns, and tradeoffs. Keep interviewing until we have covered
everything, then write a complete spec to SPEC.md.

Claude Code asks targeted questions, often surfacing edge cases you hadn't considered. Once the spec is complete, start a fresh session to execute it. Clean context keeps Claude Code focused on implementation instead of revisiting design decisions.

Try It: Onboard Into Your Own Codebase

Pick a project you haven't touched in a while, or a repo you've been meaning to explore.

1. Open it in Claude Code and run /init to generate a CLAUDE.md if one doesn't exist.

2. Ask five questions about the codebase as if you were a new hire:

What is the overall architecture of this project?
Where does authentication happen?
How are database migrations handled?
What is the testing strategy?
What would I need to change to add a new API endpoint?

3. Create a skill file at .claude/skills/explore.md:

---
name: explore
description: Explore an unfamiliar area of the codebase
---
 
Investigate $ARGUMENTS in this codebase.
1. Find all relevant files
2. Trace the main code paths
3. Identify key abstractions and patterns
4. Summarize how it works in plain language
5. Note any potential issues or tech debt

4. Test it by running /explore the payment processing flow (or whatever is relevant to your project).

You'll be surprised how quickly you build a mental model this way compared to reading code alone.

What Sticks

Claude Code is the best first stop for codebase questions. Just ask. Save human engineers for decisions that need context and judgment.

Run /init, refine the output, commit it. Shared skills in .claude/skills/ standardize team workflows. If a process lives in someone's head, it should live in a skill file instead.

The writer/reviewer two-session pattern catches bugs a single session never will. And interview-driven spec writing forces you to think through edge cases before code exists. Generate the spec, then start fresh to implement.