Claude Code Team Onboarding Playbook (2026)

Onboarding a team to Claude Code takes 2-4 weeks to reach full productivity. Rushing it leads to wasted tokens, inconsistent output, and developer frustration. This playbook provides a week-by-week plan that scales from 2-person startups to 50-person teams.

Week 1: Foundation

Day 1-2: Install and Configure

Every team member:

  1. Install Claude Code CLI: 
    # Follow Anthropic's installation instructions
  2. Copy the team settings template: 
    cp team-config/user-settings.json ~/.claude/settings.json
  3. Verify setup: 
    claude --version
  4. Run the onboarding command (if your team has /onboard — see enterprise setup guide): Start Claude Code in your primary project and type /onboard.

Day 3-4: CLAUDE.md Orientation

Run a 30-minute team session covering:

  • What CLAUDE.md does and where it lives
  • Your team’s CLAUDE.md template (review each section)
  • How to add project-specific rules
  • The Karpathy principles: Don’t Assume, Don’t Hide Confusion, Surface Tradeoffs, Goal-Driven Execution

Assign homework: each developer adds one project-specific rule to CLAUDE.md based on a problem they have encountered.

Day 5: First Supervised Session

Each developer runs a Claude Code session on a real task while a senior team member observes. Focus areas:

  • Is Claude Code following the CLAUDE.md rules?
  • Is the developer reviewing output before approving?
  • Are security policies being followed?

Week 2: Skill Building

Day 6-7: Prompt Engineering Workshop

Teach the team how to write effective prompts:

Bad prompt: “Fix the login” Good prompt: “The login form at src/components/LoginForm.tsx throws a TypeError on line 42 when the email field is empty. Add null checking for the email input before the validation call.”

Cover:

  • Specifying file paths and line numbers
  • Defining acceptance criteria
  • Setting scope boundaries (“only modify this file”)
  • Using the claude-howto visual guides as reference

Day 8-9: Hooks and Commands

Introduce the team to the project hooks:

{
  "hooks": {
    "post-tool-use": [
      { "tool": "write_file", "command": "npx eslint --fix $FILE 2>/dev/null" },
      { "tool": "write_file", "command": "npx tsc --noEmit 2>&1 | head -10" }
    ]
  }
}

Show how hooks auto-catch issues. Demonstrate slash commands for team workflows (/review, /deploy).

Day 10: Independent Work

Developers work independently with Claude Code on assigned tasks. Collect feedback:

  • What worked well?
  • What was confusing?
  • What rules need adding to CLAUDE.md?

Week 3: Optimization

Day 11-12: Cost Awareness

Install ccusage and show the team their spending:

npx ccusage

Teach cost optimization:

  • Scope sessions to specific directories
  • Use .claudeignore to skip irrelevant files
  • Keep CLAUDE.md under 2,000 words
  • End sessions when the task is complete (do not continue chatting)

Day 13-14: Advanced Patterns

Introduce based on team readiness:

Day 15: CLAUDE.md Refinement

Review the team’s accumulated CLAUDE.md additions. Consolidate, remove duplicates, and organize into clear sections. This is the team’s living configuration document.

Week 4: Integration

Day 16-17: CI/CD Integration

Add Claude Code to your pipeline for:

  • Automated code review on PRs
  • API mode for generating test stubs
  • Documentation generation from code changes

See the CI/CD integration guide for patterns.

Day 18-19: Team Workflow Refinement

Based on two weeks of usage, refine:

  • Which tasks are best suited for Claude Code?
  • What is the average time savings per task?
  • Which CLAUDE.md rules have the highest impact?
  • Are there common mistakes to add as rules?

Day 20: Retrospective

Run a team retrospective:

  • Keep: What practices should we continue?
  • Start: What should we add to our Claude Code workflow?
  • Stop: What is not working or costing too much?
  • Measure: Set productivity metrics for the next quarter

Onboarding Metrics

Track these to measure onboarding success:

Metric Week 1 Target Week 4 Target
Sessions per developer per day 1-2 5-10
Avg tokens per task High (learning) 40% reduction
CI failures from Claude Code output ~30% <10%
CLAUDE.md rules 5-10 20-30
Team satisfaction (1-5) 3 4+

Onboarding Resources

Point developers to these ecosystem resources:

Common Onboarding Mistakes

  1. No CLAUDE.md before first session. Developers get inconsistent results and blame the tool.
  2. No cost monitoring. A developer burns $200 in a week without realizing it.
  3. No security rules. Hardcoded secrets appear in the first PR.
  4. Too many rules too fast. A 5,000-word CLAUDE.md overwhelms both the developer and the context window.
  5. No feedback loop. Problems are not captured as CLAUDE.md rules.

Find the right skill → Browse 155+ skills in our Skill Finder.

FAQ

Find commands → Search all commands in our Command Reference.

Configure MCP → Build your server config with our MCP Config Generator.

Try it: Paste your error into our Error Diagnostic for an instant fix.

How long until developers are productive?

Most developers see net productivity gains by week 2. Full proficiency (knowing when and how to use Claude Code effectively) takes 3-4 weeks.

Should we mandate Claude Code usage?

No. Let developers adopt at their own pace. Mandate the CLAUDE.md template and security rules, but let usage be voluntary.

What if a developer prefers Cursor?

Both tools work with CLAUDE.md-style configuration. The team conventions still apply. See the Claude Code vs Cursor comparison.

How do we handle developers who over-rely on Claude Code?

Set guidelines: Claude Code is a tool, not a replacement for understanding the code. Require code review for all AI-generated changes. Periodically review AI-assisted PRs for quality.

For enterprise configuration, see the enterprise setup guide. For building team-specific skills, read the skill building guide. For the full CLAUDE.md reference, see the CLAUDE.md best practices guide.