3.11 大型代码库处理
预计耗时：15 分钟
本关任务简报
一个真实项目往往有几百甚至几千个文件。Claude 每次启动都是"从零开始"——它不知道你的项目架构、不知道哪个文件负责什么、不知道你们有什么约定。
如果每次都把所有代码都塞进去，token 会爆炸；如果什么都不给，Claude 会乱猜。
这一关讲的是如何让 Claude 在大型项目里工作得像一个真正了解项目的搭档：靠 CLAUDE.md 提供项目地图，靠精准的文件引用控制上下文，靠任务拆分避免单次会话处理过多。
通关奖励：解锁以下技能
- 🗺️ 能用 CLAUDE.md 给 Claude 一份让它快速定向的项目地图
- 🎯 能精准引用文件和目录，而不是把整个项目都丢进去
- ✂️ 掌握大型任务的拆分原则，避免单次会话失控
- 🤖 知道什么时候该用多 Agent 并行处理不同模块
开始前先检查装备
| 前置知识 | 说明 |
|---|---|
| 2.7 CLAUDE.md 配置 → | 这一关的核心工具是 CLAUDE.md，不了解它的基础用法就无法建"项目地图" |
| 2.5 文件引用与上下文 → | @目录/ 引用方式是大型代码库的核心操作 |
机制解析
为什么"把所有文件都给它"行不通
Claude Code 有上下文窗口限制。一个 200 文件、每文件 200 行的项目，总量超过 10 万行代码——这远超单次对话能处理的量。
更重要的是：你也不需要 Claude 看所有文件。大多数任务只涉及项目的某个局部，其余的代码对这个任务没有意义。给得越多，干扰越大，成本越高。
关键原则：给 Claude 刚好够它完成这个任务的上下文，不多也不少。
技术一：CLAUDE.md 作为项目地图
CLAUDE.md 是每次启动都会自动读取的文件。对于大型项目，它最重要的用途之一是告诉 Claude 这个项目的结构：哪个目录放什么、核心模块在哪里、有哪些约定需要遵守。
一个实用的大型项目 CLAUDE.md 模板：
## 项目结构速览
src/
├── api/ # HTTP 路由层，只处理请求/响应，不写业务逻辑
├── services/ # 业务逻辑层，所有核心计算和规则在这里
├── models/ # 数据模型定义（TypeORM Entity）
├── utils/ # 工具函数，必须是纯函数，不能有副作用
└── config/ # 环境配置，从 .env 读取，不硬编码
## 关键文件
- src/app.ts ← 应用入口，路由注册在这里
- src/config/db.ts ← 数据库连接配置
- docs/ADR/ ← 架构决策记录，涉及架构改动前必读
## 约定
- 所有异步函数必须有错误处理，禁止裸 await
- 数据库操作只能在 services/ 层，api/ 不能直接查库
- 新增 API 必须同步更新 docs/api-spec.md有了这份说明，Claude 可以在不读所有代码的情况下理解项目的整体结构，在需要读某个文件之前知道去哪里找。
用 @import 拆分过长的 CLAUDE.md
大型项目的约定一多，CLAUDE.md 容易变得又长又杂。可以把它拆成几个文件，在主 CLAUDE.md 里用 @路径/文件.md 引入，比如写上 @docs/architecture.md、@docs/conventions.md，Claude 会自动把这些文件的内容并进来。拆分后各管一块，维护更清爽。详见 2.7 CLAUDE.md 配置 →。
技术二：精准的文件引用策略
按目录引用，而不是一个个文件列举：
@src/services/payment/ ← 引用整个支付服务目录
请帮我给这个模块添加退款功能。先确认再深入——不确定问题在哪时，先让 Claude 探索：
这个项目里负责用户认证的文件在哪里？
帮我找一下，不需要读完所有文件，先告诉我目录结构。Claude 会用 Glob 和 Grep 搜索，找到相关文件后再精确引用，而不是把整个 src/ 都读一遍。
按关键词定位：
@src/ ← 只扫描目录结构
搜索 src/ 下所有涉及"payment"的文件，列出来。技术三：大型任务的拆分原则
遇到"重构整个认证模块"这类大任务，不要一次性丢给 Claude。按以下原则拆：
按文件/模块拆：
任务：重构认证模块
拆法：
会话1：重构 auth.service.ts（核心逻辑）
会话2：更新 auth.controller.ts（适配新接口）
会话3：更新测试文件
会话4：更新文档按依赖顺序拆：先改被依赖的底层，再改上层。每个会话结束时确认改动没有破坏已有功能，再开下一个会话。
把跨会话的状态记在 CLAUDE.md 里：每完成一个阶段，更新 CLAUDE.md 里的"当前状态"或"重构进度"，下一个会话启动时 Claude 能接续上下文。
技术四：用多 Agent 并行探索
当你需要同时了解项目几个不相关的模块时，多 Agent 比顺序探索更快：
我需要在这个项目里同时了解两件事：
1. 当前的日志系统是如何工作的
2. 当前的错误处理策略是什么
请并行处理这两个问题，分别探索对应的代码，给我各自的分析报告。Claude 会启动两个子 Agent 分别探索，比你先问日志再问错误处理快得多。
技术五：了解 Claude Code 处理大型任务的上限
Claude Code 对单次任务的处理是有边界的：
- 上下文窗口：当前主流模型约 200K token，一个中等规模项目的核心文件会逼近这个边界
- 工具调用轮次：单次会话里 Claude 的工具调用次数有上限，超过后它会停下来说"任务太大了"
- 注意力漂移：上下文越接近满载，Claude 越容易"忘记"早期的约定或出现前后矛盾
处理超大型任务的原则：不要试图让 Claude 在一次会话里吃完整头大象——按模块拆分后，每个会话只处理一个边界清晰的子任务，完成后提交 git，再开新会话处理下一段。CLAUDE.md 里记录跨会话的进度状态，让每次新会话都能快速接续上下文。
技术六：用 /compact 保持长会话活力
在长时间的大型项目工作中，/compact 比 /clear 更合适：
/compact压缩后 Claude 保留对当前工作状态的记忆，同时释放大量 token 空间。当你感觉 Claude 开始忘东忘西、或者响应变慢，就是该 /compact 的时候了。
想知道当前上下文被什么占满了，先用 /context 看一眼——它会列出上下文窗口里各部分（系统提示、CLAUDE.md、文件、对话历史等）各占多少，帮你判断是该 /compact、还是该精简引用的文件。
开始闯关
目标：给你的项目写一份"地图级" CLAUDE.md，验证它能帮 Claude 快速定向。
第 1 步：分析项目结构
在当前项目目录运行：
帮我分析这个项目的目录结构，总结各主要目录的职责，输出一个 3-5 行的结构说明。第 2 步：把说明写进 CLAUDE.md
把 Claude 输出的结构说明整理后加入 CLAUDE.md 的开头。可以直接告诉 Claude：
把刚才的结构说明格式化后，追加写入当前目录的 CLAUDE.md 文件。第 3 步：验证地图效果
新开一个会话（/clear），然后问：
如果我想修改用户登录的验证逻辑，应该从哪个文件开始看？如果 Claude 能直接给出具体文件路径而不是让你"自己找找看"，说明 CLAUDE.md 地图生效了。
通关检定
- [ ] 知道为什么不能把整个项目都塞给 Claude
- [ ] CLAUDE.md 里包含了项目结构说明和关键文件索引
- [ ] 能用
@目录/按模块引用，而不是逐文件手动列举 - [ ] 知道大型任务应该按模块/依赖顺序拆成多个会话
- [ ] 理解 /compact 在长会话中的价值
全部点亮就算通关 ✓
卡关了？翻车指南在这
每次新会话 Claude 都要重新探索项目结构，很耗时间
根本原因：CLAUDE.md 里没有写清楚结构。把最常被问到的"这个功能在哪个文件"逐一加进 CLAUDE.md 的关键文件列表——问一次，记一次，之后就不用重复了。
Claude 读了很多文件但最后给出的答案还是不对
上下文太多时，Claude 容易在信息里"迷路"。试试反过来：先让 Claude 提出它的诊断假设，再针对假设精确引用对应的文件去验证，而不是一次性给它十几个文件。
跨模块的改动怎么安全进行
在正式改动前，让 Claude 先做依赖分析：
@src/models/user.ts
如果我修改这个文件里的 User 接口，哪些其他文件会受影响？列出来。然后按影响范围从小到大逐步改，每步提交一次 git，保留回滚点。
下一关
结构化的项目管理之外，还有一层更本质的问题：如何跟 Claude 沟通才能稳定拿到高质量的输出？下一关讲任务拆解和提示词设计的核心方法论。