第一次会话：读懂并修改一个现有项目

上一节你已经完成安装、登录并准备好了练习项目。本节我们真正跑通第一次完整会话：先让 Claude Code 只读地读懂一个现有项目，再让它完成一处范围明确的小改动，最后由你审查差异、运行验证并决定是否保留。这一节不追求让代理一次写出复杂功能，重点是把"人指挥 → 代理探索与计划 → 代理改动 → 人审查 → 验证与回滚"这套标准节奏练熟。掌握了这个节奏，后面所有复杂任务都只是把它反复复用。

一、动手前的三项准备

第一次会话务必选一个低风险、可回滚的项目，不要直接拿正在上线的业务仓库练手。开始前依次确认：

1. 项目已纳入 Git 管理。在项目目录执行 git status，确认工作区干净，没有混入未提交的重要改动；这样一旦代理改出问题，可以随时用版本控制回退。
2. 选一个小而完整的项目。优先选择你能看懂技术栈、代码量不大、有启动命令和测试命令的示例仓库；大型 monorepo 留到后面章节再处理。
3. 先约定"只读优先"。第一条指令明确要求代理只阅读、只汇报、不要修改任何文件。新手最容易急于看改动，结果在没理解项目前就接受了跨文件大改，难以审查。

核心原则：前两条消息只做理解与汇报，第三条消息才进入小范围改动。把"探索"和"动手"分开，是控制风险最有效的习惯。

二、启动会话并下达第一条只读指令

在项目根目录打开终端，启动 Claude Code：

claude

会话启动后，先发送一条清晰的只读任务，让它先摸清项目全貌。可以参考下面这条指令，再按你的项目情况补充技术栈与重点目录：

请先通读这个项目，只做只读分析，不要修改任何文件。完成后向我汇报：
1. 项目的用途与主要技术栈；
2. 目录结构与各目录职责；
3. 启动命令、构建命令和测试命令分别是什么；
4. 代码入口文件在哪里；
5. 你阅读过程中注意到的潜在问题或约定。
汇报时引用你实际读过的文件路径。

三、观察代理的探索动作，而不是只看最终回答

发送指令后，不要只盯着最后那段总结。Claude Code 是代理，它会先调用内置工具去实际读取你的项目：列出目录、打开配置文件、查看源码、搜索关键符号。你应当在会话过程中依次观察这些动作：

探索阶段	代理通常会做的动作	你要重点核对什么
了解项目边界	查看目录树、读取 README、package.json / pyproject.toml 等清单文件	它识别出的技术栈与依赖是否和项目一致
定位入口与配置	读取启动脚本、路由配置、环境变量示例文件	它找的入口文件是否正确，有没有看错目录
理解核心源码	按目录逐个阅读模块，追踪函数之间的调用关系	它的理解是否抓住了主干，而不是停留在零散文件
总结与提问	输出结构化汇报，必要时向你澄清不清楚的约束	汇报里引用的路径真实存在，结论能在代码里找到依据

如果它汇报里提到的文件路径与你项目不符，或者对技术栈判断错误，直接在会话里指出，让它重新核对。只读阶段发现理解偏差，成本最低。

四、阅读它的第一份项目汇报

一份合格的只读汇报通常包含：项目用途、技术栈、目录职责、运行与测试命令、入口位置，以及它观察到的约定或风险。拿到汇报后，你用三个问题快速检验可信度：

• 路径是否真实：随机挑一两个被引用的文件，自己打开确认内容与描述一致。
• 命令是否可跑：把汇报里的启动、测试命令对照真实配置核对，避免它凭项目类型猜了一个不存在的命令。
• 判断是否有依据：它说"代码风格统一"或"缺少测试"时，是否真的看过对应目录，而不是泛泛而谈。

确认这份汇报基本可靠后，你对"代理已经理解了什么"心里就有了底，再进入改动阶段会更有把握。

五、下达第一个小改动任务：范围必须收得很窄

第一个改动任务选择小、独立、可验证的类型，例如：补充一个函数的注释、统一一段文案、修复一个明显的格式问题、给某个工具函数补上输入输出说明。不要一开始就要求"重构整个模块"。

一条适合新手的改动指令应当包含四个要素：背景、目标、范围约束、验收标准。示例：

基于你刚才的理解，帮我做一处小改动：
背景：src/utils/format.ts 里的 formatDate 函数目前缺少类型说明和注释。
目标：为该函数补充清晰的 JSDoc 注释，标注参数与返回值类型，不改变现有逻辑。
范围约束：只修改这一个文件，不要调整其他函数，不要重命名、不要引入新依赖。
验收标准：现有行为保持不变；项目测试命令执行后仍然通过；改动只出现在这一个文件的差异里。

把范围约束写进指令，能显著降低代理"顺手优化其他地方"的概率。如果你希望它在动手前先给方案，可以追加一句："先告诉我你打算怎么改，我确认后再开始写文件。"

六、权限确认节点：知道它什么时候要动你的磁盘

当代理准备写入文件、运行终端命令时，会话会出现权限确认提示。此时你需要判断它请求的动作是否符合刚才约定的范围：

1. 写文件：核对准备修改的文件路径，是否就是你指定的那一个；超出范围就拒绝。
2. 运行命令：核对命令内容，确认是读取、构建、测试等低风险操作；涉及安装新依赖、删除文件、推送远端等动作时，保持谨慎。
3. 连续多步动作：逐次确认，不要在没看清命令内容时习惯性全部放行。

七、审查改动：看差异、读说明、跑验证

代理完成改动后，提交给你审查。不要只看它最后说一句"已经完成"，按下面顺序复核：

• 看文件范围：执行 git status，确认被改动的文件数量与你预期一致，没有多出意料之外的文件。
• 逐行看差异：执行 git diff，逐段确认每一处修改确实服务于任务目标，没有夹带重构、改命名或调整逻辑。
• 读代理的改动说明：它通常会列出修改了什么、为什么这样改；对照差异检查说明是否属实。
• 运行验证：执行项目的测试命令；有启动命令的项目，启动后人工确认相关功能正常。验证不通过，就在会话里把报错贴给它继续修正。

八、保留、回滚与提交

审查与验证都通过后，你再决定是否接受这套改动：

# 查看最终改动
git status
git diff

# 确认无误后，按你自己的规范提交
git add .
git commit -m "docs: 补充 formatDate 函数注释与类型说明"

# 如果审查后决定全部放弃，回到改动前状态
git restore .

记住：代理是执行者，提交动作和最终决策始终由你完成。第一轮练习中出现"不满意就整体回滚"是完全正常的，回滚不会影响后续继续使用。

九、一次完整会话的对话节奏示例

轮次	你做的事	代理做的事	你的审查重点
第 1 轮	发送只读通读指令	探索目录与文件，输出项目汇报	路径真实、命令准确、理解无偏差
第 2 轮	澄清汇报中不清楚的点	重新核对文件并补充说明	偏差是否被纠正
第 3 轮	下达带范围与验收标准的小改动任务	先给计划，经确认后写文件	计划与范围一致，写操作逐次授权
第 4 轮	看 diff、跑测试、提出问题	根据反馈继续修正	差异干净、测试通过
第 5 轮	决定保留并提交，或回滚	结束本次会话	最终状态与任务目标一致

十、新手第一次会话的常见误区

• 一上来就要求大改造：范围越大越难审查，第一次务必从单文件、单函数的小改动开始。
• 跳过只读阶段直接改：在代理还没理解项目时改动，容易出现方向性错误。
• 不看 diff 就接受：代理可能在"顺手优化"中改动了你不希望动的代码，差异审查不能省。
• 验证命令没跑就提交：注释类改动风险低，但只要涉及逻辑，测试与启动验证就是必要步骤。
• 会话里堆叠太多无关需求：一个会话聚焦一个明确任务，复杂需求拆成多次会话推进。