用 Claude Code 快速读懂陌生项目

假设你接手了一个待办页面的小项目，让 Claude Code 帮你看看“添加任务”是怎么实现的。它找到三个文件，连出一条流程：点击按钮，读取输入，更新内存里的数组，再渲染列表。你顺口一问：“刷新页面后，任务还在吗？”它也给出了肯定的回答。

可这三个文件里，没有任何写入磁盘或数据库的代码。“刷新后保留”这一段，根本没有证据。

接手旧项目、新团队代码或陌生模块时，这类缺口最危险。直接加功能、修 bug，可能改错文件，也可能局部修好了，却破坏了原有约定。问题往往出在把“有几个文件名”当成了“看懂了项目”。

更稳的做法，是先让 Claude Code 只读调查，把项目画成四层地图，每一层都要有文件依据：

• 项目概览：它做什么、面向谁、属于什么类型；
• 结构地图：目录和关键文件各管什么；
• 核心流程：一个功能从入口到结果经过哪些模块；
• 行动判断：可以从哪里开始改，哪里先别碰。

这段调查由它来做，依据由你来核对。流程里每条箭头都对应到具体代码，缺在哪里就记哪里待查，下一步选修改位置时才不会踩空。

01 修改前先理解项目

调查之后，你应该能说清项目做什么、用了什么技术，文件怎样组织、主要功能怎样运行。运行和测试方式、风险区域、候选小任务，也都要有依据。这段调查做好了，下一步才容易选对修改位置。

接手陌生代码时，先确认用途、入口、模块关系和检查方法。官方的常用工作流里，第一组示例就是“理解新代码库”：先要一份整体概览，再逐步追问具体模块。让 Claude Code 帮忙做这段只读调查，你来核对它找到的依据。

如果你还没做过第一次会话，可以先看首次启动时的只读调查：确认目录、权限模式和回答依据，是画地图的前提。

Claude Code 的运行机制说明把工作分为收集上下文、采取行动和验证结果；只问代码库问题时，可以停留在收集上下文这一阶段。

02 项目地图的四层

把项目理解拆成四层，每一层回答一个不同的问题：

项目概览：这个项目大概做什么，面向谁，属于什么类型
结构地图：目录和关键文件分别负责什么
核心流程：一个功能从入口到结果经过哪些模块
行动判断：我能从哪里开始改，哪里暂时不要动

最后一层要把前三层用于具体判断：可能改哪个文件，影响哪里，用什么方法检查。只有概览和目录名，还撑不起下一步计划。

可以拿“这是一个 Web 应用”试着对照这四层。它只说了大致类型，离决定怎么改还有距离。接着追问依据、主入口和源码目录，再查核心流程、测试方式与风险区域，地图才逐渐完整。

03 用导览请求开场

先把任务限定为项目导览，让 Claude Code 知道当前只需解释，不进入修改。

可以这样开场：

请只读调查：不修改文件、不安装依赖、不启动服务或执行项目脚本，
也不读取密钥和私人资料。

你现在的任务是帮我读懂这个项目，暂时不要写代码。
请像一位耐心的项目导览员一样，先建立项目地图，再回答我的问题。
每个判断请尽量说明依据来自哪些文件或目录。

“导览员”说明了当前的任务。具体要求还得写清：只读、建立地图、给出文件依据。这样，你才好区分项目事实和推测。

接着问项目概览：

请先给我一个项目概览：
1. 这个项目主要做什么？
2. 它大概属于哪类项目？
3. 它可能面向什么用户或使用场景？
4. 你是根据哪些文件判断的？

最后一个问题把结论和项目文件连起来，方便你逐项核对。

04 目录地图：它怎样组织

项目概览回答“它是什么”，目录地图接着回答“它怎样组织”。可以继续问：

请帮我建立这个项目的目录地图。

要求：
1. 只解释主要目录，不要逐个解释所有文件
2. 每个目录说明它负责什么
3. 标出新手应该优先看的目录
4. 标出暂时不建议新手修改的目录
5. 如果有不确定的地方，请明确说“不确定”

目录地图先覆盖主干，再按任务深入。逐个罗列文件会淹没模块职责；与当前问题无关的文档或构建产物，可以暂不展开。

一般要重点识别这些位置：

这张目录地图能帮你找到任务的起点。改页面文案先找组件，理解登录要追踪路由、表单、接口和认证逻辑，补测试先看现有测试目录与写法。

05 顺着一个流程走一遍

目录地图有了，文件之间怎么配合却还不一定清楚。接下来选一个具体流程，比如创建待办或提交表单，顺着它走一遍：从哪里触发，谁来处理，状态怎样改变，最后输出什么。

可以这样问：

请帮我追踪这个项目中的一个核心流程：[写出流程名称]。

请回答：
1. 用户或程序从哪里触发这个流程？
2. 这个流程经过哪些文件和函数？
3. 每一步大概做什么？
4. 数据在这些步骤之间如何传递？
5. 如果我要修改这个流程，最可能涉及哪些文件？
6. 哪些地方风险较高，不建议新手直接改？

流程追踪要核对事件、调用和数据传递，光记文件名不够。每段关系都有代码依据，才能判断修改会不会影响后续行为。

回到开头那个假设的待办页面。找到三个文件后，还得看里面的代码能说明什么：

读到这些代码后，就能连出这条流程：

点击按钮 → 读取输入 → 更新内存数组 → 渲染列表

这里还没有磁盘或数据库写入的证据，“刷新后任务仍会保留”需要另查。如果 main.js 只是导入 addTask、没有调用它，点击和添加任务之间也还缺一段。每条箭头都要找到对应的代码行为，缺在哪里，就把哪里记为待查。

06 找到运行和验证入口

修改前先查运行和验证入口，计划才有明确的检查办法。本轮只定位配置与脚本，不执行命令；找不到或读不清实际作用时，记录待确认内容。

可以这样问：

请根据项目文件，帮我判断这个项目可能有哪些运行、测试、构建和检查命令。

请按下面格式回答：
1. 启动开发环境的命令
2. 运行测试的命令
3. 构建项目的命令
4. 代码格式化或 lint 命令
5. 你判断这些命令的依据来自哪些文件
6. 哪些命令你不确定，不能直接执行

找到命令后，先读它会执行哪些脚本，本轮只做调查。即使名字叫 test，也可能连接外部服务，安全与否要看实际动作。

JavaScript 项目可以先查 package.json；Python 项目可以查 pyproject.toml、requirements.txt、pytest.ini；有些项目用 Makefile。根据实际文件判断，把命令和来源一起记下，并注明“尚未执行”。之后获准运行时，再根据实际结果验证。

07 从地图里筛出第一批任务

项目地图最终要支持行动。第一批任务用四个条件筛选：

范围小
风险低
结果可见
容易验证

可以让 Claude Code 基于项目理解推荐任务：

请基于你刚才对项目的理解，推荐 5 个适合新手练习的任务。

要求：
1. 每个任务改动范围小，最好只涉及 1 到 3 个文件
2. 不涉及数据库迁移、支付、权限、部署、密钥等高风险区域
3. 每个任务说明可能修改哪些文件
4. 每个任务说明如何验证
5. 请按“最适合新手”到“稍微有挑战”排序

适合新手的任务通常包括修改页面文案、更新 README、补充一个简单测试、调整低风险样式、为已有函数增加边界情况处理、修复一个可稳定复现的小 bug。

重构认证模块、修改数据库结构、改支付逻辑、调整生产部署脚本、删除大量旧代码、跨多个子系统的大改动，留到以后再做。

文件数量只是线索，风险还要单独判断：少量文件也可能涉及认证或支付。先选能看清影响、能够验证和恢复的任务。选好之后，下一步是让它先写计划，由你来审。

08 整理成项目理解笔记

把调查结果整理成一份简短的项目理解笔记，连接文件依据、流程关系、检查方式与候选任务，供后续计划回查：

完成后，先核对结论是否有文件依据、流程关系是否连贯，再检查命令的来源和执行状态是否清楚、候选任务是否可检查。缺证据的地方标成待确认，就像那条“刷新后保留”的箭头，先空着，等找到代码再连上。