Claude Code 在大型代码库里的真实体验
Claude Code 在大型代码库里的真实体验
用 AI 写一个小项目，现在谁都会。描述一下需求，AI 哗哗哗就给你生成一个能跑的应用。
但你试试把 AI 丢进一个有 50 万行代码的项目里？
完全不是一回事。
大型代码库是 AI 编程工具的终极考验。context window 不够用、依赖关系理不清、代码风格不一致、历史包袱一大堆。很多人试了一下觉得「AI 根本搞不定」，然后就放弃了。
但问题往往不在 AI，而在你用它的方式。这篇文章聊聊 Claude Code 在大型代码库里的最佳实践，都是实打实的经验总结。
先把「地图」给 AI
你想想看，你新加入一个大型项目的时候，第一件事是什么？
不是直接开始写代码，而是先搞清楚这个项目的结构。哪些模块是核心、哪些是边缘、代码风格是什么样的、团队有什么约定。
AI 也是一样。只不过 AI 不会自己去摸索，你得给它一张地图。
最有效的方式是在项目根目录放一个 AGENTS.md 文件。这个文件相当于给 AI 的项目说明书。里面写清楚项目的整体架构、关键目录的作用、代码规范、常用命令，以及哪些地方是雷区不能碰。
Claude Code 启动的时候会自动读这个文件，就像一个新人入职第一天先读团队文档一样。这个投入非常值得，一个写得好的 AGENTS.md 能让 AI 的输出质量提升好几个档次。
别让 AI 一次吃太多
大型代码库最大的问题是 context window 放不下。
一个 50 万行的项目，你不可能把所有代码都塞给 AI。就算 context window 够大，信息太多 AI 反而会迷失。这就像你同时看 50 页文档和只看 5 页文档，后者的理解深度往往更好。
最佳实践是把大任务拆成小任务。不要说「帮我重构这个模块」，而是说「帮我看看这个文件里的这个函数，它和那个模块的交互逻辑是什么」。
给 AI 一个具体的问题，它能给出精准的答案。给它一个模糊的大问题，它只能给你一个模糊的大回答。
另一个技巧是善用 Claude Code 的 @ 符号引用特定文件。你可以用 @src/auth/login.ts 这样的方式精确指定 AI 需要关注的文件，而不是让它自己去猜。
渐进式理解，不是一次性灌入
我自己在大型项目里用 Claude Code 的时候，发现一个特别有意思的模式。
最开始我只是让 AI 帮我读代码。不是让它写什么，就是让它解释某段代码在做什么。这个阶段我把它叫做「让 AI 熟悉环境」。
然后我会问一些架构层面的问题，比如「这个模块和那个模块之间的数据流是什么样的」、「如果我要修改这个功能，会影响哪些地方」。
等到 AI 对这个项目有了足够的理解之后，我才开始让它帮我写代码。
这种渐进式的方式比直接上来就让 AI 改代码要靠谱得多。因为你给了 AI 足够的上下文，它的输出质量自然就高了。
你想想看，你招一个高级工程师进来，也不可能第一天就让他改核心代码吧？总得先花几天熟悉项目。AI 也是一样的。
写好 Commit Message 比你想的重要得多
这个建议听起来可能有点奇怪，但在大型代码库里特别实用。
当你让 AI 帮你做了一次修改之后，你可以让它帮你生成一个详细的 commit message，描述这次修改做了什么、为什么这样做、影响了哪些地方。
这些 commit message 会成为 AI 理解项目演化过程的线索。
下次你再让 AI 帮你做相关的事情，它可以通过 git log 快速了解这个模块之前经历过哪些修改。这些历史信息比代码本身有时候更有价值，因为它告诉你「为什么代码是现在这个样子」。
好的 commit message 不仅对 AI 有用，对你自己、对团队里的其他人都是一个长期投资。
永远不要跳过 Review
这条建议适用于所有 AI 编程场景，但在大型代码库里尤其重要。
大型代码库的修改牵一发而动全身。AI 可能改了一个它觉得没问题的地方，但实际上影响了三个其他模块。如果你不仔细 review，这些影响可能要到线上出问题你才发现。
我的做法是让 AI 在每次修改之后，主动列出它影响了哪些文件、哪些函数、哪些依赖。然后我再根据这个清单去检查相关代码。
还有一点特别重要，不要只看 AI 改了什么，还要看它没改什么。有时候 AI 会漏掉一些必要的修改，比如改了一个接口但没有更新调用方。这种遗漏在小项目里很容易发现，在大型代码库里可能藏得很深。
处理历史包袱的策略
每个大型代码库都有历史包袱。十年前写的代码、不再维护的依赖、没有文档的模块、只有一个人懂的「黑魔法」。
这些地方是 AI 最容易出错的地方。因为 AI 的训练数据里可能没有那些过时的技术，或者它不了解那些「约定俗成」的写法背后的特殊原因。
遇到这种情况，我的建议是先自己搞清楚现状，再让 AI 帮你改。
你可以先花时间读代码、查 git 历史、问团队老人，搞明白这段代码为什么会是这个样子。然后把你的理解告诉 AI，让它在你的约束下做修改。
不要指望 AI 能自己理解那些「只可意会不可言传」的设计决策。这些决策背后往往有业务上下文、历史原因或者团队政治，AI 是不可能知道的。
大型代码库用 AI 的正确心态
归根结底，用 AI 处理大型代码库，最重要的是心态。
你不能指望 AI 像魔法一样解决所有问题。它是一个工具，一个特别强大的工具，但它需要你来引导。
你对项目的理解越深，AI 能帮你的就越多。反过来，如果你自己都搞不清楚项目的架构和逻辑，AI 只会给你制造更多混乱。
大型代码库是检验 AI 编程工具真实能力的试金石。能在小项目上跑得欢不算本事，能在百万行代码的项目里稳定输出才是真功夫。
而这个真功夫，一半在 AI，一半在你。