How Claude Code works in large codebases: Best practices and where to startClaude 代码在大型代码库中的运作方式最佳实践与入门指南https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-startThe most successful Claude Code deployments share a set of recognizable patterns across configurations, tooling, and org structure. This article is part ofClaude Code at scale, a new series covering best practices for engineering organizations building with Claude Code at enterprise scale.最成功的Claude Code部署案例在配置、工具和组织结构方面都遵循一系列可识别的模式。本文是《规模化Claude Code》系列文章的一部分该系列主要介绍企业级规模下使用Claude Code构建系统的工程团队最佳实践。Claude Code is running in production across multi-million-line monorepos, decades-old legacy systems, distributed architectures spanning dozens of repositories, and at organizations with thousands of developers. These environments present challenges that smaller, simpler codebases don’t, whether that’s build commands that differ across every subdirectory or legacy code spread across folders with no shared root.This article covers the patterns weve observed that have led to successful adoption of Claude Code at scale. We use “large codebase” to refer to a wide range of deployments: monorepos with millions of lines, legacy systems built over decades, dozens of microservices across separate repositories, or any combination of the above. That also includes codebases running on languages that teams dont always associate with AI coding tools, such as C, C, C#, Java, PHP. (Claude Code performs better than most teams expect it to in those cases, particularly as of recent model releases.) While every large codebase deployment is shaped by its specific version control, team structure, and accumulated conventions, the patterns here generalize across them and are a good starting point for teams considering adopting Claude Code.Claude Code已在数百万行规模的单体代码库、拥有数十年历史的遗留系统、跨越数十个代码仓库的分布式架构以及拥有数千名开发者的组织中投入生产应用。这些环境带来了小型简单代码库所不具备的挑战——无论是每个子目录各不相同的构建命令还是分散在多个无共同根目录文件夹中的遗留代码。本文总结了我们在规模化成功落地Claude Code过程中观察到的关键模式。我们使用大型代码库来指代多种部署场景包含数百万行的单体仓库、历经数十年构建的遗留系统、分散在独立仓库的数十个微服务或是上述情况的任意组合。这也包括那些开发团队通常不认为适合AI编程工具的语言环境例如C、C、C#、Java、PHP等在这些场景下特别是随着近期模型版本的更新Claude Code的表现往往超出大多数团队的预期。虽然每个大型代码库的部署都受其特定的版本控制、团队结构和历史惯例影响但本文总结的模式具有普适性可为考虑采用Claude Code的团队提供良好起点。How Claude Code navigates large codebasesClaude Code navigates a codebase the way a software engineer would: it traverses the file system, reads files, uses grep to find exactly what it needs, and follows references across the codebase. It operates locally on the developer’s machine and doesn’t require a codebase index to be built, maintained, or uploaded to a server.The AI coding tools relied on RAG-based retrieval by embedding the entire codebase and retrieving relevant chunks at query time. At large scale, those systems can fail because embedding pipelines can’t keep up with active engineering teams. By the time a developer queries the index, it reflects the codebase as it existed days, weeks, or even hours ago. Retrieval then returns a function the team renamed two weeks ago, or references a module that was deleted in the last sprint, with no indication that either is out of date.Agentic search avoids those failure modes. Theres no embedding pipeline or centralized index to maintain as thousands of engineers commit new code. Each developers instance works from the live codebase.But the approach has a tradeoff: it works best when Claude has enough starting context to know where to look. This means the quality of Claudes navigation is shaped by how well the codebase is set up, layering context with CLAUDE.md files and skills. If you ask it to find all instances of a vague pattern across a billion-line codebase, you’ll hit context-window limits before the work begins. Teams that invest in codebase setup see better results.Claude Code 像软件工程师一样浏览代码库它遍历文件系统、读取文件、使用 grep 精准定位所需内容并跟踪代码库中的引用关系。该工具直接在开发者本地机器运行无需构建、维护或上传代码库索引。传统AI编程工具依赖基于RAG的检索机制通过嵌入整个代码库并在查询时检索相关片段。但在大规模场景下这类系统可能失效——因为嵌入管道无法跟上工程团队的活跃更新。当开发者查询索引时获取的可能是几天前、几周前甚至几小时前的代码状态。检索结果可能返回已被重命名两周的函数或引用上个冲刺阶段已删除的模块且没有任何过期提示。智能代理搜索规避了这些问题。它不需要维护嵌入管道或集中式索引即使面对数千名工程师持续提交新代码。每个开发者的实例都直接基于实时代码库工作。但这种方法存在权衡当Claude拥有足够的初始上下文知道从何处着手时其效果最佳。这意味着代码导航质量取决于代码库的基础建设包括CLAUDE.md文件与技能层的上下文构建。若要求在十亿行代码库中模糊搜索某个模式在开始工作前就会触及上下文窗口限制。重视代码库基础建设的团队能获得更优效果。The harness matters as much as the modelOne of the most common misconceptions about Claude Code is that its capabilities are solely defined by the model used. Teams focus on a model’s benchmarks and how it performs on test tasks. In practice, the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone.The harness is built from five extension points—CLAUDE.md files, hooks, skills, plugins, and MCP servers—each serving a different function. The order in which teams build them matters, as each layer builds on what came before. Two additional capabilities, LSP integrations and subagents, round out the setup. Below, we explain what each of these components and capabilities do:CLAUDE.mdfiles come first. These are context files that Claude reads automatically at the start of every session: root file for the big picture, subdirectory files for local conventions. They give Claude the codebase knowledge it needs to do anything well. Because they load in every session regardless of the task, keeping them focused on what applies broadly will prevent them from becoming a drag on performance.Hooksmake the setup self-improving. Most teams think of hooks as scripts that prevent Claude from doing something wrong, but their more valuable use is continuous improvement. A stop hook can reflect on what happened during a session and propose CLAUDE.md updates while the context is fresh. A start hook can load team-specific context dynamically so every developer gets the right setup for their module without manual configuration. For automated checks like linting and formatting, hooks enforce the rules deterministically and produce more consistent results than relying on Claude to remember an instruction.Skillskeep the right expertise available on-demand without bloating every session.In a large codebase with dozens of task types, not all expertise needs to be present in every session. Skills solve this through progressive disclosure, offloading specialized workflows and domain knowledge that would otherwise compete for context space and loading them only when the task calls for it. For example, a security review skill loads when Claude is assessing code for vulnerabilities, while a document processing skill loads when a code change is made and documentation needs to be updated.Skills can also be scoped to specific paths so they only activate in the relevant part of the codebase. A team that owns a payments service can bind their deployment skill to that directory, so it never auto-loads when someone is working elsewhere in the monorepo.Pluginsdistribute what works.One challenge with large codebases is thatgoodsetups can stay tribal. A plugin bundles skills, hooks, and MCP configurations into a single installable package, so when a new engineer installs that plugin on day one, they will immediately have the same context and capabilities as those who have been using Claude already. Plugin updates can be distributed across the organization through managed marketplaces.For example, a large retail organization we work with built a skill connecting Claude to their internal analytics platform so that business analysts could pull performance data without leaving their workflow. They distributed it as a plugin before the broad rollout to the business.Language server protocol (LSP) integrations give Claude the same navigation a developer has in their IDE.Most large-codebase IDEs already have an LSP running, powering go to definition and find all references. Surfacing this to Claude gives it symbol-level precision: it can follow a function call to its definition, trace references across files, and distinguish between identically named functions in different languages. Without it, Claude pattern-matches on text and can land on the wrong symbol. One enterprise software company we worked with deployed LSP integrations org-wide before their Claude Code rollout, specifically to make C and C navigation reliable at scale. For multi-language codebases, this is one of the highest-value investments.语言服务器协议LSP集成使Claude具备与开发者在IDE中相同的代码导航能力。大多数大型代码库IDE已运行着LSP支持转到定义和查找所有引用功能。将该能力赋予Claude可实现符号级精确度它能追踪函数调用至定义处跨文件追溯引用并区分不同语言中同名函数。若无此功能Claude仅能进行文本模式匹配可能定位到错误符号。与我们合作的一家企业在全面部署Claude Code前就全组织推行了LSP集成专门为确保大规模C/C代码导航的可靠性。对于多语言代码库而言这是最具价值的投资之一。MCP servers extend everything.MCP servers are how Claude connects to internal tools, data sources, and APIs that it cant otherwise reach. The most sophisticated teams built MCP servers exposing structured search as a tool Claude can call directly. Others connect Claude to internal documentation, ticketing systems, or analytics platforms.MCP服务器扩展了一切功能。MCP服务器是Claude连接其无法直接访问的内部工具、数据源和API的方式。最成熟的团队构建了MCP服务器将结构化搜索作为Claude可以直接调用的工具公开。其他团队则将Claude连接到内部文档、工单系统或分析平台。Subagentssplit exploration from editing.A subagent is an isolated Claude instance with its own context window that takes a task, does the work, and returns only the final result to the parent. Once the harness is in place, some teams spin up a read-only subagent to map a subsystem and write findings to a file, then have the main agent edit with the full picture.子代理将探索与编辑分离。子代理是一个独立的Claude实例拥有自己的上下文窗口它接收任务、完成工作并仅将最终结果返回给父代理。一旦框架就位某些团队会启动一个只读子代理来映射子系统并将发现写入文件然后让主代理在掌握全局的情况下进行编辑。The table below summarizes what each component does, when it loads, and the most common mistakes we see with each:Three configuration patterns from successful deploymentsHow you configure Claude Code for a large codebase depends heavily on how that codebase is structured. Still, three patterns appeared consistently across the deployments we observed.Making the codebase navigable at scaleClaude’s ability to help in a large codebase is bounded by its ability to find the right context. Too much context loaded into every session degrades performance, while too little context leaves Claude to navigate blind. The most effective deployments invest upfront in making the codebase legible to Claude. A few patterns appear consistently:Keeping CLAUDE.md files lean and layered.Claude loads them additively as it moves through the codebase: root file for the big picture, subdirectory files for local conventions. The root file should be pointers and critical gotchas only; everything else drifts into noise.Initializing in subdirectories, not at the repo root.Claude works best when its scoped to the part of the codebase thats actually relevant to the task. In monorepos, this can feel counterintuitive because tooling often assumes root access, but Claude automatically walks up the directory tree and loads every CLAUDE.md file it finds along the way, so root-level context is never lost.Scoping test and lint commands per subdirectory.Running the full suite when Claude changed one service causes timeouts and wastes context on irrelevant output. CLAUDE.md files at the subdirectory level should specify the commands that apply to that part of the codebase. This works well for service-oriented codebases where each directory has its own test and build commands. In compiled-language monorepos with deep cross-directory dependencies, per-subdirectory scoping is harder to achieve and may require project-specific build configurations.Using.ignorefiles to exclude generated files, build artifacts, and third-party code.Committingpermissions.denyrules in.claude/settings.jsonmeans the exclusions are version-controlled, so every developer on the team gets the same noise reduction without configuring it themselves. In some codebases, generated files are themselves the subject of development work. Developers who work on code generators can override project-level exclusions in their local settings without affecting the rest of the team.Building codebase maps when the directory structure doesn’t do the work.For organizations where code isn’t consolidated in a conventional directory structure, a lightweight markdown file at the repo root listing each top-level folder with a one-line description of what lives there gives Claude a table of contents it can scan before opening files. For codebases with hundreds of top-level folders, this works best as a layered approach: the root file describes only the highest-level structure, and subdirectory CLAUDE.md files provide the next level of detail, loading on demand as Claude moves through the tree. For simpler cases, -mentioning the specific files or directories Claude should reference can do the same job.Running LSP servers so Claude searches by symbol, not by string.Grep for a common function name in a large codebase returns thousands of matches and Claude burns context opening files to figure out which matters. LSP returns only the references that point to the same symbol, so the filtering happens before Claude reads anything.Setting this up requires installing a code intelligence plugin for your language and the corresponding language server binary; the Claude Code documentation covers the available plugins and troubleshooting.One caveat: there are edge cases where even the hierarchical CLAUDE.md approach breaks down, for example codebases with hundreds of thousands of folders and millions of files, or legacy systems on non-git version control. We will address their challenges in future installments of this series.Actively maintaining CLAUDE.md files as model intelligence evolvesAs models evolve, instructions written for your current model can work against a future one. CLAUDE.md files that guided Claude through patterns it used to struggle with may either become unnecessary or actively constraining when the next model ships. For example, a CLAUDE.md rule that tells Claude to break every refactor into single-file changes may have helped an earlier model stay on track but would prevent a newer one from making coordinated cross-file edits it handles well.Skills and hooks built to compensate for specific model limitations, whether in the model’s reasoning or in Claude Code’s own tooling, become overhead once those limitations no longer exist. A hook that intercepted file writes to enforce p4 edit in a Perforce codebase, for example, became redundant once Claude Code added native Perforce mode.Teams should expect to do a meaningful configuration review every three to six months, but its also worth doing one whenever performance feels like its plateaued after major model releases.Assigning ownership for Claude Code management and adoptionTechnical configuration alone doesnt drive adoption. The organizations that got it right invested in the organizational layer, too.The rollouts that spread fastest had a dedicated infrastructure investment before broad access. A small team, sometimes even just one person, wired up the tooling so Claude already fit developer workflows when they first touched it. At one company, a couple of engineers built a suite of plugins and MCPs that were available on day one. At another, an entire team focused on managing AI coding tools had the infrastructure in place before the rollout began. In both cases, developers first experience was productive rather than frustrating, and adoption spread from there.The teams doing this work today tend to sit under developer experience or developer productivity, which is typically the function responsible for onboarding new engineers and building developer tooling. An emerging role in several organizations is an agent manager: a hybrid PM/engineer function dedicated to managing the Claude Code ecosystem. For organizations without a dedicated team, the minimum viable version is a DRI: one person with ownership over the Claude Code configuration, the authority to make calls on settings, permissions policy, the plugin marketplace, and CLAUDE.md conventions, and the responsibility to keep them current.Bottoms-up adoption generates enthusiasm but can fragment without someone to centralize what works. You need to have an individual or a team assemble and evangelize the right Claude Code conventions (such as a standardized CLAUDE.md hierarchy or a curated set of skills and plugins). Without that work, knowledge will stay tribal and adoption will plateau.In large organizations, especially those in regulated industries, governance questions come up early, such as: who controls which skills and plugins are available, how do you prevent thousands of engineers from independently rebuilding the same thing, how do you make sure AI-generated code goes through the same review process as human-generated code? To address these early on, we suggest starting with a defined set of approved skills, required code review processes, and limited initial access, and expand as confidence builds.We’ve observed the smoothest deployments at organizations that establish cross-functional working groups early by bringing together engineering, information security, and governance representatives to define requirements together and build a rollout roadmap.Applying these patterns to your organizationClaude Code is designed around conventional software engineering environments where engineers are the primary codebase contributors, the repo uses Git, and code follows standard directory structures. Most large codebases fit this mold, but non-traditional setups such as game engines with large binary assets, environments with unconventional version control, or non-engineers contributing to the codebase require additional configuration work. Our guidance assumes a conventional setup and the patterns we’ve described have worked across many of our customers. Any remaining complexity requires judgment specific to your codebase, tooling, and organization. Thats where Anthropics Applied AI team works directly with engineering teams to translate these patterns into your organization’s specific requirements.--https://claude.com/product/claude-code/enterprise