前几天Anthropic 发布了一篇面向工程团队的 Claude Code 最佳实践文章重点讨论了在大型代码库中的使用方式。在今天这篇文章中我们总结了这篇博客的实践内容并顺便看看大型团队真想把 AI 编程工具放进日常开发中有哪些经验是可以直接借鉴的。开始之前先声明下“大型代码库”指的是什么。它不只是几百万行代码的 monorepo单一代码库还有维护了不知道多久的遗留系统、分布在若干个仓库的微服务架构以及上述情况混在一起的更复杂的工程环境。此外提到 AI 编程语言不一定立马想到的编程语言比如 C、C、C#、Java、PHP也在本次讨论的范围。一句话总结Claude Code 在大型代码库里的表现不只取决于模型本身还取决于代码库有没有被整理成“Claude 能看懂、能导航、能验证”的状态。Claude Code 浏览大型代码库的方式Claude Code 浏览代码库的方式很像一个软件工程师平时读代码的姿势先在文件系统中查找相关文件读些代码然后再用 grep 找到需要的信息沿着函数调用、模块引用继续往下追代码逻辑。和很多基于 RAG 的 AI 编程工具不太一样Claude Code 是在本地环境直接读取和搜索代码不用先把整个代码库做成索引也不用把代码库上传到远程服务器。RAG 类编程工具往往会先给代码库构建索引再根据问题检索相关片段。然而大型工程团队的代码变化太快了函数改名、模块删除…这些频繁的操作让索引很容易跟当前代码库对不上。Claude Code 采用 Agentic Search 来解决代码更新同步问题。简单来说就是让 Agent 直接读取当前代码库去找和任务相关的代码。这样就不用额外维护一套中心化索引也避开了向量化流程跟不上代码变化的问题。对每天都有大量代码提交的团队来说这一点很关键Claude Code 读取的是最新的代码库而不是某个已经滞后的代码快照。与此同时这种方式也有代价。Claude Code 并不是一开始就知道该从哪里理解这个项目。它需要一些初始化的上下文比如哪些目录重要、入口文件在哪里、当前模块有什么约定、测试和构建命令怎么跑。如果你让它在一个十亿行代码库里“找出所有类似模式”但不给任何方向它很快就会陷进大量无关信息里耗完了上下文窗口最后还不能解决真正的问题。因此大型代码库想要用好 Claude Code不能只是把任务丢给它还要提前把代码库整理成 Claude Code 更容易导航的样子。这也说明了下文为什么会反复提到 CLAUDE.md、Skills、LSP、MCP 这些配置。它们本质上都在解决同一个问题让 Claude Code 少走弯路快速找到正确上下文。和模型一样重要的 Harness很多团队刚开始用 Claude Code 时会先关注模型能力比如 benchmark 和测试任务表现。但在真实环境里模型之外的工程环境同样重要这就是 Claude Code 依赖的 harness。它包括 CLAUDE.md、hooks、skills、plugins、MCP servers以及 LSP 和 subagents。这些模块不能简单地堆在一起要先用 CLAUDE.md 整理好项目上下文再用 hooks、skills、plugins 和 MCP 逐层扩展。基础上下文越清楚后面的自动化、专门能力和内部系统接入才越容易发挥作用。CLAUDE.md先说清楚基础上下文CLAUDE.md 是 Claude 每次会话开始时会自动读取的上下文文件。一般来说项目根目录下的 CLAUDE.md 负责说明整个项目的基本情况像是项目结构、关键约定、容易踩坑的地方子目录里的 CLAUDE.md 则更偏向说明当前模块记录这个目录下的开发习惯、测试命令和本地规则。CLAUDE.md 的作用很基础但不能写成大杂烩。因为每次会话开始Claude 都会读取这些内容。如果你什么都往里面塞反而会占用上下文拖慢 Claude 的判断。比较适合放进 CLAUDE.md 的信息是那些不太会频繁变化、经常会用到、对大多数任务都有用的信息。这有点像给新人写项目入门文档。根文档不需要变成一本百科全书它只用告诉新人这个项目大概怎么分层哪些地方最容易踩坑遇到问题应该先看哪里。子目录文档再补充更具体的模块规则。这样 Claude 进入一个代码库后就不需要每次都从零开始摸索了。Hooks让配置自己变好hooks 很容易被认为是“拦截错误操作”的脚本用来拦截一些危险操作。其实它最有价值的地方是让 Claude Code 的配置可以持续更新。像是会话结束后用 stop hook 总结哪些经验该补进 CLAUDE.md或者是会话开始前用 start hook 自动加载团队或模块上下文都是很好的工程实践。此外对于 lint、format 这类固定检查hooks 也比普通提示词可靠因为它不是提醒 Claude“记得做”而是直接把检查变成自动执行的流程。Skills按需加载专门知识在大型代码库里Claude Code 会遇到很多不同类型的任务。像是安全审查、文档更新、发布流程、支付服务部署、数据查询等等这些任务都需要一些专门知识。但这些知识每次都塞进会话里的话上下文很快就会变得很臃肿。Skills 要解决的就是这个问题。它可以把某类任务需要的经验、流程和注意事项单独打包起来等下次遇到相关任务时再加载。这样 Claude 既能用到专门知识又不会让每次会话的上下文被无关信息占满。Skills 还可以和具体目录绑定。例如支付团队可以把部署相关的 skill 绑定到 payments 目录。这样只有研发在这个目录下工作时它才会自动生效同时在 monorepo 的其他模块进行开发就不会受到这个 skill 的影响。Plugins把有效配置分发出去在大团队里经常会出现这种情况某个小团队已经把 Claude Code 用顺了但经验只留在自己内部。新人来了得重新摸索其他团队也很难直接复用经验。这时候Plugins 就派上用场了。它可以把已经跑通的 skills、hooks、MCP 配置打包成一个可安装的插件。新人工程师装上之后不需要从零配置就能拿到一套已经验证过的上下文和能力。组织内部也可以通过统一的插件市场分发和更新这些配置。Anthropic 提到过一个例子一家大型零售公司把 Claude 接到了内部分析平台上让业务分析师可以在日常工作中直接拉取业务数据。后来他们把这个能力做成 plugin作为一套标准配置分发出去方便大范围地推广使用。LSPClaude 按符号导航LSP全称 Language Server Protocol是 IDE 用来理解代码结构的一套协议很多“跳转到定义”“查找引用”能力都靠它实现。把 LSP 接给 Claude Code 后Claude 就不只是按关键词搜代码而是能按符号理解代码关系从函数调用跳到定义追踪引用区分不同模块里的同名函数。对大型代码库来说LSP 很重要。没有它Claude 很多时候只能靠文本匹配一个普通函数名就可能搜出大量结果。得再筛一遍才能知道哪些结果和任务有关。Anthropic 提到有公司在推广 Claude Code 前会先部署 LSP就是为了让 C、C 这类代码的导航更可靠。MCP Servers连接内部工具和数据MCP servers 的作用是让 Claude 接入代码库之外的内部工具和数据源像是内部文档、工单系统、分析平台、搜索工具或业务 API。这样 Claude Code 处理业务时除了看代码还能查到相关文档、工单、数据和内部系统信息。有些团队把结构化搜索做成 MCP 工具的话Claude 就可以直接调用了。MCP 好用但不适合一上来就做得很复杂。比较稳妥的做法是先把 CLAUDE.md、hooks、skills 这些基础配置跑顺再考虑接入内部文档、工单系统、分析平台这类外部系统。Subagents把探索和编辑拆开Subagent 你可以理解为是一个单独拉出来的 Claude。它有自己的上下文窗口可以先去完成一部分任务比如阅读代码、梳理模块、分析某个子系统然后只把最终结果交回给主 agent。在大型代码库里这个能力很适合把“看代码”和“改代码”分开。先让一个只读 subagent 去摸清某个子系统把发现的信息整理成文档主 agent 再根据这份结果去做实际修改。这样主 agent 就不用把所有探索过程都装进自己的上下文把空间留给真正要改的代码和关键决策。图注Claude Code 扩展能力一览这张图表总结了 Claude Code 扩展层的几个组成部分这里要注意LSP 是通过 plugin 层访问的subagents 是一种任务委派能力而不是一个需要像其他扩展点那样配置的组件。三种成功的配置模式Anthropic 说大型代码库应该怎么配置 Claude Code取决于这个代码库本身的结构。他们在多个成功部署案例里看到了三个反复出现的模式。让代码库在变大之后依然好找Claude 能不能快速找到正确上下文决定了 Claude 在大型代码库里能不能帮上忙。上下文给太多会拖慢会话给太少它又不知道该从哪里开始理解项目。所以好的配置不是把所有信息都塞给 Claude而是让代码库本身更容易被它读懂。这里有几个比较关键的做法**CLAUDE.md 要轻量、分层。**根目录的 CLAUDE.md 只放项目结构、关键约定和容易踩坑的地方子目录里的 CLAUDE.md 再补充当前模块的本地规则。根文件不要写成百科全书信息太多反而会变成噪音。**尽量从相关子目录启动而不是总从 repo 根目录开始。**Claude 会自动向上查找并加载路径上的 CLAUDE.md所以根目录上下文不会丢。实际使用时从任务相关的子目录启动反而能减少无关文件和配置的干扰。**测试、lint、build 命令也要按目录写清楚。**如果 Claude 只改了一个服务却每次都跑全量测试很容易超时还会把无关输出塞进上下文。比较好的方式是在对应子目录里写明这个模块该跑哪些测试、lint 和构建命令。**用 ignore 规则减少噪音。**生成文件、构建产物、第三方代码不应该让 Claude 反复读。把这些排除规则放进项目配置里团队成员就能共享同一套降噪方式。**目录结构不清楚时可以准备一份代码库地图。**在根目录放一个简单的 markdown 文件列出主要目录分别负责什么。对 Claude 来说这相当于一张目录页可以先帮它判断应该从哪里看起。**大型代码库最好接入 LSP。**它能让 Claude 按符号找定义和引用先过滤掉大量无关匹配再去读真正相关的代码。对多语言代码库尤其是 C、C 这类项目推荐 LSP。总的来说这一部分的重点是不要让 Claude 在大型代码库里盲搜。先把上下文、目录边界、测试命令、忽略规则和符号导航整理好它才能更容易地找到正确位置。主动维护 CLAUDE.mdCLAUDE.md 不是写完就放着不管的。模型会持续变强过去为了约束旧模型写下的规则到了新模型上可能会变成限制。早期模型做大型重构时容易跑偏技术团队可能会在 CLAUDE.md 里写了一条规则每次重构只改一个文件。这个规则在当时是有用的但如果新模型已经能稳定处理跨文件修改它就会反过来束缚 Claude 的能力。Skills 和 hooks 也一样。很多配置一开始是为了解决某个具体问题模型能力不够或是 Claude Code 当时还不支持某个功能。一旦这些限制被新模型或新版本工具解决了原来的配置就会变得多余成为性能的负担。Anthropic 提到过 Perforce 例子有团队以前会用 hook 处理文件写入确保 Claude 修改文件前先执行p4 edit。后来 Claude Code 支持了原生 Perforce mode这个 hook 就不需要再保留了。因此Claude Code 的配置要定期 review。比较合理的节奏是每三到六个月检查一次尤其是大模型版本更新之后。如果团队发现 Claude Code 的表现进入瓶颈也可以检查一下是不是旧的 CLAUDE.md 规则、hooks 或 skills已经不再适合当前模型了。给 Claude Code 指派负责人技术配置做好了不代表团队就会自然用起来。Claude Code 要在组织里真正推广还需要有人把基础环境搭建好。比较推荐的做法是在大规模开放之前先由一个小团队甚至一个负责人把 CLAUDE.md、plugins、MCP、权限策略这些基础配置跑通。这样后面的人接触 Claude Code 时就有了一套已经能工作的环境而不是自己从零摸索、到处踩坑。这类搭建工作一般会放在开发者体验或研发效能团队下面因为它本来就和开发者工具、工程效率、新人上手有关。有些组织里也开始出现类似 Agent 负责人的角色专门维护 Claude Code 的配置、插件和使用规范。如果没有专门团队至少也要明确一个负责人。这个人要能决定 Claude Code 的设置、权限策略、插件市场和 CLAUDE.md 规范也要负责持续维护这些配置。自下而上的使用热情很重要但如果没人把有效经验沉淀下来很容易变成各个团队各配各的、各踩各的坑。最后好经验只留在小圈子里整个团队的使用也很难继续往前推进。在大型组织里还要尽早考虑治理问题哪些 skills 和 plugins 可以用AI 生成代码要走什么 review 流程怎么避免不同团队重复造同一套配置。比较稳妥的方式是先从一组经过批准的 skills、明确的代码审查流程和有限范围试点开始再逐步扩大。说到底Claude Code 的推广不只是工具问题也是一件工程组织问题。配置、权限、流程和责任人都明确了开发者才更容易把它真正用进日常工作里。如何应用这里需要提醒一点上面这些经验主要适用于比较常规的软件工程环境。就是说代码主要由工程师维护仓库使用 Git目录结构相对标准。大多数大型代码库都属于这个范围。但如果工程环境比较特殊就需要额外调整。像是游戏引擎项目有着大量二进制资产团队使用的是非 Git 版本控制或者有很多非工程师也会参与代码修改。这些场景下Claude Code 的配置方式就不能直接照搬上文了。虽然本文给了些通用模版但真正落到团队里还是要结合自己的代码库结构、工具链和组织流程来判断哪些先做哪些后做哪些根本没必要做。小结这篇文章的价值更多在于把“AI 编程工具怎么进团队”这件事讲清楚了。它没有把问题简单归结为模型能力而是回到工程现场代码库怎么组织、上下文怎么管理、规则怎么执行、经验怎么复用。对团队来说这可能比某个单点技巧更值得参考。
