原技术博客出处: How Claude Code works in large codebases: Best practices and where to start

Claude Code 如何在大型代码库中工作：我读懂了什么

最近看到 Anthropic 发了一篇文章，讲 Claude Code 在大规模代码库中的运行方式和最佳实践。作为一个还在学校里泡着、主要跟几千行规模项目打交道的计算机学生，我一开始觉得这篇文章可能跟我没什么关系。但读完发现，它讨论的一些核心问题其实挺有意思，跟你用不用 Claude Code 本身没什么关系。

---

痛点：大代码库到底难在哪

先说说问题本身。文章里提到，大型代码库可能是几百万行的单体仓库，也可能是几十年积累下来的遗留系统，或者是分散在几十个不同仓库里的微服务。

这些环境带来的挑战是什么？文章举了个例子：RAG 驱动的 AI 编程工具通常需要对整个代码库做 embedding，但 embedding 管道跟不上活跃开发的节奏。等你查询的时候，索引里的代码可能是几周前的版本——两星期前被重命名的函数、上个 Sprint 就被删掉的模块，全都不对。而且这种情况发生时，系统根本不会提示你信息已过时。

所以，传统 RAG 在大规模代码库面前天然有个结构性缺陷：embedding 管道无论如何加速，都追不上代码变更的速度。你再怎么优化，只要代码在变，索引就永远是延迟的。

但文章里提到的一个事实更让我意外：Claude Code 内部根本不用 RAG，也不建索引。它就是用传统的 grep，靠 AI 自己决定搜什么关键词、怎么搜、搜多深。这个设计选择背后的逻辑是：在大规模代码库里，维护一个实时同步的索引本身就是一项巨大的工程负担，与其花精力维护索引，不如把精力花在让 AI 更聪明地 grep。

---

模型 vs 工具链

文章有个观点我觉得很重要：“AI 编程工具的能力不只是由模型决定的，围绕模型构建的工具链（文章里叫 ‘harness’）同样关键”。

文章里打了个比方我觉得挺形象的：harness 相当于战车，模型相当于拉车的马——战车本身决定了马能跑多快。更直白地说，好马配个快散架的破车，跑不远。

---

核心配置点拆解

文章详细讲了几个配置点，我试着用自己的理解拆开说说。

CLAUDE.md

这个是最基础的。每次会话开始时会自动加载的上下文文件。根目录的讲大局，子目录的讲局部规范，层层叠加。但关键是得精简，只放那些在会话里始终相关的东西。

Hooks

大多数人以为 hooks 只是用来阻止 Claude 做错事的护栏，但文章说它的真正价值在于持续改进。比如会话结束后跑一个反思钩子，趁热把这次学到的新规范推回 CLAUDE.md，配置自己完善自己。

Skills

这个是按需加载的专业能力模块。安全审查技能只在评估漏洞时触发，文档更新技能只在代码变动时触发。用"渐进式披露"的方式避免上下文塞满各种不相关的东西。

LSP（语言服务器协议）集成

这个我觉得是文章里最实用的东西。没 LSP 的时候，Claude 纯靠 grep 做字符串匹配，遇到同名函数（比如 Java 里不同类都有 getUser）会直接懵。LSP 能按符号精准跳转定义和找引用，让搜索在 Claude 读任何文件之前就完成过滤。文章里提到有一家 C/C++ 重型企业，在部署 Claude Code 之前先在组织范围内铺开了 LSP，就是专门为了解决大规模代码库里的符号导航问题。

Plugins

大代码库有个典型问题是"好配置不出圈"：某个团队摸索出的最佳实践，另一队完全不知道，每个团队都在重复造轮子。Plugins 把技能、钩子、MCP 配置打成一个可安装包，新来的工程师第一天装上插件，就能直接拥有跟老手一样的环境和上下文。

Subagents

这是一个让我觉得"还能这么玩"的设计。子代理是一个独立的 Claude 实例，拥有自己的上下文窗口，接受一个任务，干完活，只返回最终结果。有团队的做法是用只读子代理先去探索一个子系统的结构，把发现写入文件，然后主代理拿着完整信息去改代码。这种分工的好处是探索和编辑的上下文不互相污染。

---

最佳实践里我觉得最实用的几个

文章提到的几个配置模式，我觉得不只在 Claude Code 里有用，放在其他工具的配置上也有参考价值：

• 分层配置：CLAUDE.md 是"累加加载"的——Claude 从一个子目录启动，往上走到根目录，沿途加载所有 CLAUDE.md 文件。根目录文件只放最重要的大局信息和关键避坑点，子目录文件放各自的局部规范。每个 CLAUDE.md 最好控制在 150 行以内，超过这个数量，Claude 每次都会加载一堆用不上的信息。
• 在子目录启动：这一点反直觉，尤其是在单体仓库里，我们习惯在根目录跑一切。但文章指出，把 Claude 限定在任务相关的子目录中效果反而更好，因为它会自动向上遍历找到所有相关的上下文。
• 测试和 lint 命令按子目录限定范围：如果你改了某个服务的代码，却让它跑整个单体仓库的全部测试套件，结果就是超时 + 大量无关输出塞满上下文。在子目录的 CLAUDE.md 里指定只适用于该子目录的测试命令，是更高效的做法。
• 用 .ignore 文件排除噪音：生成的文件、构建产物、第三方代码，都不该出现在 Claude 能看到的内容里。把这些规则放进版本控制的 .claude/settings.json，整个团队都能受益于同样的噪音过滤。
• 代码地图：如果目录结构太乱，或者文件分散得太开，文章推荐在根目录放一个轻量级的 Markdown 文件，列出每个顶级文件夹是干什么的。Claude 先扫这个地图再深入读文件。

---

配置需要持续维护：它也会过时

文章指出一个容易被忽视的问题：CLAUDE.md 会随着模型进化而过时。你今天写的一条"把所有重构拆成单文件改动"的规则，可能对当前模型有用，但对三个月后的新版模型来说可能反而是束缚——模型明明可以一次做跨文件协调修改，却被旧配置限制了。

文章建议每三到六个月做一次配置审查，特别是当模型大版本更新后感觉性能停滞的时候，就该看看是不是某些规则已经过时了。这其实是一种工程思维：把配置本身当作需要持续维护的代码，而不是一次性写死的设置。

---

最后让我意外的：组织因素比技术更关键

文章最后一部分讨论的其实是"谁该来管这个事"。

“技术配置本身并不驱动采用率”。听起来像常识，但现实里太多团队直接跳过这一步。成功的推广都有一个共通点：在广泛开放之前，先有一支专门的小团队（甚至只是一个人）把工具链搭好，让每个开发者第一次接触 Claude 时，它就已经融入了他们的日常工作流。

有个案例让我印象深刻：一家公司里几个工程师在推广之前就搭好了一套插件和 MCP 套件；另一家公司专门有个团队负责管理 AI 编程工具的基础设施，一切就绪后才开始推广。两家的结果一样：开发者的第一次体验是"这工具帮我把事干成了"，而不是"这个怎么又报错了"。

文章提到一个正在兴起的新角色叫 “Agent Manager”，是 PM 和工程师的混合职能，负责管理 Claude Code 生态的方方面面：配置、权限、插件市场、CLAUDE.md 规范等。

没有这样的角色会怎样？文章说得一针见血：“自下而上的推广能产生热情，但如果没有一个中心角色来汇总统一把那些有效做法，知识会散落在各团队之间，推广会停滞”。

对于大型组织，尤其是受监管的行业，治理问题会提前浮出水面：谁有权决定哪些技能和插件可用？如何防止几千个工程师各造各的轮子？AI 生成代码怎么走和人类代码一样的审查流程？

文章的建议是：一开始就限定范围，选一批批准的技能，定好审查流程，限制初期访问范围，随着信心建立再逐渐扩大。最顺利的落地案例往往在早期就搭建了跨职能工作组——工程、信息安全、治理三方代表一起定需求和路线图。

---

启示

这篇文章让我意识到一件事：在学校里，我们习惯了一个人面对一个小项目，什么都能自己搞定。但在真实的大型组织里，问题从来不是纯粹的技术问题。

一个工具的落地，涉及配置管理（CLAUDE.md 分层设计）、团队协作（跨职能工作组）、持续维护（每季度做配置审查），甚至还有专门的"Agent Manager"这种我以前从没想过的角色。

技术能力只是基础。文章给我最大的启发是：一个工具的成败，除了技术因素之外，更大的变量在于——谁来设计配置、谁来推广实践、谁来持续维护。这些工作看起来不像"写代码"那么核心，但它们往往是决定一个工具能不能被团队真正用好的关键。