16 Moves That Make Claude Code Work in a Large Codebase

Most teams that get bad results from Claude Code in a big repo blame the model. It is almost never the model.

Claude Code has no index of your codebase. It opens the file system and reads, the way a new engineer would on day one. A new engineer with no map and no README does badly too. The fix is not a better model, it is a codebase that explains itself.

In May 2026 Anthropic published the patterns they see across their largest deployments: monorepos in the millions of lines, legacy systems built over decades, dozens of microservices in separate repositories, and languages people do not associate with AI coding tools like C, C++, C# and Java. This PDF takes that material and reorders it into a build order you can work through top to bottom, with the reasoning kept in.

What's inside

• Why agentic search beats an embedded index at scale, and the one tradeoff it comes with
• The seven parts of the setup around the model, in the order they should be built
• Keeping CLAUDE.md files lean and layered, and the expertise that should never go in one
• Why you start Claude in a subdirectory rather than the repo root, even in a monorepo
• Scoping test and lint commands per directory, and where that breaks down in compiled monorepos
• The permissions.deny rules worth committing so the whole team gets the same quiet repo
• Writing a codebase map when the folder structure does not explain itself
• Running a language server so Claude resolves symbols instead of string-matching
• Hooks as a self-improving layer, not just a guard rail
• Skills, path scoping, and progressive disclosure
• Packaging a working setup as a plugin so it stops being tribal knowledge
• Why MCP servers belong near the end of the list, not the start
• Splitting exploration from editing with read-only subagents
• Reviewing your configuration every three to six months as models change
• Ownership, the DRI, and the governance questions that arrive in week one
• A 19-step start-here list, in order

Who it's for

Engineers and engineering leads introducing Claude Code to a codebase that is too big to explain in one prompt. It assumes you have used Claude Code a little and want the setup right before you roll it out to other people.

Get the PDF

Drop your name and email above and it is yours. Clean, printable, nine pages.

Source: How Claude Code works in large codebases, Anthropic, 14 May 2026.