Onboarding Claude Code: A Step-by-Step Setup Guide

Imagine a strong new developer starts Monday. You wouldn't hand them root and say "fix the billing bug." You'd set up their machine, point them at the repo, walk them through how you build and test, and give them a small, well-scoped first ticket. Claude Code earns the same treatment. Skip the setup and you get an agent that guesses at your conventions, runs the wrong test command, and edits files it shouldn't. Do the setup well and the first session feels like a competent hire who already read the onboarding doc.

This is the hands-on walkthrough. Follow it in order on a real repository and you'll have a properly onboarded Claude Code by the end — with the artifacts to prove it.

Step 1: Install and authenticate

Start in a clean terminal at the root of a git repository you actually work in — onboarding against a toy project teaches you nothing transferable. Install the Claude Code CLI per Anthropic's instructions, then launch it inside the repo. On first run you'll authenticate and pick a default model; for day-to-day engineering, Sonnet 4.6 is a sensible balance of speed and capability, with Opus 4.8 reserved for the hardest reasoning-heavy tasks and Haiku 4.5 for cheap, high-volume steps.

Before doing anything ambitious, confirm the agent can see the project. Ask it to summarize the repository structure and name the main entry points. If that summary is accurate, your working directory and file access are correct. If it's vague or wrong, stop and fix the environment first — every later step depends on the agent reading the right tree.

Step 2: Scope permissions deliberately

A new developer gets least-privilege access, and so should the agent. Decide up front which actions run automatically and which require your confirmation. Reading files and searching the repo are safe to auto-allow. Shell commands, file writes, and anything touching the network deserve a prompt — at least until you trust the workflow.

The practical move is to allowlist the specific commands you run constantly (your test runner, linter, type checker, build) so the agent isn't blocked mid-task, while leaving destructive or unfamiliar commands gated behind a confirmation. Think of it as the difference between giving a new hire commit access to a feature branch versus force-push rights on main. You can always widen permissions once the agent has earned trust on a few tasks.

flowchart TD
  A["Install & auth in repo"] --> B["Verify agent reads the tree"]
  B --> C["Scope permissions: allow safe, gate risky"]
  C --> D["Write CLAUDE.md: build, test, conventions"]
  D --> E["Wire one MCP server it needs"]
  E --> F["Give a small first ticket"]
  F --> G{"Tests pass & diff clean?"}
  G -->|No| D
  G -->|Yes| H["Widen scope, real work"]

Step 3: Write the CLAUDE.md onboarding doc

This is the highest-value step and the one most teams rush. CLAUDE.md is a project memory file that loads into the agent's durable context on every turn, carrying your conventions, commands, and constraints so the agent doesn't have to rediscover them. Treat it exactly like the README you'd write for a human joining the team — except every line must be true and operational, because the agent will follow it literally.

Cover the essentials concretely. State the exact commands to install dependencies, run the test suite, lint, and type-check. Name the directories that matter and what lives in each. Spell out conventions the agent can't infer: "we use named exports," "never edit files in generated/," "all database access goes through the repository layer." Add the landmines: "the staging deploy is manual," "do not run the full integration suite locally — it hits real services." Keep it tight; a focused page that's all signal beats five pages of obvious advice the agent already knows.

After writing it, test it. Start a fresh session and ask the agent how it would run the tests and where a particular feature lives. The answers should match your file verbatim. If the agent improvises, your memory file is too vague — tighten the wording until the behavior is deterministic.

Step 4: Wire the one tool it can't work without

Most repos need the agent to reach exactly one external system early — usually the database, the issue tracker, or an internal API. Wire that one MCP server now rather than later, because a first task that needs it will otherwise stall. Configure the server with read-only credentials to start; you can grant writes once you've watched it behave. Confirm the connection by asking the agent to list available tools and run a single safe query, like counting rows in a table or fetching one open issue. A clean round-trip here means the integration layer is sound before you depend on it.

Step 5: Give a small, well-scoped first task

Resist the urge to open with something heroic. The first real task should be small enough to fully verify and meaningful enough to exercise the setup — a bug fix with a reproducible failing test is ideal. Describe the task the way you'd brief a junior: the symptom, where you think it lives, the command that reproduces it, and what "done" means. Then let the agent work, but watch the turns. You're not just getting a fix; you're auditing whether your CLAUDE.md, permissions, and tools hold up under a real workload.

When the diff comes back, review it like a pull request. Are the right files touched? Does it follow your conventions? Did the agent run the tests you specified and report results honestly? Every gap you find is a line to add to CLAUDE.md — the loop on the diagram where a failed check sends you back to refine memory. After two or three tickets, the file stabilizes and the agent stops making the same class of mistake.

Step 6: Widen scope and codify the workflow

Once the basics are solid, graduate the agent to bigger work: multi-file features, refactors, investigations across the codebase. This is also when subagents and skills start to pay off — a reusable skill that encodes your "add a new API endpoint" checklist turns a fuzzy request into a repeatable procedure. The throughline of good onboarding is that each session leaves behind a durable artifact: a sharper memory file, a new allowlisted command, a documented skill. That's what separates a one-off chat from a teammate who gets better every week.

Frequently asked questions

How long does it take to onboard Claude Code properly?

The mechanical setup — install, permissions, a first CLAUDE.md, one MCP server — takes under an hour. The valuable part is the next few tasks, where you refine the memory file based on real mistakes. Plan for two or three small tickets before the agent feels reliably dialed in.

What should go in CLAUDE.md versus left out?

Put in the operational specifics the agent can't infer: exact build/test/lint commands, directory roles, hard conventions, and landmines to avoid. Leave out generic programming advice and anything the model already knows. The bar is: would a new human hire need this written down? If yes, include it; if it's obvious, cut it.

Should I give Claude Code write access to my database on day one?

No. Start the MCP database server with read-only credentials and confirm it behaves on safe queries before granting writes. This mirrors least-privilege onboarding for a human and keeps a misread instruction from becoming a destructive mutation early, when you trust the agent least.

What makes a good first task for Claude Code?

A small bug with a reproducible failing test. It's fully verifiable, it exercises your build and test commands, and the pass/fail signal tells you immediately whether the setup holds. Avoid sprawling features as a first task — they make it hard to tell whether a problem is the agent or your onboarding.

Bringing agentic AI to your phone lines

The same disciplined onboarding — scoped permissions, a crisp instruction layer, one tool wired at a time — is how CallSphere stands up voice and chat agents that answer every call, use tools mid-conversation, and book work 24/7. See it live at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.