从 Claude Code 的大型代码库实践，看 AI Coding 如何从“个人效率工具”走向“工程生产系统”

来源：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start

很多人使用 AI 编程工具时，关注点通常很直接：

这个模型够不够强？

它能不能一次写出正确代码？

它会不会理解我的项目？

这些问题当然重要，但它们只问到了表层。真正进入大型代码库之后，问题会变得完全不同。

在一个几十万行、几百万行，甚至跨多个仓库、多个团队、多个技术栈的系统里，AI 编程工具面临的核心问题不是“会不会写代码”，而是：

它怎么知道该看哪里？

它怎么区分新代码和旧代码？

它怎么理解团队约定？

它怎么知道哪些命令该执行？

它怎么避免把过期文档当成事实？

它怎么把一次成功经验沉淀成团队能力？

Anthropic 最近发布了一篇关于 Claude Code 在大型代码库中工作的文章。表面看，它讲的是 Claude Code 的最佳实践；但真正值得提取的，是它背后提出的一套更通用的 AI Coding 工程化思想。

这篇文章的核心可以压缩成一句话：

AI Coding 的效果，不只取决于模型，而取决于模型所在的工程环境。

换句话说，一个模型是否能在大项目里稳定产出，不是单看它的推理能力，而是要看它有没有足够清晰的上下文、可靠的工具链、自动化的验证机制，以及可持续维护的组织流程。

这也是很多团队使用 AI 编程工具时最容易忽略的地方。

一、AI 在大代码库里，真正缺的不是“全部上下文”

很多人对 AI 编程有一个直觉：

既然模型不理解项目，那就把更多代码、更多文档、更多规则塞给它。

这个思路看似合理，但在大代码库里经常失效。

原因很简单：大项目的信息量太大，不可能一次性全部交给模型。即使上下文窗口变得更大，把所有代码、文档、配置和历史决策都塞进去，也会带来新的问题：噪音变多、重点变弱、

模型注意力被稀释。

对大代码库来说，更关键的问题不是“让 AI 看到所有东西”，而是“让 AI 知道从哪里开始找”。

Claude Code 的思路更接近一个真实工程师：它不是提前把整个代码库都索引好，再从索引里召回片段；而是在本地代码库中遍历文件、读取文件、使用 grep 搜索，并沿着引用关系追踪代码。

这和传统 RAG 式代码检索有明显差别。

RAG 的问题在于，索引可能滞后。大型工程团队每天都有大量提交，函数可能被改名，模块可能被移动，接口可能被删除。如果索引更新不及时，AI 拿到的就可能是几小时、几天甚至几周前的代码。

在普通问答场景里，信息旧一点可能还可以接受；但在代码场景里，旧代码就是错误上下文。

所以，Claude Code 强调的是一种更接近实时工作区的方式：从开发者当前机器上的真实代码库出发，现场搜索，现场阅读，现场推断。

但这也带来一个新问题：

如果 AI 不知道入口在哪里，它就会在庞大的文件系统里盲目搜索。

这时候，大代码库是否“可导航”，就变成了 AI Coding 能否成功的前提。

二、让代码库变得“可导航”，比写神奇 Prompt 更重要

很多人一提到 AI 编程，就会去找 Prompt 模板。

比如：

“你是一个资深 Java 架构师，请帮我分析……”

“请一步一步思考……”

“请严格遵循最佳实践……”

这些提示词不是完全没用，但它们解决不了大型代码库的核心问题。

因为模型真正需要的不是角色扮演，而是工程地图。

Claude Code 文章里反复强调 CLAUDE.md 的价值。这个文件本质上不是说明书，也不是文档仓库，而是给 AI 的项目上下文入口。

更准确地说，它像是代码库里的“导航标识”。

一个好的根目录 CLAUDE.md 不应该写成百科全书，而应该写成地图：

• auth-service：用户、角色、权限、菜单、资源管理

• workflow-service：审批流、流程节点、任务流转

• finance-service：报销、借款、还款、票据处理

• frontend：管理端页面，基于 Vue / React

• deploy：Jenkins、Docker、K8s、Nginx 部署文件

Global Conventions

• Java 17

• Spring Boot 3.x

• Controller 不写业务逻辑

• 金额字段使用 BigDecimal

• Long 返回前端时序列化为 String

Critical Gotchas

• 权限校验不能依赖前端传 permission_code

• 修改流程节点逻辑必须补充回归场景

• Mapper XML 中新增 SQL 时必须检查索引和空值处理


它不需要解释每个表、每个接口、每个业务分支。那些内容应该放在更靠近具体模块的位置。

更合理的结构是：

/CLAUDE.md
/auth-service/CLAUDE.md
/workflow-service/CLAUDE.md
/finance-service/CLAUDE.md
/frontend/CLAUDE.md
/deploy/CLAUDE.md

根目录负责全局地图，子目录负责局部规则。

这背后的原则很重要：

上下文要分层，而不是堆叠。

如果把所有规则都塞进一个巨大文档里，AI 每次启动都要读取一大堆不相关信息，结果反而变差。

大项目里的上下文设计，应该像后端系统设计一样：分层、解耦、按需加载。

三、模型不是独立工作的，Harness 才是关键

原文里有一个非常重要的概念：harness。

可以把它理解成模型外部的工程承载系统。

很多人以为 Claude Code 的能力主要由模型决定：模型强，它就能写好；模型弱，它就写不好。

但在真实工程环境里，模型只是其中一部分。真正决定结果的，是模型周围有没有一套完整的工作系统。

这套系统包括：

这几个组件放在一起，才构成一个真正可用的 AI Coding 环境。

这里最值得注意的是：

Prompt 不是万能的。

如果一个动作是确定性的，就不应该靠提示词要求模型“记住”，而应该交给工具自动完成。

比如：

每次修改后执行测试。

每次保存后执行格式化。

每次改 SQL 后检查索引。

每次结束会话后生成修改摘要。

这些事情写在 Prompt 里，模型可能会忘；但做成 hooks，就变成了稳定流程。

这就是工程化和提示词工程的区别。

提示词是软约束。

工具链是硬机制。

四、Skills 的价值：不要让所有知识挤在同一个上下文里

在复杂项目里，不同任务需要的知识完全不同。

做接口开发，需要知道 Controller、DTO、参数校验、异常处理。

改 SQL，需要知道索引、执行计划、空值处理、金额精度。

改权限模块，需要知道用户、角色、资源、菜单、按钮、API 之间的关系。

改工作流，需要知道节点状态、流转条件、回退逻辑、审批人规则。

如果把所有这些知识都写进 CLAUDE.md，它会迅速膨胀，最后变成一份谁都不想维护、AI 也不一定读得好的巨型文档。

Skills 的意义就在这里。

它不是项目背景，而是某一类任务的方法论。

比如一个 Java 企业项目可以准备这些 Skills：

spring-api-review.md
mybatis-sql-review.md
permission-model-change.md
workflow-node-change.md
frontend-vue-review.md
k8s-jenkins-deploy-check.md

每个 Skill 只处理一种任务。

当 AI 修改接口时，加载 API Review Skill。

当 AI 修改 Mapper XML 时，加载 SQL Review Skill。

当 AI 改权限表结构时，加载 Permission Model Skill。

这样做的价值不是“文档更整齐”，而是让 AI 在正确的时刻获得正确的知识。

这也是大型系统设计里很常见的思想：

不要把所有能力做成全局单例。

要按领域、按场景、按边界组织能力。

AI Coding 也是一样。

五、LSP 的意义：让 AI 不只是 grep，而是理解符号

在小项目里，grep 很好用。

但在大项目里，grep 很容易失效。

比如你搜索 execute、submit、query、process 这样的函数名，可能会返回几百甚至几千个结果。AI 需要不断打开文件，判断哪个才是相关代码，最后上下文很快被消耗掉。

这时候 LSP 的价值就出来了。

LSP，也就是 Language Server Protocol，是现代 IDE 实现“跳转定义”“查找引用”“类型推断”“错误提示”的基础。

如果 AI 能使用 LSP，它就不只是文本搜索，而是可以做符号级导航：

这个方法定义在哪里？

这个接口有哪些实现类？

这个字段在哪里被引用？

这个类的调用链是什么？

同名方法中，哪个才是当前类型真正绑定的那个？

对于 Java、C++、C# 这类强类型语言，LSP 的价值尤其明显。

因为很多关系无法只靠字符串判断。

Spring 项目里也一样。

你要理解一个接口，不能只看 Controller。你还要追踪 Service、Mapper、XML、Entity、DTO、VO、配置类、注解、事务边界，甚至还有 AOP、拦截器和权限注解。

如果 AI 只有 grep，它很容易看错。

如果 AI 有 LSP，它就更接近一个真正使用 IDE 的开发者。

这也说明一个问题：

AI Coding 的未来，不是让模型孤立地读文本，而是让模型接入开发者原本就依赖的工程工具。

六、MCP 很强，但不应该第一个做

现在很多人一听到 MCP，就想马上接入各种系统。

接数据库。

接 Jenkins。

接 GitLab。

接 Jira。

接知识库。

接内部接口。

这些方向都没问题，但顺序很重要。

如果你的代码库本身没有整理好，CLAUDE.md 没有，模块边界不清，测试命令不明确，构建流程也不稳定，那一上来做 MCP，往往只是把混乱扩散到更多地方。

更合理的顺序应该是：

CLAUDE.md
→ Skills
→ Hooks
→ LSP
→ MCP

先让 AI 看得懂当前项目。

再让 AI 掌握常见任务方法。

再让 AI 的关键动作自动化。

再让 AI 具备符号级代码导航能力。

最后才是接入外部系统。

MCP 的价值在于扩展 AI 的工作边界。比如：

读取需求单。

查询构建日志。

查看接口文档。

检索内部知识库。

分析线上错误日志。

查询数据库表结构。

但它不应该替代基础工程整理。

如果基础上下文是乱的，MCP 只会让 AI 更快地访问更多混乱信息。

七、AI Coding 的组织问题：个人能用，不等于团队能用

个人使用 AI 编程工具，门槛很低。

装一个 CLI，打开项目，输入需求，很快就能看到效果。

但团队级使用完全不同。

团队需要解决的是：

谁维护 CLAUDE.md？

谁决定哪些 Skills 是标准的？

谁管理 hooks？

谁控制 MCP 权限？

谁负责插件分发？

AI 生成的代码走什么 review 流程？

哪些任务允许 AI 自动执行？

哪些操作必须人工确认？

如果没有统一治理，AI Coding 很容易变成“个人经验碎片”。

有的人写了一套很好用的配置，但只存在自己电脑里。

有的人调通了一个工作流，但没有沉淀成团队标准。

有的人踩过坑，但没有进入项目文档。

最后每个人都在重复搭环境、重复写提示词、重复踩坑。

这不是工具问题，而是组织问题。

Anthropic 原文里提到，在一些成熟组织里，已经出现了类似 agent manager 的角色。这个角色不只是工程师，也不只是产品经理，而是负责管理 AI Coding 生态：配置、权限、插件、规范、推广、治理。

即使没有专门团队，至少也需要一个明确负责人。

这和 DevOps、平台工程、研发效能的发展路径很像。

刚开始，每个人自己写脚本。

后来，团队发现脚本需要共享。

再后来，脚本变成平台能力。

AI Coding 也会走类似路径。

从个人工具，到团队规范，再到组织级开发基础设施。

八、这篇文章真正给开发者的启发

如果只把这篇文章看成 Claude Code 的官方宣传，就会低估它的价值。

它真正提供的是一个判断框架：

AI Coding 不是把模型放进代码编辑器，而是把模型放进工程系统。

对个人开发者来说，最小可行版本可以很简单：

1. 写一个根目录 CLAUDE.md

2. 为核心模块补充局部 CLAUDE.md

3. 建一份 codebase-map.md

4. 明确每个模块的构建和测试命令

5. 整理常见坑和修改注意事项

6. 为高频任务沉淀几个 Skill 文档


这不需要大团队，也不需要复杂平台。

只要你愿意整理自己的项目，AI 的效果就会明显变好。

对团队来说，更成熟的版本是：

1. 标准化 CLAUDE.md 分层结构

2. 建立团队级 Skills

3. 用 hooks 固化测试、格式化、检查流程

4. 接入 LSP 提升代码导航能力

5. 谨慎接入 MCP，优先只读权限

6. 建立 AI 生成代码的 review 规范

7. 定期清理过时配置

8. 指定负责人维护 AI Coding 工作流


这里面最重要的不是技术复杂度，而是持续维护。

因为 AI 模型在进化，项目也在进化。

今天有效的提示和约束，三个月后可能变成负担。

比如早期模型可能不擅长跨文件重构，所以团队会要求它“一次只改一个文件”。但新模型可能已经能处理跨文件修改，这条规则反而会限制它。

所以 AI Coding 的配置也需要像代码一样维护。

它不是一次性文档。

它是工程资产。

九、我认为最值得带走的四个结论

第一，AI 不需要知道所有代码，但必须知道从哪里开始。

大项目的关键不是喂更多上下文，而是建立清晰的导航结构。

第二，Prompt 解决不了工程流程问题。

能自动化的事情，不要靠模型记忆。测试、格式化、检查、摘要、权限限制，都应该尽量交给 hooks 和工具链。

第三，知识要按任务加载，而不是全局堆积。

CLAUDE.md 放项目共识，Skills 放专项方法，MCP 负责外部系统，LSP 负责代码导航。每种东西都有自己的边界。

第四，AI Coding 最终会变成研发基础设施。

今天很多人还把它当个人助手，但在大型组织里，它会越来越像 DevOps、CI/CD、研发效能平台一样，成为团队工程系统的一部分。

真正的门槛，不是会不会用 AI，而是会不会整理工程环境

AI 编程工具正在变强，这一点已经很明显。

但越往真实项目里走，越会发现：模型能力只是起点。

真正决定 AI 能否稳定工作的，是代码库本身是否清晰，文档是否分层，规则是否可执行，工具是否接通，验证是否自动化，团队是否有人维护这套系统。

所以，与其不断寻找一个“更强的模型”，不如先问一个更实际的问题：

我的项目，对 AI 来说，是不是一个可理解、可导航、可验证的工作环境？

如果答案是否定的，那么模型再强，也只是在混乱中猜测。

如果答案是肯定的，AI 就不只是一个代码补全工具，而会逐渐变成你工程体系中的协作者。

这也是 Claude Code 这篇文章最值得学习的地方：

它没有把 AI Coding 描述成魔法。

它把 AI Coding 放回了工程本身。