公众号名称：超级猛

作者名称：超级猛

发布时间：2026-05-24 17:42

WENOTE ARTICLE

Claude Code在大型项目中的最佳实践指南

“

Claude Code 不靠 RAG 索引导航大代码库，而是像工程师一样读文件、grep 搜索、循引用追踪。真正决定效果的也不是模型本身，是围绕模型构建的七层扩展架构：CLAUDE.md → Hooks → Skills → Plugins → LSP → MCP → Subagents。每一层都有明确的加载时机和适用场景，按顺序搭建别跳步。核心结论：harness 比模型更重要。

Anthropic 最近发了一篇 Claude Code 企业实战的干货文章，讲的是 Claude Code 在大型代码库里到底怎么工作、哪些配置值得投入、以及真正的落地模式长什么样。我读完觉得这是目前为止最扎实的一篇官方指南，没有之一。

之前写了很多篇 Claude Code 的实战笔记，但都是从个人使用者的角度出发。这篇不一样——它是 Anthropic 应用 AI 团队在帮一堆大企业落地 Claude Code 之后，总结出来的可复制模式。

下面是我的拆解，会保留原文的核心框架，但加入我自己的一些判断和实践体验。

Claude Code 是怎么”看懂”大代码库的

很多人以为 Claude Code 背后有一个巨大的 RAG 索引——先把整个代码库向量化，然后每次问答时从索引里检索相关代码。

实际情况完全不是这样。

Claude Code 的工作方式跟一个人类工程师差不多：读文件、grep 搜索、顺着引用关系一层层翻。它不需要一个预先建好、需要持续维护、还要上传到服务端的中心化索引。

为什么不做 RAG？原文的解释很到位：在几千个工程师每天提交代码的大型代码库里，嵌入流水线根本跟不上代码变更的速度。 等到开发者真正去查询索引的时候，它已经是几天甚至几小时前的快照了。检索结果可能返回一个已经改名的函数、一个已经被删掉的模块，而且没有任何标记告诉你这是过时信息。

Agent 搜索不依赖索引，所以不存在这个”索引过时”的问题。但代价是：Claude 需要足够的起始上下文才能知道去哪找。 在一个十亿行代码库里，如果只给一个模糊的关键词让它搜，很容易还没开始干活就把上下文窗口烧光了。

所以导航质量不取决于模型本身，取决于你的代码库 setup 做得怎么样。这个东西，原文管它叫 “harness”。

核心论点：Harness 比模型本身更重要

这篇文章最核心的一个判断，我全文引用：

“

围绕模型构建的生态系统——也就是 harness——对 Claude Code 实际表现的影响，比模型本身更大。

这句话我深有体会。用 Claude Code 时间长了你就会发现，同样的模型，在不同项目里的表现天差地别。区别不在模型，在你给它的环境和指引。

原文把 harness 拆成了七个层次，而且顺序是有讲究的——每一层都建立在上一层的基础上：

下面一层一层拆开说。

STEP

第一层：CLAUDE.md，先从这里开始

CLAUDE.md 是一个上下文文件，Claude 在每个会话启动时自动读取。根目录的 CLAUDE.md 覆盖全局信息，子目录的 CLAUDE.md 覆盖局部约定。

关键原则：精简。

因为 CLAUDE.md 在每个会话都加载，不管你要干什么，所以塞得越多，拖慢越明显。根目录文件只放最关键的东西：项目是什么、几个代码入口、最重要的坑在哪。其他的都属于噪音。

原文特别强调了一个容易踩的坑：把应该在 skill 里的内容写进了 CLAUDE.md。CLAUDE.md 适合放”做任何事都需要知道的背景”，skill 适合放”做某类特定任务需要的专业知识”。

STEP

第二层：Hooks，让 setup 自己进化

Hooks 是在特定事件触发时自动执行的脚本。原文举了两类用法：

预防性的： 在 Claude 写完代码后自动跑 lint、格式化、类型检查。这种确定性检查比让 Claude “记住规则”可靠得多。

进化性的： 这才是更有价值的方向。设置一个 stop hook，在每次会话结束后，趁上下文还在，自动反思这轮对话中有没有什么值得沉淀进 CLAUDE.md 的经验。还有一个 start hook，可以在会话开始时动态加载团队特定的上下文。

我自己在 Obsidian 里就用了类似 stop hook 的机制——每次 Agent 完成操作后，自动记录变更日志。这个动作不费劲，但积累几周之后回看，能清晰看到 Agent 的行为模式。

STEP

第三层：Skills，需要时才加载，不占位置

Skills 跟 CLAUDE.md 最大的区别：Skills 不常驻，只有在相关任务触发时才加载。

这解决了一个很实际的矛盾——你想给 Claude 足够多的专业知识，但你不想让每个简单任务都得先看完一整套安全审查手册才能开始。

原文举的例子很到位：一个安全审查 skill 只在 Claude 评估代码漏洞时才加载；一个文档处理 skill 只在需要更新文档时才出现。

还有一个设计细节：Skills 可以绑定到特定目录。比如支付团队可以把部署 skill 绑定到 payments/ 目录下，这样别人在其他目录工作时这个 skill 永远不会被误触发。

STEP

第四层：Plugins，把好用的东西分发出去

在大代码库里，“好的 setup”很容易停留在某个人的机器上，变成部落知识。

Plugins 解决的问题就是这个。它把 skills、hooks、MCP 配置打包成一个可安装的插件。新来的工程师装完就能获得跟老手一样的上下文和能力。更新通过受控的应用市场统一推送。

原文提到一个实际案例：某大型零售组织开发了一个 skill，把 Claude 接入内部分析平台，然后打包成插件，在面向业务团队大规模推广之前先小范围分发验证。

这一步的关键不在于技术，在于组织意愿——你得有一个人或一个团队愿意把这些东西整理成可复用的资产。

STEP

第五层：LSP，从”搜字符串”到”搜符号”

LSP（Language Server Protocol）给 Claude 提供的是一种精度上的质变。

没有 LSP 的时候，Claude 只能当文本搜索用——grep 一个函数名可能返回几千条结果，Claude 要逐个读才能判断哪个才是真正的引用。有 LSP 之后，它直接按符号语义定位：只返回同一个符号的定义和引用，过滤在 Claude 读取之前就已经完成了。

原文提到一家企业软件公司在全组织推广 Claude Code 之前，先把 C 和 C++ 的 LSP 集成全部部署到位。对于多语言代码库，他们把 LSP 称为”ROI 最高的投入之一”。

我的补充：如果你现在已经在用 Claude Code，但还没配 LSP，可以试一下。你会发现错误定位的速度有一个明显的跃升，尤其是静态类型语言。

STEP

第六层：MCP 服务器，把 Claude 接进你的内部世界

MCP 服务器让 Claude 能访问内部工具、数据源和 API——这些东西靠常规的文件读取和 grep 是接触不到的。

做得比较成熟的团队会搭建 MCP 服务器，把结构化的内部搜索暴露成一个 Claude 可以直接调用的工具。还有些团队用它连接内部文档系统、工单系统、分析平台。

我个人在 Obsidian 里接 MCP 的体验是：打通这一步之后，Claude 能做的事情边界扩大了一大圈。原来只能在本地的 markdown 文件里打转，接上 MCP 之后可以直接操作设计工具、浏览器、项目管理平台。

STEP

第七层：Subagents，把”看代码”和”改代码”分开

Subagent 是一个独立的 Claude 实例，有自己的上下文窗口。它接受一个子任务，独立完成工作，然后只把最终结果返回给主 Agent。

为什么这很重要？因为探索代码和编辑代码放在同一个会话里，会互相挤占上下文窗口。原文建议的做法是：用一个只读 subagent 去摸清一个子系统，把发现写进一个文件；主 Agent 拿到这个文件之后再开始编辑，脑子里已经有完整地图了。

我用过类似的模式——让一个 Agent 先做代码审查，生成一份结构化的分析报告，然后另一个 Agent 基于报告来改代码。效果确实比一边看一边改要好，尤其是跨多个文件的重构。

七个层次汇总：

组件	是什么	何时加载	最适合	常见误区
CLAUDE.md	自动读取的上下文文件	每个会话	项目约定、代码库常识	把该放 skill 的内容塞进来
Hooks	事件触发执行的脚本	事件触发时	自动化一致性、沉淀会话经验	用 prompt 去做应该自动跑的事
Skills	特定任务的打包指令	按需加载	跨会话跨项目复用专业能力	全塞进 CLAUDE.md
Plugins	skills+hooks+MCP 的打包	配置后始终可用	把验证过的配置分发给全组织	让好的 setup 停留在个人机器上
LSP	语言服务器的实时代码智能	配置后始终可用	符号级导航、类型语言自动报错	以为它自动就有了
MCP 服务器	外部工具和数据的连接	配置后始终可用	让 Claude 访问内部工具	基础没打牢就先折腾 MCP
Subagents	独立 Claude 实例处理子任务	调用时启动	拆分探索和编辑、并行工作	在同一会话里一边探索一边改

三个落地模式，来自真正跑通的团队

上面是工具层，下面是实践层。原文总结了三个反复出现的落地模式：

STEP

模式一：让代码库”可导航”

Claude 能干什么，上限就是它能找到多少正确的上下文。太多上下文拖慢性能，太少上下文等于让 Claude 盲飞。

几个实操要点：

• CLAUDE.md 保持精简、分层次。 Claude 在目录树里移动时会累加读取各级 CLAUDE.md，所以根目录文件只放指针和关键易错点，剩下的分到子目录里去。

• 在子目录初始化，不要在仓库根目录。 这一点在 monorepo 里尤其反直觉——但 Claude 会自动向上遍历目录树加载沿途的所有 CLAUDE.md，所以根层级的上下文不会丢。同时，限定了工作范围。

• 测试和 lint 命令按子目录限定。 改了一个服务就跑全量测试，既超时又浪费上下文。子目录级的 CLAUDE.md 里只写这个模块需要的命令。

• 用 .ignore 排除生成文件、构建产物和第三方代码。 配合 permissions.deny 规则做版本控制，全团队共享同一套降噪配置。

• 目录结构不够清晰时，写一张代码库地图。 一个轻量的 markdown 文件，列出每个顶层文件夹和一句话描述。上百个顶层文件夹时用分层索引。

• 跑 LSP 服务器。 把搜索从”字符串匹配”升级到”符号匹配”，过滤在 Claude 读到内容之前就完成了。

STEP

模式二：持续维护 CLAUDE.md，跟上模型进化

这一条很多人容易忽略。

模型在进化，原来写给旧模型的指令可能在新模型上变成束缚。原文举了个例子：之前你写了一条规则说”把重构拆成单文件修改”，因为旧模型跨文件修改容易出错。但新模型可能已经能很好地处理跨文件协调修改了，这条规则就从一个好帮手变成了一个限制器。

同样的，Skills 和 hooks 如果是围绕某个模型的特定短板设计的，一旦这个短板被修复，这些东西就从”必要的补偿”变成了”纯粹的开销”。

原文建议：**每三到六个月做一次有计划的配置审查，**并且在每个大版本模型发布后，如果发现性能似乎到了一个平台期，立刻审视现有配置是否已经拖了后腿。

我的补充：这条建议听起来像运维，但确实有必要。我之前有一个给旧版 Claude 写的”先阅读整个文件再修改”的指令，在新版本上反而导致它浪费上下文去反复读文件。删掉之后，速度和准确率都有明显提升。

STEP

模式三：给 Claude Code 管理分配明确的负责人

只有技术配置，没有人负责推动，落地就是散的。

原文观察到一个规律：推广最快的团队，在全面开放之前就已经有专门的人做了基础设施投入。一个小团队提前把工具接好，让开发者在第一天拿到 Claude Code 的时候就是顺手的状态，而不是一脸懵。

有两个实际案例：一家公司让几个工程师提前搭建了一套插件和 MCP，正式推广当天就能用；另一家公司有专门管理 AI 编程工具的团队，在 rollout 之前基础设施已经就绪。

原文提到一个新角色叫 “Agent Manager”——一个兼具 PM 和工程师能力的角色，专门管理 Claude Code 生态：配置归谁管、权限策略怎么定、插件市场怎么维护、CLAUDE.md 规范是什么、谁来保证这些东西持续更新。

最简版本：找一个 DRI（直接负责人），把配置、权限、插件、规范这四样明确分配给一个人。

如果没有这个人，“知识永远停留在部落状态，推广率一定会到平台期。”

对于大组织，尤其是受监管行业，还会遇到更复杂的问题：谁能决定哪些 skills 和 plugins 可用？怎么防止几千个工程师各自重新发明同一套东西？怎么保证 AI 生成的代码跟人类写的代码走同样的审查流程？

原文建议的策略是：从有限的批准 skill 列表、强制代码审查流程、小范围试点开始，信心建立后再扩大。最顺畅的 rollout 都是工程、信息安全、治理三方代表一起定义要求、一起制定路线图。

这篇文章适合谁看

如果你已经在用 Claude Code 做个人项目，这篇讲的是：当你从”能跑通”进化到”团队在跑”的时候，什么样的配置结构能撑住规模化。

如果你正准备在团队或组织里推广 Claude Code，这篇文章就是一台现成的路线图——每一层的优先级、每一步可能踩的坑、每一项对应的组织角色，它都讲清楚了。

如果你只是刚开始用 Claude Code，我建议先跑通几个项目，感受一下它在你自己的代码库里的表现，然后再回来看这篇文章。有些判断，你没有踩过坑之前看了只是概念，踩过之后再回头看就变成了经验。

我自己的判断

读完这篇文章，我有几个想法分享：

第一，Claude Code 未来的竞争壁垒不在模型，在 harness。 当各家模型的能力趋同，真正拉开差距的是谁能给模型提供更好的运行环境。这篇文章等于给出了一个标准答案：七层架构，按顺序来，别跳步。

第二，“配置工程”会成为一个新的技能领域。 过去我们说”软件工程”，关注的是代码写得对不对。未来还需要一种新的工程能力：怎么写好 CLAUDE.md、怎么设计 skill 的加载边界、怎么让 hooks 自动进化配置。这不是运维，也不是传统意义的开发，是一个全新的技能树。

第三，不要让好的配置停留在你的机器上。 如果你现在是团队里 Claude Code 用得最好的人，你最大的价值不是用得好，是把你用好的方式变成别人也能用的资产。

我是「超级猛」，长期折腾AI编程、Agent和自动化工作流。写Claude Code、Codex、Hermes这些工具的实战笔记，也聊AI怎么改变开发和内容生产的真实逻辑。

内容效果不满意？点此反馈