Anthropic 百万行代码库的官方最佳实践

随着AI 编程智能体的越来越深入到日常工作相信你也遇到了大型项目和和小型代码库完全不同的场景。正好最近也是在做大型项目的重构开发刷到这篇来自 Anthropic 官方的文章。系统梳理了 Claude Code 在大规模代码库中的运作机制、Harness 架构的七个扩展点以及在项目中成功使用的三种配置模式。本文介绍的模式具有普遍适用性可以为考虑采用 AI 智能体编程的团队提供一个业内领先公司的工程实践。如何浏览大型项目的代码首先需要解决的问题就是如何浏览代码库。Claude Code 会像开发工程师一样遍历目录、读取代码文件、用 grep 精确查找所需内容、在代码库中追踪引用关系。记得早期大家都是依赖 RAG 检索对整个代码库做嵌入索引查询时检索相关片段。但是在大规模场景下索引的速度跟不上提交速度。等到查询时它反映的已经是几天、几周甚至几小时前的代码了。返回的结果可能是两周前已重命名的函数或者是上个版本中已删除的模块而且没有任何过时提示。所以 Claude Code 的解决方案是采用 智能Agentic搜索。不需要RAG模式的嵌入embedding没有集中式索引无论多少工程师同时提交新代码每个人的实例都直接基于实时代码库工作。相应的代价就是Claude 需要足够的起始上下文才能知道去哪找。这就意味着 Claude 导航质量取决于代码库的配置程度核心就是 CLAUDE.md 文件和 Skills 的分层上下文设计。如果在十亿行代码库里模糊搜索就会遇到上下文窗口的限制而导致大模型什么都干不了。Harness框架与模型同等重要一个常见的误解是Claude Code 的能力完全取决于所用模型因为 Opus 4.7 是目前最好的大模型。实际上围绕模型构建的 Harness 生态即框架对实际表现的影响超过模型本身。Anthropic 把 Harness 拆成七个组件从基础到高级层层递进。第一层CLAUDE.md 文件CLAUDE.md 是 Claude 每个会话自动读取的上下文文件。根目录文件把握全局子目录文件描述本地惯例。因为每个会话都会加载内容必须聚焦在广泛适用的信息上否则会拖累性能。→ CLAUDE.md 文档https://code.claude.com/docs/zh-CN/memory第二层Hooks 让配置自我改进大多数团队把 Hooks 看作防止 Claude 犯错的脚本。但更有价值的用法是持续改进。Stop Hook 可以在上下文还新鲜时反思刚才的会话提出 CLAUDE.md 更新建议。Start Hook 可以动态加载团队专属上下文每个开发者打开对应模块时自动获得正确配置。对于 linting、格式化等自动化检查Hooks 比让 Claude 记住指令更可靠、更一致。→ Hooks 指南https://code.claude.com/docs/zh-CN/hooks-guide在这篇文章中万字深研 Harness 工程实践指令遵从率 20%Hook 执行率 100%研发团队就充分使用了Claude Code 的Hook 机制设计了8 门状态机8-Gate State Machine横跨七个阶段16个生命周期来保证智能体在大型开发项目中的指令遵循率。第三层Skills 按需加载专业知识大型代码库有几十种任务类型不可能每种专业知识都在每个会话中常驻。Skills 通过渐进式披露解决这个问题把专业工作流和领域知识卸载只在任务需要时加载。比如安全审查 Skill 在 Claude 评估代码漏洞时才加载文档处理 Skill 在代码变更需要更新文档时才加载。Skills 还可以限定在特定路径。支付服务团队把部署 Skill 绑定到自己的目录别人在仓库其他位置工作时它绝不会自动加载。→ Skills 文档https://code.claude.com/docs/zh-CN/skills第四层使用插件分发成熟解决方案大型代码库的通病是好的配置容易停留在内部团队层面。插件机制把 Skills、Hooks 和 MCP 配置打包成一个可安装包新工程师安装后第一天就能获得和资深工程师完全相同的上下文和能力。插件的更新可以通过插件托管市场统一分发。Anthropic 举了一个例子某大型零售组织构建了一个 Skill把 Claude 连接到内部分析平台业务分析师不用离开工作流就能拉取绩效数据。他们在全公司推广前先把这个 Skill 打包成插件分发。→ Plugins 文档https://code.claude.com/docs/zh-CN/plugins第五层语言服务器协议LSP 集成按函数/变量名查找大型代码库的 IDE 通常已经在运行语言服务器协议LSP提供跳转到定义和查找所有引用。把这一能力暴露给 Claude它就获得了符号级精确导航跟随函数调用找到定义、跨文件追踪引用、区分不同语言中的同名函数。没有 LSPClaude 只做文本模式匹配很容易命中错误的符号。一家大型企业软件公司在全组织推广 Claude Code 之前先部署了 LSP 集成目的就是让 C 和 C 代码的导航在大规模下保持可靠。对于多语言代码库这是投资回报率最高的配置之一。→ 代码智能 Pluginhttps://code.claude.com/docs/zh-CN/discover-plugins#code-intelligence我之前的文章有介绍开源的项目实现了类似的功能GitNexus 把代码库变成知识图谱审核 AI 产出更清晰改 Bug 更精准。可以将整个代码库索引成一个知识图谱追踪每一个依赖、调用链、功能集群和执行流程然后通过 MCP 协议暴露给 AI 代理。第六层MCP 服务器连接一切MCP 服务器让 Claude 连接它原本无法触及的内部工具、数据源和 API。成熟的团队把结构化搜索暴露为 Claude 可以直接调用的工具。其他团队则连接内部文档、工单系统或分析平台。这一层功能和操作相信大家多少都用过。比如通过MCP连接腾讯文档从生成到分享我把 OpenClaw 腾讯文档技能跑通了。又比如 WorkBuddy 默认提供的连接器管理以及可自定义的连接器。第七层子智能体Subagents探索与编辑分离Subagent 是拥有独立上下文窗口的隔离 Claude 实例。它接收任务、完成工作、只把最终结果返回给父 Agent。一些团队的做法是先启动一个只读 Subagent 梳理子系统并把发现写入文件然后主 Agent 在掌握全局后执行编辑。→ Subagents 文档https://code.claude.com/docs/zh-CN/sub-agentsClaude Code 的 Harness 架构为了更直观地对比官方给了一张表组件是什么何时加载最适合常见误区CLAUDE.md自动读取的上下文文件每个会话项目惯例、代码库知识把该放 Skill 的内容塞进来Hooks事件触发的脚本事件触发自动化行为、捕获经验用 Prompt 做本该自动运行的事Skills任务类型的打包指令按需加载跨会话的复用专业知识全塞进 CLAUDE.mdPluginsSkillsHooksMCP 打包配置后始终可用组织内分发好方案让好配置停在个人层面LSP语言服务器的实时智能配置后始终可用符号导航、类型错误检测以为它是自动的MCP 服务器外部工具数据连接配置后始终可用访问内部工具基础没搭好就搞 MCPSubagents独立 Claude 实例被调用时探索编辑分离、并行同一会话里又探索又编辑三种配置模式1. 让代码库可导航Claude 的能力上限取决于它能否找到正确上下文。加载太多会拖性能加载太少会让它盲目探索。下面六条是成功部署中较好的做法CLAUDE.md 精简且分层。Claude 遍历目录树时叠加加载根文件只管全局指针和关键注意事项其他内容都会变成噪声。在子目录中初始化不在仓库根目录。作用域限定在任务实际相关的部分时效果最好。Claude 会自动向上遍历并加载沿途的每个 CLAUDE.md所以根级别上下文不会丢。按子目录限定测试和 lint 命令。只改了一个服务就跑全量测试会超时并浪费上下文。子目录级的 CLAUDE.md 应指定该部分适用的命令。用 排除生成文件、构建产物和第三方代码。在.claude/settings.json中提交permissions.deny规则排除项受版本控制团队每个人自动获得相同的噪声过滤。开发代码生成器的人可以在本地设置中覆盖项目级排除项不影响其他人。当目录结构不够清晰时构建代码库地图。在仓库根目录放一个轻量 markdown 文件列出每个顶层文件夹及一行描述。对于数百个顶层文件夹的代码库用分层方式根文件只描述最高层子目录 CLAUDE.md 提供下一层细节。使用语言服务协议LSP按名称精确定位。grep 查找命令常见函数名可能返回几千个结果Claude 会浪费上下文逐个打开判断。LSP 只返回同一函数名/变量名的引用过滤在读取之前就完成了。需要注意的是分层的 CLAUDE.md 方案在极端情况下也会失效比如几十万文件夹、几百万文件的代码库或非 Git 版本控制的遗留系统。2. 随模型进化维护 CLAUDE.md为当前模型写的规则可能在下一个模型上变成束缚。比如一条告诉 Claude 每次只改一个文件的规则帮助了早期模型不跑偏但会阻止新模型做它擅长的跨文件协同编辑。为弥补特定模型限制而构建的 Skills 和 Hooks一旦限制不存在了就成了额外开销。在 Perforce 代码库中拦截写入执行p4 edit的 Hook在 Claude Code 增加原生 Perforce 模式后就多余了。团队应该每三到六个月做一次配置审查重大模型版本发布后如果感觉性能停滞也值得做一次。3. 分配责任人这一条是非技术的建议组织结构要适应AI 编程带来的变革。推广AI 编程最快的团队都在广泛开放前做了基础设施投入。一家公司的几位工程师提前构建了全套 Plugin 和 MCP第一天就可用。另一家公司有专门管理 AI 编码工具的完整团队推广前就准备好了基础设施。这两种情况下开发者的第一次接触就是高效的采用自然扩散。Claude Code 推广的阶段做这种事的人通常归属在开发者体验或开发者生产力部门。一个正在出现的新角色是智能体经理Agent Manager混合 PM 和工程师职能专门管理 Claude Code 生态。如果还没有专门团队最小可行版本是一个开发负责人对 Claude Code 配置拥有所有权的人有权决定设置、权限策略、Plugin 市场和 CLAUDE.md 惯例并有责任保持它们最新。对于大型组织最容易出现以下治理问题谁控制哪些 Skills 和 Plugins 可用怎么防止成千上万的工程师重复造轮子AI 生成的代码怎么走和人工代码一样的审查流程Anthropic 的建议是从已批准的 Skills、强制代码审查和有限初始访问开始随着信心增强逐步扩展。早期就建立跨职能工作组把工程、信息安全、治理代表拉到一起定义需求、制定路线图。比如这篇在国内碧桂园研发团队落地的实践经验总结AI Code 企业落地问题成本失控与无法持续记忆上下文及解决方案。在展开 AI Coding 后实现了改进过程的可观测然后在此基础上解决了 Token 消耗过大上下文优化问题。最后给出一份 Claude Code 的官方检查清单入门检查清单原文https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start推荐Lazyweb 免费的 25.7 万截图库让 AI 写出好看的前端页面Multica让 AI 智能体变为你的员工给 AI 装上真实浏览器camofox-browser 实战基于 DeepSeek 的编程智能体 TUIChatGPT 里的哥布林goblins是怎么来的不用一个违禁词 让 Claude 说出炸药配方红队攻击实录大模型黑箱揭秘GPT、Claude、Gemini、Grok、Hermes 系统提示词全公开jcode 深度解析纯 Rust 打造它凭什么号称「最强 Coding Agent」从73.7到89.5HALO 智能体用轨迹分析实现了递归自我进化小米模型 MiMo V2.5 全系列 Pro · TTS 免费用让 AI 帮你修 bug结果它把整个代码重写了一遍没人整理过的 DeepSeek 进化史25篇论文里的技术蜕变给 OpenClaw 接入10000工具和数据为你盯盘给出独家策略Claude Design 系统提示词被泄露AI 如何成为你的专业设计师