上周我接手了一个 15 万行的遗留项目，打开 VS Code 的那一刻我差点崩溃——200 多个文件，层层嵌套的目录结构，还有那种"我也不知道干嘛用但千万别删"的神秘文件夹。

更绝望的是，我需要用 Claude Code 帮我重构核心模块。

说实话，第一次尝试惨不忍睹。Claude Code 给出的方案完全忽略了项目的依赖关系，改完一个文件，另外五个文件报错。我花了整整一个下午在"改错-报错-再改错"的死循环里打转。

后来我摸索出了一套策略，现在处理这种大项目，效率至少提升了 3 倍。

为什么 Claude Code 处理大代码库会"翻车"

先说一个大多数人不了解的事实：Claude Code 的上下文窗口不是无限的。

很多人以为把整个项目扔给 Claude Code，它就能"秒懂"一切。但实际情况是，当你一次性读取太多文件，模型会"稀释"关键信息。说人话就是：给的信息越多，关键信息被淹没得越厉害。

这就像你让一个人同时看 100 本书，然后问他第 37 本第 52 页讲了什么——他大概率答不上来，不是能力不行，是信息过载了。

Claude Code 处理大型代码库的核心挑战有三个：

1. 上下文污染：无关代码干扰关键逻辑的识别

2. 依赖盲区：改动一处，其他地方跟着炸

3. token 爆炸：还没聊几句，上下文就满了

策略一：分层读取，先骨架后血肉

这是我最常用的策略，适用于任何规模的项目。

核心思路：不要一上来就读具体实现，先建立项目的"认知骨架"。

具体操作步骤

第一步：只读目录结构

# 用 tree 命令快速了解项目结构（限制层级）
tree -L 2 -d

这一步的目的是搞清楚项目的模块划分。比如一个典型的 Next.js 项目可能是这样的：

src/
├── app/          # 路由和页面
├── components/   # 组件库
├── lib/          # 工具函数
├── hooks/        # 自定义 hooks
└── types/        # 类型定义

第二步：读取入口文件和配置文件

Prompt 示例：读取 package.json、tsconfig.json 和 src/app 目录下的 layout.tsx，帮我理解这个项目的技术栈和架构

这一步你只需要让 Claude Code 知道：这是什么框架？用了哪些核心依赖？入口在哪里？

第三步：按需深挖，而不是全量读取

很多人犯的错误是这一步：

# 错误示范：一次性读取所有文件
find src -name "*.tsx" -exec cat {} \;

这会把几万行代码一次性塞进上下文，效果极差。

正确的做法是用 Grep 工具定向搜索：

Prompt 示例：在 src/components 目录下搜索所有使用了 "useAuth" 的文件，我需要了解认证相关的组件有哪些

这个策略的精髓：让 Claude Code 像"探照灯"一样工作，而不是像"泛光灯"。

策略二：建立依赖地图，避免改一处炸一片

这个策略我踩过很大的坑。

有一次我重构了一个工具函数，觉得改动很小，没做依赖检查。结果这个函数被 17 个地方引用，其中 3 个是关键业务逻辑。上线后直接炸了两个核心功能。

从那以后，我养成了一个习惯：改动任何函数之前，先问 Claude Code"谁在用它"。

具体操作方法

Prompt 示例：搜索项目中所有调用 formatCurrency 函数的地方，列出文件名和具体用法

Claude Code 会用 Grep 工具快速定位所有引用：

// src/lib/format.ts - 定义处
export function formatCurrency(amount: number, currency: string): string

// src/components/PriceTag.tsx - 引用处
formatCurrency(price, 'USD')

// src/pages/order.tsx - 引用处
formatCurrency(order.total, order.currency)

看到这些引用之后，你再决定怎么改，心里就有数了。

进阶技巧：对于复杂的改动，我会让 Claude Code 生成一个"影响范围报告"：

Prompt 示例：我要修改 formatCurrency 函数，增加一个可选参数 locale。请分析这个改动会影响哪些文件，每个文件需要如何调整

这样你能在动手之前，就把所有需要改的地方列出来，逐一确认。

策略三：分模块隔离，一次只做一件事

大项目最忌讳"贪多嚼不烂"。

我现在的做法是把大任务拆成独立的子任务，每个子任务只涉及一个模块。完成一个，验证一个，再进行下一个。

具体操作流程

假设你要重构一个电商项目的购物车模块，可以这么拆分：

阶段一：只读购物车相关文件

Prompt 示例：只读取 src/features/cart 目录下的所有文件，帮我理解购物车的数据结构和核心逻辑

阶段二：独立重构，不动其他模块

Prompt 示例：基于刚才读取的内容，重构 cartStore.ts，把状态管理从 useState 迁移到 zustand。注意：不要改动其他模块的代码

阶段三：验证改动

Prompt 示例：检查购物车模块的改动是否影响了订单模块（src/features/order），特别是购物车提交订单的接口

阶段四：继续下一个模块

这样做的好处是：每个阶段上下文都很干净，Claude Code 的理解质量高，出错概率低。

策略四：用 CLAUDE.md 给 Claude Code 写"说明书"

这是我最近半年发现的最实用的技巧。

在项目根目录创建一个 CLAUDE.md 文件，把项目的关键信息写进去：

# 项目说明

## 技术栈
- Next.js 14 (App Router)
- TypeScript 5
- Tailwind CSS
- Prisma + PostgreSQL

## 目录结构
- src/app: 路由页面
- src/components: 组件库
- src/lib: 工具函数
- src/hooks: 自定义 hooks

## 编码规范
- 组件用 PascalCase，文件用 kebab-case
- 所有 API 调用都要放在 src/lib/api 目录
- 不要使用 any，优先用 unknown + 类型守卫

## 关键文件
- src/lib/auth.ts: 认证核心逻辑
- src/lib/db.ts: 数据库连接

为什么这个文件很重要？

每次启动 Claude Code，它会自动读取这个文件。等于你给 Claude Code 发了一份"项目说明书"，它从一开始就知道项目的基本信息，不需要你再重复解释。

我发现加了 CLAUDE.md 之后，Claude Code 的代码风格一致性明显提升了，不再问一些基础问题，直接进入正题。

我踩过的两个大坑

坑一：相信"全部读取"能解决一切问题

我刚用 Claude Code 的时候，觉得上下文越大越好。有一次我让 Claude Code 读取了整个 src 目录的所有文件，大概 3 万行代码。

结果呢？它给我的代码建议非常泛泛，没什么针对性。我问它"帮我优化 auth.ts"，它给的方案完全是通用的，根本没考虑项目里已有的认证流程。

原因：上下文太大，关键信息被稀释了。

解决：只读取当前任务相关的文件，控制在 10-20 个文件以内。

坑二：改完不验证，直接下一个任务

这个坑让我在线上环境丢过人。

当时我用 Claude Code 重构了一个支付模块，本地跑了一下没问题，就直接提交了。结果上线后发现，另一个模块调用了支付模块的一个废弃接口，直接 500 错误。

原因：我只验证了改动的地方，没检查依赖它的地方。

解决：改动任何模块之后，用 Grep 搜索所有引用它的地方，逐一确认是否有影响。

总结

处理大型代码库，核心原则就一句话：让 Claude Code 做"精确打击"，而不是"地毯式轰炸"。

具体来说：

1. 分层读取：先目录结构，再入口文件，最后按需深挖

2. 依赖地图：改动之前，先问"谁在用它"

3. 分模块隔离：一次只做一个模块，做完验证再做下一个

4. CLAUDE.md：给 Claude Code 一份项目说明书

这些策略的本质是：主动管理上下文，而不是被动接受信息过载。

---

你在用 Claude Code 处理大型项目时，遇到过最头疼的问题是什么？是上下文溢出、依赖爆炸，还是其他坑？欢迎在评论区聊聊你的经历。