真实 Coding 任务的风险不只在“代码写错”，还包括误改用户未提交内容、运行危险命令、升级无关依赖、测试覆盖不足和把本地密钥带进结果。
先建立可回滚基线
开始前：
- 查看 Git 状态，处理已有未提交改动。
- 创建独立分支或工作副本。
- 记录当前构建和测试结果。
- 确认
.env、密钥和生产配置不会进入上下文。 - 只把目标仓库设为工作区。
基线已经失败时，要先记录原有失败，避免把它误算成本次修改回归。
用 Ask 建立项目地图
要求 WorkBuddy 只读并回答：
- 技术栈、入口和目录职责。
- 与需求相关的调用链。
- 现有测试、类型和格式化工具。
- 可能受影响的文件。
- 配置、数据迁移和兼容风险。
让它引用具体文件路径和符号，而不是只给通用架构描述。
把需求改写成验收条件
“修复搜索”不够。写成：
当用户在教程索引输入 WorkBuddy 并选择“应用”意图时，
只显示 agent=workbuddy 且 intent=应用 的条目；
刷新、后退和分享 URL 后筛选状态保持；
空结果显示可恢复入口；桌面和 390px 移动端无横向溢出。验收条件决定需要哪些测试，也限制 Agent 不去修改无关区域。
使用 Plan 审查修改范围
计划应列出：
- 准备修改的文件和原因。
- 不会修改的相邻模块。
- 数据和组件接口变化。
- 新增或更新的测试。
- 运行命令及风险。
- 回滚方式。
拒绝“顺便重构”“统一升级依赖”等无关工作。跨模块修改可以拆成多个独立步骤。
执行小而完整的改动
确认计划后再用 Craft。任务中明确禁止：
- 删除用户未提交改动。
- 执行
reset --hard、清库或生产部署。 - 修改工作区外文件。
- 自动提交或推送。
- 把密钥写入代码和日志。
每完成一个逻辑单元就运行相关测试，不必等所有文件都改完。
通过右侧边栏检查变更
右侧“变更”可以快速查看新增、删除和修改，但仍建议用项目原生 Diff 工具复核。重点看：
- 是否出现计划之外的文件。
- 错误处理和边界条件是否保留。
- 是否增加硬编码路径、密钥或调试日志。
- 依赖文件变化是否必要。
- 测试是否真正覆盖新行为。
行数少不等于风险低，权限和数据逻辑的一个条件变化也可能影响很大。
按层运行验证
推荐顺序：
- 格式化和静态检查。
- 与修改模块直接相关的单元测试。
- 类型检查或构建。
- 更广的测试套件。
- 关键用户路径手工或 E2E 验证。
记录实际命令、退出码和失败摘要。不要只接受“应该可以”。
处理测试失败
先区分是基线已有、环境问题、测试过时还是代码回归。一次只修复与当前变更相关的失败；不要为了全绿删除断言或跳过测试。
依赖网络、账号或外部服务时，明确哪些验证无法在本地完成，并给出生产前检查。
交付前写 Diff 摘要
摘要包含：
- 用户可见行为变化。
- 修改文件和核心实现。
- 已运行测试及结果。
- 未运行的测试与原因。
- 数据、兼容和安全风险。
- 回滚步骤。
让审阅者不看完整对话也能理解改动。
完成检查
- 已有工作区状态和测试基线有记录。
- 需求被改写为可验证条件。
- 实际修改未超出确认计划。
- Diff、测试和关键路径都经过检查。
- 未验证项和回滚方式明确交付。