Agent 辅助编码的故障很少是「模型突然变笨」，更多是 会话态坏了：目标漂移、上下文噪声、范围失控、验收缺失。继续在同一脏线程里加戏，通常会更贵也更错。
本文给 三类故障剧本------卡住、乱改、漏测：如何命名、如何复现提问、如何裁剪上下文。可与 10-06 委派/夹具文、同日 Aider 文互补。界面文案以当前 Cursor 为准。
先命名，再动刀
| 类型 | 典型症状 | 首问 | 裁剪重点 |
|---|---|---|---|
| 卡住 | 空转、重复计划、不改文件 | 目标与阻塞各一句 | 丢掉长历史与失败方案 |
| 乱改 | 无关文件、大重构、改测试骗绿 | 允许路径列表 | 禁止项写死 |
| 漏测 | 声称完成但无测试/测红 | 要跑的命令 | 只留相关测与失败栈 |
| 混杂 | 以上同时出现 | 先分类 | 新开会话 |
命名本身就是裁剪：你不再对「它不太行」说话，而对「乱改」说话。
复现提问四步
把模糊抱怨变成可执行问句：
- 现象：我看到什么？我期望什么？
- 证据 ：日志、
git diff --stat、失败断言。 - 范围：哪些文件/命令相关？哪些明确无关？
- 请求：下一步只做什么；交付格式（diff / 命令结果）。
模板：
text
【故障类型】乱改
【现象】我要求只改 src/billing.py，但 diff 动到 12 个文件
【证据】git diff --stat 如下......；其中测试被改了断言
【范围】允许：src/billing.py；禁止：tests/** 与格式化
【请求】请基于当前未提交变更，生成回退无关文件的步骤，
并给出仅针对 billing 的最小补丁方案；先不要继续改证据进提示，比「请认真一点」有用。
上下文裁剪法
该留 ：失败断言与栈顶；相关源文件 @；验收命令；明确禁止项；子任务卡字段。
该扔 ：无关成功闲聊；无 @ 的整仓搜索结果；过期错误方案；重复粘贴的全文；上一次失败的半截 diff。
经验规则：新会话 + 精简材料 > 在脏线程里加戏。 需要历史时，用手写 10 行摘要交接，而不是滚动两千行对话。
剧本 A：卡住
识别：多轮只有计划口吻；或反复读同一文件；或工具调用空转。
动作：
- 停。不要再发「继续」。
- 新会话。粘贴：目标一句、非目标一句、已尝试两条、当前阻塞。
- 要求 只输出下一步可执行动作（一条命令或一个文件的最小编辑），禁止长篇架构。
- 若仍卡：把任务拆小（见委派文），先做可红绿的切片。
卡住时常被误诊为「要换更强模型」。先裁上下文与缩范围，再谈换模型。
剧本 B：乱改
识别 ：diff --stat 文件数异常；出现全仓格式化；测试期望被改松。
动作：
git checkout -- <无关路径>或交互式收回（按你的 Git 习惯），先回到安全点。- 新会话，用路径白名单 + 「禁止改测试」强提示（夹具文套路）。
- 要求交付 unified diff ，人工
--stat验收。 - 把白名单写进 Rules 或任务卡，减少重犯。
乱改的根因常是目标动词太虚（「优化」「完善」）。换成可测动名词。
剧本 C：漏测
识别：Agent 说「已完成」但没有跑测试；或只跑了无关测；或生产改了测没动。
动作：
- 你先本地跑目标命令，拿到红/绿真相。
- 若红：走夹具最小 diff 套路。
- 若绿但你不信任：补邻近测或主需求级测，再让 Agent 只读解释。
- 提示词里把验收命令写成 硬门禁：「未粘贴命令结果前不得宣称完成」。
漏测与「测试骗绿」是孪生兄弟：前者不做，后者乱做。合同都是验收命令。
混杂故障
同时卡住又乱改时，不要写超级提示词试图一次性拯救。顺序是：
- Git 回到可述状态（或新分支保存现场）。
- 只选一个类型开新会话。
- 修完再处理下一类型。
收工清单
- 已用一句话命名故障类型
- 新会话只带证据与范围
- 乱改已用路径白名单刹住
- 漏测已用红测命令钉死验收
- 最终 diff 人工扫一眼无越界
- 剧本卡片存入团队库
团队化
把三类模板放进 docs/agent-playbooks/，新人比口口相传更快上手。也可与 PR 模板联动：「Agent 辅助改动请附验收命令输出」。
会话卫生：排障前后的 Git 姿势
- 排障前：
git status/git diff --stat留底，必要时建wip/debug-*分支。 - 乱改后：先回到可述状态，再新会话；不要在半毁工作区上「继续让它修」。
- 排障成功后：原子提交，提交信息写故障类型与验收命令。
Agent 排障与人排障一样，需要可回滚点。没有 Git 卫生，剧本会变成雪上加霜。
提问语气：少形容词，多约束
弱：你怎么又改乱了，认真点。
强：故障类型=乱改。允许文件=...。请列出将回退的路径，等待确认后再继续。
形容词会浪费轮次；约束会改变工具行为。把「生气」翻译成「类型 + 范围 + 交付」，是专业排障。
何时该换模型 / 模式
在裁剪与缩范围之后仍反复空转：可尝试换更强推理模型，或改 Ask 先分析再 Agent 改。但顺序必须是 先剧本后换挡。许多「模型不行」其实是「线程太脏」。
Manual 模式适合：乱改已发生，你只想精细采纳若干行（见 10-05）。
记录模板（可进团队库）
text
日期：
故障类型：卡住 / 乱改 / 漏测
证据：
裁剪动作：
新会话提示词：（附）
结果：--stat / 测试
遗留：两周复盘一次，能看出是 Rules 问题、MCP 过多，还是任务卡质量问题。
与子 Agent 委派的交叉
委派翻车常表现为乱改或漏测。剧本同样适用：对子卡执行「类型命名 → 新会话 → 白名单」。主线程不要吞掉子卡的失败日志------那是最好的证据。
反例：在同一线程里「总结并继续」
模型的总结可能美化失败、丢掉禁止项。排障场景下，总结只适合作为 你手写摘要的素材，不要自动成为下一轮的唯一上下文。你动手写 10 行交接，往往比自动总结更短更准。
三类故障的「第一句话」速查
卡住：故障=卡住。目标=...。阻塞=...。请只给下一步动作。
乱改：故障=乱改。允许=...。禁止=...。先列回退路径，等待确认。
漏测：故障=漏测。验收命令=...。请先跑命令并把输出贴回，再谈改码。
把三句话存成代码片段，排障启动时间可降到一分钟内。
上下文裁剪的量化直觉
经验上，排障新会话材料超过「两屏提示词 + 四个文件」就该再拆。不是硬性标准，但当你开始粘贴整份堆栈五十屏时，模型会在噪声里找故事，而不是找断言。
可用「删掉这段是否影响复现」做刀法：不影响就删。
工具调用空转的专门处理
若 Agent 反复 list/read 同一批文件：
- 明确禁止继续搜索，要求基于已给材料决策；
- 或切换 Ask：「只分析根因，不改文件」；
- 分析可接受后，再 Agent 落地最小 diff。
空转常被误读为「需要更多上下文」；其实更多时候是「需要更少上下文 + 更硬决策」。
案例：漏测伪装成完成
症状：Agent 说「已修复登录」，但仓库测试红。
处理：你跑命令 → 红。新会话，类型=漏测，粘贴红测，走夹具套路。
复盘：原会话是否从未要求粘贴测试输出？是则改任务卡模板，加上硬门禁句。
案例价值在改模板，不在责怪单次模型输出。
案例：乱改来自「优化一下」
症状：顺手重命名、提纯工具函数、改格式。
处理：回退无关 hunk；重开；动词改成可测目标。
复盘：Rules 是否缺「禁止无关格式化」铁律？补上。
把剧本接到每日站会
若团队做 AI 编码站会：昨日是否出现三类故障、各几次、是否已沉淀进剧本库。排障次数下降才是工具实践进步；单纯「用了 Agent」不是。
排障与 Token：为什么裁剪也是省钱
脏线程里的每一次「继续」都会把失败方案、重复栈、无关文件再次送进前缀。排障剧本要求新会话，本质是在砍历史税。若你已读过 Token 观测实战文，可以把「排障新会话次数」也记进个人仪表盘------次数上升不一定坏，说明你在止损；坏的是「同线程硬扛十轮」。
与 MCP 动态加载的交叉故障
工具过多时，卡住与乱改会交叉：Agent 调错工具、或在写工具组开启时「帮忙改远程资源」。排障时额外检查：本轮启用了哪些 MCP 分组？若无关，关掉再问。动态加载习惯文与本剧本是同一枚硬币的两面。
一页纸打印版
正面：三类表 + 三句第一话。背面：复现四步 + 该留该扔。打印贴显示器旁，比再开一篇文档找段落快。工程文化有时就是一张纸的事。
收束前自测
用最近一次真实翻车套剧本走一遍，把提示词与结果贴进团队库。若走不通，改剧本而不是改记忆。剧本是活文档，一月一审足够。
FAQ
Q：新会话会不会丢掉重要上下文？
A：会丢掉噪声，也会丢掉你没摘要的要点------所以要手写 10 行交接。别把「自动长历史」当成记忆可靠。
Q：Ask 模式能排障吗？
A：适合根因分析与方案对比；落地改码仍要 Agent/Manual，并带验收命令。
Q：三种故障同时出现怎么办？
A：Git 回安全点后一次只治疗一种；先乱改（回到可述），再漏测，再卡住。
Q：剧本会不会太死板？
A：死板的是门禁，灵活的是材料。类型命名与新会话是门禁；证据怎么贴可以灵活。
排障能力是团队杠杆：一人会裁剪，全员 Token 与情绪成本下降。把剧本当活文档维护，比追求一次「神级提示词」更接近工程。
附录：交接摘要十行模板
text
1. 故障类型：
2. 用户可见症状：
3. 已验证命令与结果：
4. 关键文件：
5. 已排除假设：
6. 禁止项：
7. 下一步唯一动作：
8. 风险：
9. 回滚点（commit/分支）：
10. 不需要再读的噪声：新会话只贴这十行加证据，通常比粘贴全文对话更有效。与委派卡字段刻意同构，降低脑内切换成本。到此，卡住/乱改/漏测三类剧本已足够你在真实项目里止损；其余优化交给复盘与 Rules 微调。
边界声明
- 不涉及绕过安全、越权或破坏性未授权操作。
- 不同 Cursor 模式（Ask/Agent/Manual）选择见既有决策文；本文聚焦排障提问。
今晚可执行
- 从最近一次翻车会话里挑一例，命名类型。
- 用四步模板新开会话重跑。
- 记录
--stat前后对比，写进团队库。
排障的第一技能不是催更，而是裁剪；第二技能不是换模型，而是写清验收。