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