Claude Code in a Monorepo: A Step-by-Step Walkthrough

Most tutorials show Claude Code fixing a typo in a toy repo and call it a day. That is not the problem real teams have. The real problem is a 600-package monorepo where a single change touches three services, two shared libraries, and a generated client, and where one careless edit breaks CI for forty engineers. This walkthrough takes that harder case and goes step by step through a task an engineer can actually follow today: adding a new field to an API and threading it cleanly through the stack.

I will keep it concrete. Real commands, real decision points, real review discipline. The goal is not to admire the tool but to leave you with a repeatable procedure you can run on Monday morning against your own large repository.

Step 1: Set up the ground truth

Before you type a single instruction, give the agent a map. Create or update a CLAUDE.md at the repo root with the things a new hire would need on day one: how to build (pnpm -w build), how to run tests for one package (pnpm --filter @acme/orders test), the directory layout, and the non-obvious rules ("never edit files under gen/, they are generated; regenerate with make proto"). This file is loaded into context at session start, so every instruction below inherits it.

This step pays for itself within the first task. Without it the agent will burn turns rediscovering your build commands and may edit generated files it should have left alone. With it, the agent starts from your team's hard-won conventions instead of guessing.

Step 2: Scope the task tightly

Vague requests produce vague edits. Instead of "add a discount field to orders," give the agent the boundaries of the change up front: which package owns the schema, which service exposes the API, and what you consider done. A strong opening instruction reads like a small spec. "Add an optional discountCents integer to the Order schema in packages/orders-schema, surface it in the GraphQL resolver in services/orders-api, and update the generated TypeScript client consumers. Do not touch the mobile app."

flowchart TD
  A["Write CLAUDE.md ground truth"] --> B["Scope task as a mini-spec"]
  B --> C["Claude maps blast radius via search"]
  C --> D["Propose plan & file list"]
  D --> E{"Plan looks right?"}
  E -->|No| B
  E -->|Yes| F["Apply edits package by package"]
  F --> G["Run scoped tests & typecheck"]
  G --> H{"Green?"}
  H -->|No| F
  H -->|Yes| I["Review diff & commit"]

Notice that scoping is also a cost control. In a monorepo, the difference between "the orders package" and "the codebase" is thousands of tokens of unnecessary file reads. Naming the blast radius keeps the agent's context tight and its edits surgical.

Step 3: Let it map the blast radius before editing

Ask for a plan before any code changes: "List the files you intend to change and why, then stop." Claude Code will run searches across the monorepo to find every consumer of the Order type, including ones you forgot, and come back with an annotated file list. This is the moment to catch scope creep. If it proposes touching the analytics pipeline you did not know depended on the schema, you decide whether that is in scope now or a follow-up.

This plan-first checkpoint is the single most valuable habit in large-repo work. The agent's search is genuinely good at finding the long tail of call sites, and reviewing the plan costs you thirty seconds while reviewing a wrong 40-file diff costs you twenty minutes. Treat the plan as a contract you approve before execution.

Step 4: Apply edits in reviewable slices

Tell the agent to work one package at a time and to run that package's typecheck and tests after each slice: "Start with orders-schema, run its build and tests, show me the result, then move on." This turns one giant risky diff into a sequence of small verified ones. If the schema change is wrong, you find out before it has rippled into the API and the client.

Between slices, actually read the diff. Claude Code is strong but not infallible, and in a monorepo the failure mode that hurts is a plausible-looking edit that violates a convention the agent could not have known. Watch especially for changes to shared libraries, where one altered signature fans out across every consumer. A two-line edit to a util everyone imports is higher risk than a fifty-line edit isolated to one service.

Step 5: Close the loop with the build system

The final step is to let the agent prove the change rather than assert it. Have it run the full affected-package test set and the workspace typecheck, and paste failures back to it so it can iterate. A good closing instruction is "run pnpm -w typecheck and the tests for every package you touched; fix anything red." The agent reads the failing output, locates the cause, and patches it, looping until green.

This is where the agentic model earns its keep. The compile-test-fix cycle is exactly the tedious loop you do not want to babysit, and it is one Claude Code runs well because it can read the error, find the offending line, and edit, all without a context switch for you. Your job shifts from typing the fix to approving the final, verified diff and writing the commit message with intent the agent could not infer.

A realistic gotcha to plan for

Generated code is the classic monorepo trap. If your repo has protobuf or GraphQL codegen, the agent may try to hand-edit the generated output to make a test pass, which works locally and then gets clobbered on the next make gen. Pre-empt this in CLAUDE.md and re-state it in the task: edits go in the source schema, never the generated artifact. The same caution applies to lockfiles, snapshot tests, and vendored dependencies.

Frequently asked questions

How do I stop Claude Code from changing too many files?

Scope the request as a mini-spec that names the owning packages and explicitly excludes areas like the mobile app, then ask for a plan and file list before any edits. Reviewing and trimming that plan is far cheaper than reverting an overgrown diff.

Should I run tests myself or let the agent run them?

Let the agent run scoped tests and typechecks after each package-sized slice so it can iterate on failures automatically. You still read the final diff and decide what ships; the agent handles the tedious compile-test-fix loop in between.

What goes in CLAUDE.md for a monorepo?

Build and per-package test commands, the directory layout, codegen rules, and explicit do-not-touch zones like generated folders and lockfiles. It loads at session start, so it shapes every task without you repeating yourself.

How do I handle a change that spans many packages safely?

Have the agent map every consumer first, then apply edits one package at a time with tests after each, starting from the package that owns the schema. Small verified slices beat one large diff you cannot fully review.

Agentic AI for the phone, step by step

The same disciplined loop, scope tightly, verify each step, and let the agent close the loop, is how CallSphere builds voice and chat agents that answer every call, act on tools mid-conversation, and book work 24/7. See the walkthrough 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.