如何避免 Claude 写代码时每个改动都会搜索整个代码库？

ivye
免费干货
5小时前
8热度
0评论

随着你用 Claude 写代码，常见的一个问题会很快出现：代码库越来越大、功能不断增加，原本很小的改动也会变得出奇地“昂贵”。你让 Claude “只改一下这个行为”，它却开始在仓库里到处翻找定位要改的地方。这个探索过程会消耗大量 token，更糟的是，由于它还没像你一样理解项目架构，往往会在错误的层级上动刀。
好消息是，你不需要和模型“硬刚”，也不必不停地粘贴更多上下文。核心思路很简单：让 AI 按照人的思路去思考。

为什么小改动会变得很耗 token

人类在维护一个熟悉的项目时，很少会为每个任务都“把整个仓库搜一遍”。他们脑子里已经有一张清晰的地图：

哪些模块负责哪些职责
配置放在哪里
哪些文件是“入口”
团队遵循什么约定
哪些地方不要碰（危险区、生成代码、遗留区域）

有了这张地图，维护者就能直接去到正确的文件，做一个小而精准的修改，然后跑对的验证命令。
而 Claude 并不会像人那样在不同会话之间保留对仓库的持续记忆。每次你让它改代码，都很像把仓库交给一个第一天入职的新同事。新人通常会先浏览一圈：“这里有什么？后端在哪？测试在哪？路由怎么组织？”这段“入职熟悉”的过程，正是 token 被消耗掉的地方：列目录、开文件、从零构建对项目的理解。
所以真正的问题变成了：

我们怎样才能让 Claude 像一个对项目非常熟悉的人那样工作？

如果你能把项目的“心智地图”压缩成一小段稳定、每次都能优先提供给 Claude 的上下文，就能大幅减少它对全仓库的广泛扫描。Claude 会更容易直接跳到最可能的模块，找到正确的扩展点，然后做出精准的补丁。
实践中，这意味着给 Claude 一份项目指南：用一处权威的文档写清楚架构、约定和“导航捷径”——就像你给一个资深工程师的入职 briefing 一样。
有两个机制特别好用：

CLAUDE.md 文件
用于领域规则的 .claude/rules 目录

`CLAUDE.md`：Claude 每次都应先读的项目地图

一个非常有效的模式，是在仓库根目录创建 CLAUDE.md。关键在于：Claude 在处理代码改动时会读取它，因此这里是最理想的“常驻”说明书。
把 CLAUDE.md 当作一份高密度的项目上手备忘录，而不是泛泛的 README。README 往往写给用户；CLAUDE.md 则是写给要动手改代码的助手。
那它应该写什么？优先放能帮助 Claude 快速定位修改点、并避免高风险改动的信息。

1）项目概览

说明项目是什么，以及主要组件有哪些。
例如：

“这是一个 SaaS Web 应用，前端 React，后端 Node/Express API。”
“后端采用领域驱动设计；业务逻辑在 /src/domain，不要写在 controller 里。”

2）仓库结构

列出关键目录及其职责。保持简洁、以实用为主。
例如：

/src/api — HTTP 处理、请求校验、路由
/src/domain — 核心业务规则、实体、服务
/src/infra — 数据库适配器、外部集成
/src/ui — 前端组件
/tests — 单元/集成测试
/migrations — 数据库迁移（不要手改；通过工具生成）

光这一条就能节省大量 token，因为 Claude 不再需要猜“职责应该放在哪里”。

3）“改 X 应该去哪里改”的规则

人类往往知道非常明确的落点，把这种经验写下来。
例如：

“新增 API endpoint：在 src/api/routes.ts 加路由，在 src/api/handlers/* 写 handler，业务逻辑放在 src/domain/*。”
“修改定价规则：改 src/domain/billing/pricing.ts，并同步更新 tests/billing/pricing.test.ts。”

这些规则就像捷径，让 Claude 不必打开一堆无关文件就能直达目标。

4）约定与不可妥协的底线

用来防止风格漂移和架构被慢慢侵蚀。
可以包括：

命名规范
推荐模式（例如“使用依赖注入”“避免单例”）
错误处理方式
日志规范
“不要做”清单：生成目录、敏感目录、第三方 vendor 代码等

例如：

“不要在 controller 里写业务逻辑。”
“不要修改 /generated 下的文件；用 pnpm codegen 重新生成。”

5）如何验证改动

维护者知道该跑什么命令，把它明确告诉 Claude。
例如：

单测：pnpm test
Lint：pnpm lint
TypeScript 类型检查：pnpm typecheck
本地服务：docker compose up
“集成测试需要 TEST_DB_URL”

这能减少来回沟通，让补丁更可靠。

6）决策记录

如果你们有强约束的架构决策，可以简要写明：

“我们选择 X 而不是 Y 的原因是……”
“我们正在从 REST 迁移到 GraphQL；新接口优先走 GraphQL。”

这能防止 Claude 把你们已经放弃的模式又重新引入。

`.claude/rules`：沉淀专门的领域知识

除了一个全局指南，把更细的、可复用的“规则包”放到 .claude/rules 目录也很有帮助。你可以把它理解为不同领域的操作手册：安全、数据库迁移、UI 约定、性能约束、合规要求等等。
规则的优势在于结构化。你可以把关注点拆开，避免把 CLAUDE.md 变成一本书。
一些很实用的规则文件示例：

.claude/rules/security.md
- “不要记录 PII（个人敏感信息）到日志。”
- “所有用户输入必须用 Zod schema 校验。”
- “只能使用参数化查询。”
.claude/rules/database.md
- “所有 schema 变更都必须有 migration。”
- “对用于过滤的列添加索引。”
- “避免 N+1 查询；使用 join 或批处理。”
.claude/rules/frontend.md
- “使用 /src/ui-kit 的设计系统组件。”
- “不要写 inline style；使用 CSS modules。”
- “无障碍要求：所有表单输入必须有 label。”
.claude/rules/testing.md
- “新功能必须有单元测试。”
- “修 bug 必须补回归测试。”
- “优先写确定性的测试；避免真实网络请求。”