Skip to content

Onboarding a new member

A new teammate joining an AI-fluent team faces two learning curves at once: the codebase and the way the team uses AI. The second one is easy to underestimate — they can install the same tools you have and still be far less effective, because the tools are only half of it. Good onboarding transfers both: the setup, and the judgment for using it.

Who this is for: anyone joining a team that already works with AI, and whoever runs their first week. The goal is to get a new member from "AI installed" to "AI used well, the way to use it" — fast, and without a senior engineer re-explaining everything by hand.

The setup you can install in an afternoon, and the judgment you can't — 1 min 53 s.

The two things you're actually transferring

The introduction makes the point that AI is only as good as its operator: a good result needs both tool knowledge (quick to pick up) and engineering judgment (slow, no shortcut). Onboarding maps onto exactly that split:

  • The setup — tools, plugins, config, memory files. Mostly mechanical. A new member can be fully equipped in an afternoon, and most of it is already checked into the repo.
  • The judgment — when to trust output, when to reset, how the team reviews AI work. This is the part that doesn't come from an install script, and it's where the onboarding effort should actually go.

Get the setup out of the way quickly so the first week can focus on the judgment.

The day-one baseline

Start with the base tool and a working environment:

  • Install and sign in to Claude Code, then walk through Getting started — plan mode, the memory file, treating output like a teammate's pull request. This is the operating manual for the tool itself.
  • Clone the repo and confirm the project's memory file loads. If the team follows the thin-root pattern, the new member's agent now knows the test command, the module map, and the house style on the very first session — without anyone explaining it.

Install the team's tools

The team standardizes on a set of plugins, skills, and MCP servers so everyone works from the same capabilities. Don't re-teach these from scratch — point the new member at the catalogs that already document them:

  • Skills and plugins — the team's installed plugins, what each is for, and how skills get auto-invoked. The "want X → use Y" router is the fastest way to learn what's available.
  • MCP and config — the MCP servers in the setup and the shared config. Because project MCP config is checked into git, most of this comes with the clone; the new member just needs to know what's there and why.

The principle: the team's toolset is documented once, in the repo, so onboarding is reading and installing, not interviewing a senior engineer.

What they inherit for free

This is the payoff of doing the team foundation well: a new member picks up the team's accumulated know-how just by cloning the repo. Because conventions live in committed files rather than in people's heads and chat histories:

  • Project memory (CLAUDE.md / AGENTS.md / agents/) gives their agent the same architecture map, commands, and failure modes everyone else's agent has — see Memory and project rules.
  • Project skills in .claude/ encode "how we do things here," so the new member inherits the team's workflows on day one — see Reusable skills and automation.

The less that lives only in senior engineers' heads, the cheaper every future onboarding gets. If onboarding keeps surfacing the same unwritten rule, that's the signal to write it into the shared foundation.

The judgment that isn't in a repo

The setup gets a new member equipped; it doesn't make them a good operator. Spend the first week on the habits that no install script provides:

  • Verification and review. The single most important habit: never ship AI output unread. Walk them through how the team reviews and verifies AI work — Verification and review.
  • Knowing when to reset. New users tend to fight a derailed session instead of starting clean. Teach the reset reflex early — Knowing when to reset.
  • Pairing on real tasks. The fastest transfer of judgment is watching an experienced operator drive: where they scope, where they stop and check, where they overrule the model. Have the new member shadow a real task, then drive one with review.

Quick checklist

  • Claude Code installed and signed in; Getting started read
  • Repo cloned; project memory file confirmed loading on first session
  • Team plugins, skills, and MCP servers installed from the documented catalogs
  • New member knows what lives in project memory and project .claude/ — and that they inherit it for free
  • Verification and reset habits taught, not assumed
  • Shadowed one real task, then drove one under review
  • Any unwritten rule that came up during onboarding was written back into the shared foundation