首个项目实操清单与常见误区

本节是第 3 章的实操收口：把"把任务讲清楚"和"审查改动"整合成一份新手可逐步照做的清单，包含开工前准备、标准执行节奏、完整时间线、高频误区对照表和验收自检表。建议在一个干净的真实小项目上按顺序演练一遍，形成肌肉记忆。

一、开工前准备清单

• 确认工作目录正确：先 cd 到目标项目根目录再启动，避免在错误目录里让代理读取无关文件。
• 确认工作区干净：用 git status 查看，避免把本次改动和之前未保存的工作混在一起难以审查。
• 先体检环境：会话内运行 /doctor，确认安装、登录与配置无明显异常。
• 选定权限模式：陌生项目或敏感代码先留在 Manual（默认）；熟悉后再考虑 acceptEdits，不使用绕过模式处理本机日常工作。
• 准备一份项目记忆雏形：可先运行 /init 生成起始 CLAUDE.md，后续再人工补充技术栈、构建命令与约定（第 4 章专讲）。
• 想好一个小而明确的首个任务：目标控制在"单模块、可测试、半小时内可验证"，不要一上来挑战大型重构。

二、标准执行节奏（六步循环）

步骤	动作	完成标志
1. 交代任务	按背景/目标/范围/动作/验收五要素写清楚	任务边界与完成标准明确
2. 先行计划	进入 /plan 让代理阅读代码、产出修改方案	方案经你确认，列出改动文件
3. 小步实现	确认方案后动手，一次聚焦一个可验证目标	产出首轮改动
4. 审查范围与内容	/diff + git status + 逐行阅读关键 diff	确认无越界、无误删
5. 运行验证	跑测试、类型检查、构建，复现目标行为	验证全绿、行为符合验收
6. 收尾或继续迭代	接受合格改动；不合格则把失败信息反馈回去继续修	目标达成或进入下一轮修正

三、可照抄的端到端时间线（以"补一个边界处理 + 测试"小任务为例）

1. 进入项目目录，运行 claude 启动会话。
2. 运行 /doctor 确认环境，运行 /init 生成项目记忆起点。
3. 用五要素结构输入任务，明确"先出方案、暂不改代码"。
4. 用 /plan 观察代理列出的文件与思路，补充排除项和验收标准。
5. 方案确认后让代理开始实现；必要时在 acceptEdits 与手动模式间切换以平衡效率与可控性。
6. 实现完成后运行 /diff 看改动范围，配合 git diff --stat 判断规模。
7. 逐条阅读关键 diff，重点检查边界条件、导出签名与新增依赖。
8. 执行项目的测试与构建命令，把任何失败输出贴回让代理修复直至全绿。
9. 手动复现目标场景确认行为正确。
10. 确认无误后按团队规范整理提交信息；本轮若上下文较长，结束前可 /compact 或 /clear 准备下一任务。

四、新手高频误区对照表

误区	后果	正确做法
一上来就要求"大重构"	改动巨大、风险高、无法快速验证	先用小任务练手，再逐步扩大范围
跳过计划直接接受实现	方案未经对齐，容易方向性返工	中等任务先走 /plan 方案确认
只看总结不看 diff	漏掉越界修改和误删代码	范围核对 + 关键行阅读不可省
不跑测试就标记完成	引入回归错误却不自知	测试/构建全绿才进入下一步
一个会话塞多个无关任务	上下文混杂、审查困难	单一主线，完成一个再 /clear 切下一个
遇到模糊处让代理自行决定	关键选型偏离团队约束	用澄清对话明确技术与兼容性约束
在敏感/生产目录使用宽松权限模式	误操作风险高	敏感代码坚持逐条确认或计划先行
把密钥直接贴进提示词	敏感信息进入对话上下文	凭据走环境变量或受保护配置，不粘贴明文
上下文变冗长仍硬撑长会话	响应变慢、细节被压缩丢失	及时 /compact 或换会话并依赖 CLAUDE.md 续接
改动失败反复接受又推翻	工作区混乱、回退困难	先回到干净状态，明确失败原因后再动手

五、完成前验收自检表

• □ 改动文件都在约定范围内，无意外无关修改。
• □ 目标行为已实现并手动复现正确。
• □ 单元测试/集成测试全部通过，无新增回归。
• □ 类型检查与构建（如适用）通过。
• □ 边界与异常输入处理清楚，导出签名与兼容性要求未被破坏。
• □ 未写入任何密钥、令牌或硬编码环境特定值。
• □ 关键决策与排除项已在对话中确认并记录必要约定。
• □ 已按团队规范准备提交说明或明确暂不提交的理由。