10 · 场景手册：从「能用」到「用对」

前面讲原则，这篇讲 具体场景里怎么做。
默认假设：你已经有 L1–L2 工具（IDE/CLI Agent），仓库有基本测试或至少能跑起来。

用法：按场景抄流程；把翻车点回写进团队规范。

0. 所有场景共用的 60 秒开场

动手前先写（可以很短）：

目标：
非目标：
验收：
红线：（不可改的模块 / 不可碰的数据 / 不可推远程）
入口：（关键文件、错误日志、相关 issue）

再让 AI 先复述理解，你纠正一次，再批准动手。
这一步省掉的返工，通常大于「直接生成」省下的时间。

1. 修 Bug（最常见、最该练）

适合 AI 的部分

根据堆栈缩小候选文件
提出 2–3 个假说并排序
起草复现脚本与回归测试
在明确根因后改代码

不适合交给它独自完成的部分

判断「这是不是真正的用户问题」
在无日志时瞎猜生产环境行为
为了让测试绿而改断言（掩盖 bug）

翻车样例

模型「修好了」本地，生产仍挂：缺真实数据形态
测试被改成迁就错误实现
顺手重构半个模块，review 变成考古

口令

先锁定失败，再允许修改。

2. 加小功能（边界清晰）

例如：加一个 API 字段、一个设置项、一个后台筛选。

关键约束要先说死

是否允许新依赖
是否允许改 DB schema（迁移怎么做）
错误码/文案是否有规范
权限模型是否已有现成中间件

何时该停手改设计

AI 开始：

复制粘贴三处相似逻辑却不肯抽
或反过来过度抽象「通用框架」

→ 停，人定边界，再继续。

3. 中等功能 / 跨模块改动

例如：新登录方式、通知渠道、计费项。

不要一句话：「帮我把 XX 做完」

拆成可代理单元：

切片	产出	验收
设计草案	接口与数据流一页纸	人拍板
骨架	类型/接口/空实现	能编译
主路径	快乐路径可跑	e2e 或手动脚本
失败路径	权限/超时/重试	测试锁定
观测	日志/指标/审计字段	能排查
文档与开关	README/flag	可灰度

每片单独会话或明确阶段，避免上下文腐坏。

人必须亲自盯的点

数据模型一旦写错，后面全是债
权限与多租户边界
对外契约（API/事件）的向后兼容
回滚策略

4. 重构（AI 很能写，也很能搞砸）

好重构任务

重命名与机械搬迁
按已有模式消除重复
补测试后再挪实现
在类型/测试保护下的内部拆分

坏重构任务（先别扔给 AI）

「把这个模块变得干净一点」——无验收
无测试的核心域大挪移
同时换架构风格 + 加功能

口令

没有行为锁的重构，是在用自信换运气。

5. 测试补全与「让 CI 变可信」

高价值用法

从 bug 反推回归测试
为纯函数/解析器生成边界用例
把手动复现脚本固化成 CI 步骤
识别「断言过弱」的测试并收紧

要警惕

生成一堆只测 mock 交互、不测业务不变量的测试
为了覆盖率数字而测私有实现细节
把 flake 用 sleep/重试「糊绿」

验收标准（给人看的）

删掉实现中的关键一行，测试是否会红？
测试名字是否描述业务行为？
是否依赖真实时间/网络而未隔离？

6. Code Review 辅助

适合

总结 diff 意图与风险面
列出未覆盖的边界条件清单
对照 checklist 做第一轮扫描
解释陌生模块给评审者

不适合

让模型「LGTM」代替人的责任
只根据 commit message 臆测正确性
在没跑测试/预览时宣称安全

实用提示

你是对抗式评审者。默认假设有缺陷。
只基于 diff 与我提供的上下文。
按：正确性 / 安全 / 数据 / 可维护 / 测试缺口 分组。
每条指出具体文件与可疑逻辑，不要空泛表扬。

人仍要抽查：权限、钱、删除、并发、兼容。

7. 事故 / 值班（高风险）

AI 可以

协助解读日志与时间线
提出排查树
起草对外状态页文案（人改）
事故后整理时间线草稿

AI 不可以（默认）

直接在生产执行修复
自动扩缩容/改 DNS/清数据
在证据不足时「先试试重启」式建议被直接执行

建议协议

人声明：当前是事故模式，只读分析
AI 给排查步骤与命令建议
人在受控环境执行
修复方案双人确认
事后把「模型误导过的假说」记进复盘

8. 遗留系统摸底

流程

让 AI 画：模块图、入口、数据存储、外部依赖（标注不确定）
人用运行与老人核对「哪里是真的」
建立「神圣模块」与「可动模块」名单
先加表征测试/日志，再谈改造
所有结论写回 ARCHITECTURE.md / ADR

价值

把「人口头传统」变成 人和模型都能用的上下文资产。

9. Greenfield / 从 0 到 1

AI 极强的阶段

脚手架、目录、CI 模板
标准鉴权/CRUD 样板
多种 API 设计草稿对比

人必须先定的

问题是否值得做
核心用户路径是什么
非功能：一致性、多租户、审计、成本
什么不要做（范围杀手）

建议节奏

人：一页产品+技术约束
AI：2–3 个架构草案（含否决理由）
人：选一个，写死边界
AI：垂直切片（端到端一条路径）
人：真用一遍，再扩展
尽早加：lint、测试、权限、基础观测

反模式： 连续三天「继续完善」却从未有可演示路径。

10. 文档、迁移说明、RFC 草稿

好用法

从代码生成「现状描述」再由人改成「目标描述」
把讨论纪要收成 ADR 草稿
迁移 runbook：步骤、回滚、校验 SQL

硬规则

文档中的命令与旗标必须可核对
架构决策必须有人签名（作者字段是人）
「AI 写的文档」若无人读过，等于没有

11. 多代理 / 并行任务（进阶）

当工具支持子代理、worktree、并行会话时：

模式	用法	注意
探索并行	多假说同时查	汇合后人裁决
实现/评审分离	一个写、一个专门找茬	避免同一上下文自嗨
按文件/子系统拆	大迁移分区改	接口契约先冻结
长任务 babysit	CI 修、依赖升级	权限收紧 + 预算上限

纪律

并行不是目标，汇合点的质量才是
每个代理要有独立验收，不要「大家一起变好」
共享可变状态（同分支狂改）是混乱之源 → 用分支/worktree

12. 「不该用 AI」的清单（省时间）

你 2 分钟能改完且完全清楚的一行
需要人际谈判才能定的产品取舍
无任何反馈环的纯猜测生产状态
涉及不可逆数据且你还没理解影响面
你准备用来学习基本语法的练习（用，但要关掉自动完成去想）

13. 场景 × 风险速查

场景	默认风险	最低门禁
修 bug	假修复	失败测试先红后绿
小功能	风格分裂	复用现有模式 + 评审
跨模块	契约破坏	分阶段 + 兼容测试
重构	行为漂移	行为锁 + 小 diff
补测试	虚假安全感	「破坏实现应失败」抽检
评审	责任外包	人终审关键路径
事故	误操作放大	只读分析，执行权人工
遗留摸底	自信的错图	人与运行时核对
0→1	范围爆炸	先一条垂直路径
多代理	汇合灾难	契约冻结 + 隔离分支

14. 把场景沉淀成团队资产

每次重复场景成功或翻车后，更新：

仓库 CLAUDE.md / 说明里的「常见任务怎么做」
提示模板库（修 bug / 加字段 / 重构…）
禁止事项（本仓库特有）
评审 checklist 的一条新项

个人会用，是技能；团队可复制，是能力。

上一篇：X/社区热度参考
下一篇：误区与常见反对意见