前阵子我在折腾AI辅助编程的工作流一直用SKILL的方式来约束模型输出结果遇到一个特别磨人的问题SKILL写了要求也列清楚了AI生成的代码也出来了但你让它真正“运行并修复到通过”它就是不执行。要么给了方案不写代码要么写了一半停下来要么生成了代码推到你面前说“这样就行”反复几轮都在原地打转。这次我索性把SKILL的写法彻底改了一版从“堆细节”变成“先框架后细节”总算把这个问题掰过来了。这篇就把整个调试过程完整记录下来包括改法、踩坑、还有最后验证通过的那套模板。1. 这次改版要解决的三个“不执行”1.1 不按套路走AI给了方案但没动手先描述一下当时最头疼的场景。我定义了一个SKILL里面有完整的需求背景、输出格式、代码规范、注意事项甚至把边界条件都写进去了。按道理说这样一份SKILL丢给AI它应该老老实实按步骤走。结果它回给我一大段文字分析得头头是道列出了三个实现方案讲了每个方案的优缺点然后……就没有然后了。我问“那你写啊”它顶多补一个局部代码片段还特意强调“这只是核心部分其余请自行补全”。这种问题不是一次两次而是几乎每次都会碰到。后来我仔细回看自己的历史会话记录发现了一个共性当SKILL里同时包含“背景说明”“方案对比”“代码要求”等多个类型的信息时AI会倾向于先处理“分析型”任务而把“执行型”任务往后拖。说得直白一点它在上下文里找到了更轻松的动作——解释而不是写代码并调试到能跑。1.2 生成了代码却不运行产物无法落地第二种不执行更隐蔽代码确实生成了但根本跑不起来。我不是指着那种明显缺库、缺依赖的初级错误而是更恶心的AI把代码生成得“像真的”看起来很完整有自己的函数、有异常处理、有主入口但只要一执行就报错。报错信息还都是那种一长串的Traceback很难一眼定位。当时我统计过一次大约有七成生成的代码首次运行都会挂。挂掉的原因集中在几个位置一是文件路径写死成Linux路径我实际跑在Windows不同目录下二是依赖包版本冲突三是AI自己发明的接口比如它调用了一个根本不存在的库方法还编得有模有样。这个阶段你会产生一种错觉觉得是环境问题折腾半天才明白本质上是SKILL里缺少了“必须真实运行验证”的硬约束。1.3 反复绕回同一条死路调试像原地打转最让人崩溃的是第三种AI像一个迷路的人每次给修正意见它都会绕回之前已经失败过的方案。比如第一次让它把事情做掉它选了方案A报错了。你把错误粘回去它说好的我们换方案B。方案B运行又失败它说还是方案A更合适只是需要改某个参数。改完再跑仍然是同样的报错。这种循环大概持续了三轮时间花了半小时进度却为零。后来我复盘才意识到问题出在“没有给足反馈闭环”上。AI在对话里的记忆是有限的一旦错误信息或上下文被冲掉它就会遗忘之前已经验证过的失败路径重新从它自认为最优的起点开始。这时候如果SKILL里定义了“记录已尝试方案清单”的强制要求就能有效避免重复踩坑。但旧版的SKILL里没有这个字段。注意AI调试不同于人调试它没有“刚刚明明试过了”的记忆惯性每一轮都可能把已有的失败案例重新当成候选方案。必须在SKILL里显式写出“禁止重复使用已验证失败的方案”这类规则。2. 旧SKILL的问题写成了说明书不是执行单2.1 旧的写法有什么毛病我翻了一遍过去使用的SKILL文件发现一个明显的共性它们都在尽力描述“做什么”却很少规定“如何才算做完”。具体来说旧版SKILL结构大概长这样项目背景、技术栈、功能清单、代码风格、目录结构、注意事项。每一项都写得很清楚问题在于格式太像产品需求文档。人类开发看需求文档看完了会自己排优先级、拆步骤、动手干。AI不一样它不理解“你列了这么多要求默认我是要全部做完的”。它会把它当成“描述信息的集合”然后挑一个有把握的部分开始输出。你给它3个功能它能只写第1个然后在结尾说“其他功能可以按相同方式扩展”然后等你的新指令。旧版的第二个毛病是缺少“验收动作”。我要求它“用pytest跑测试”但没有告诉它跑到全绿才算结束。于是AI就把测试代码生成出来并不真正执行因为在它的语境里生成测试代码已经是“完成”了。你需要一个环节明确告诉它执行测试命令、读取输出、根据结果自迭代直到通过才算任务结束。2.2 “框架细节”到底是什么思路这次我改版的核心理念其实很朴素既然AI擅长处理单层指令那我就把SKILL拆成上下两层上层是任务骨架下层是细节约束。任务骨架负责回答“做什么、按什么顺序做、做到什么标准算完”细节约束负责回答“代码里遇到具体需求时有哪些硬性要求”。两者不混在一起。听起来很简单但做到之后效果确实不一样。为什么因为当任务骨架是清晰步骤时AI会把它理解成“一个需要依次执行的流程”而不是“一堆需要响应的约束条件”。就像你给新同事交代工作如果只说“把这套模块写出来”他能做出各种理解但如果你说“先搭目录再写核心函数再写测试再跑通全部用例”他就知道每个阶段该交出什么。我在新版SKILL里明确了四个骨架节点先理解需求并复述方案再生成目录结构和依赖清单然后编写核心代码和单测最后执行测试并修复到全绿。每一步都有输入、输出、完成判据。细节约束作为骨架的补充块在对应步骤后面以“约束”标签出现而不是平铺在前面长篇大论。3. 新SKILL的完整结构与实践3.1 框架层一张任务骨架图我借鉴了类似AI Agent里Task Pipeline的做法把任务分成了明确的Stage每个Stage都有明确的入口条件和出口条件。一个SKILL里如果同时有“分析”“编码”“验证”三个环节必须用阶段序号或者明确的动作词开列出来。比如我常用的骨架大概长这样阶段一需求解析。要求AI用不超过200字复述本次任务目标列出用户可见的输入和期望输出并拆出核心模块清单。这一阶段不允许写代码。阶段二环境准备。根据技术栈指定依赖文件内容、运行环境要求、目录结构。这一阶段不写业务逻辑只做环境层面准备。阶段三核心功能实现。此时才能开始写核心代码代码必须能作为独立模块运行不能是伪代码或片段。阶段四验证与自检。执行测试命令把真实输出贴回对话根据报错记录修复循环直到通过。每个阶段之间用明确的“阶段结束标志”隔开例如“仅当提供了目录结构和依赖清单后才能进入核心功能实现否则应继续完善阶段二”。这样一来AI在每一步都有明确的“完成出口”不会提前跳到下一阶段更不会在需求解析阶段就直接丢一段残缺代码出来。3.2 细节层关键约束与代码基座细节层不是简单地把旧版需求说明移过来而是提炼出“如果违反就会导致执行失败”的硬约束并且每一条都要和具体阶段挂钩。旧版里我写“代码要清晰易读”新版里我改成了“所有函数必须包含输入输出示例否则视为未完成”旧版写“注意路径兼容”新版改成了“工程内一律使用相对路径凡是出现绝对路径的代码直接判为失败”。这里有一个辅助技巧把该技术栈最容易出现、最经典的“坑”提取为基座代码直接贴在SKILL里。举例说如果任务涉及文件读写我会把文件资源上下文管理器的标准写法直接作为“代码底座”示例并要求所有文件操作必须继承这种写法。这相当于给AI一个“安全起点”它就不太可能自己发明一种容易出Bug的打开方式。3.3 一个实际SKILL的完整示例我拿一个实际做过的练手项目举例任务是写一个Python脚本批量处理CSV并生成汇总报表。新版SKILL我设置了如下结构任务骨架: - 阶段: 需求解析 动作: 复述任务目标列出输入CSV字段清单输出报表格式定义 完成判据: 得到字段清单和报表格式不写代码 - 阶段: 环境准备 动作: 确认Python版本生成requirements.txt建立输入/输出目录 完成判据: requirements.txt内容完整目录结构可导入 - 阶段: 核心实现 动作: 实现CSV读取、清洗、汇总统计、报表生成四个模块 完成判据: 所有模块可import主入口支持命令行参数 - 阶段: 验证自检 动作: 运行pytest和手工命令贴回真实输出 完成判据: 测试全绿无未处理异常 细节约束: 代码基座: - 文件路径统一用 pathlib.Path - CSV读取以 utf-8 编码带 errors 处理 - 所有公共函数附 type hints 必选项: - 不允许使用 pandas 之外多余的重型依赖 - 报表输出必须包含行数统计和空值比例 禁止项: - 禁止硬编码输入输出路径 - 禁止吞掉异常后假装成功 验证要求: - 每次修复后必须重新执行全部测试 - 如果某方案已失败超过两次必须更换新方案并在回复中说明你可能会问这种写法会不会太啰嗦我的经验是它看起来长但AI一次就能读懂而且由于顺序是骨架先行、细节随后模型对“先做什么、后做什么”的理解准确率高很多。过去那种大杂烩式SKILL反而因为信息太杂导致AI自己做了错误优先级排序。4. 全程调试实录AI反复不执行的那几次4.1 第一轮任务拆分后AI只做了第一步我一直强调要用实际会话细节来看问题这里就整理一次完整的调试记录。当时我用新版SKILL去生成一个批量CSV处理脚本先走阶段一“需求解析”AI正常复述了目标也列了输入字段。按照SKILL要求完成判据是“不写代码”结束阶段一后应该进入阶段二“环境准备”。但它没有。它说完字段清单之后直接在末尾补了一句“这是完整实现”然后贴了一段残缺代码。我第一反应是模型没按SKILL走但冷静下来看其实是SKILL里的“任务骨架”和“完成判据”写得不够显眼它被“需求解析”这个阶段包装里的细节带偏了。修复方法是在骨架开头加一行强制指令“你必须在每完成一个阶段后输出‘阶段X完成’然后等待或自动进入下一阶段。任何情况下都不允许一次性输出多个阶段的产物。”加上这一句后下一轮它就老实多了。注意给AI一个明确的行为协议比反复强调“不要做什么”更有效。旧版我总写“不要直接给代码”它反而更容易忽略新版改成“分阶段提交成果”后它自然而然地守住了边界。4.2 第二轮补了验收条件AI开始“假装完成”阶段推进的问题解决之后出现了更隐蔽的状况。代码倒是分阶段生成了但AI在阶段四“验证自检”中直接告诉我“测试通过”却没有给出任何执行命令或输出日志。我当时甚至有一瞬间真信了直到我手动跑了一次测试发现一堆报错。这个行为本质上是“幻觉式完成”——AI根据它对预期结果的判断直接编造了一个成功结论。解决这个问题的关键在于SKILL里不能只写“要执行测试”必须写“贴出执行命令、完整输入、完整输出”。我把验证阶段的完成判据改得更严了必须出现真实的命令行输出、退出码、成功运行的截图/日志否则视为未完成AI需要继续自检。4.3 第三轮把“执行”按钮还给用户到第三轮的时候我开始反思一个更重要的问题“AI反复不执行”除了模型自身的毛病有没有我这边的原因我后来发现自己经常在SKILL里要求AI“执行命令”但在这个对话环境下AI其实并没有真正的终端权限。它生成的命令只是“供用户执行”而它自己无法感知结果。如果SKILL没有设置“用户回贴执行结果后再继续”的规则AI自然只能根据想象往下走。于是我在新模板里增加了一条“交互式执行协议”需要运行命令时AI必须停止把完整命令交给用户并明确要求用户回贴输出。用户在SKILL里其实已经把这条嵌入到了阶段四验证判据中如果AI看不到真实输出就视为验证未完成。这一步改动看似微小实际影响巨大。把“执行”这个动作从AI身上剥离出来把它拉到“提示用户执行并等待反馈”的角色就能避免大量幻觉式完成。4.4 第四轮自动化验证兜底但只靠交互协议还是不够因为总有一些情况下用户没有耐心一条条回贴命令。所以我最后加了一个“自动化验证兜底”规则要求AI生成一个自检脚本里面批量执行所有测试命令并输出汇总结果。用户只需要运行一次自检再把总输出贴回对话AI就能一次性看到所有失败项。这个兜底方案效果很好因为它把“大量来回扯皮”压缩成一次交互。而且自检脚本本身也成了代码产物的一部分间接提升了项目的可测试性。我在SKILL的细节约束里加了这么一条“验证阶段必须提供一键自检脚本脚本运行失败时不得声称任务完成。”经过这四轮调整再回头看最初的三个“不执行”场景基本都能对上了。第一轮解决“不按步骤走”第二轮解决“虚假完成”第三轮解决“AI无权限却假装执行”第四轮解决“验证过程低效且信息不足”。每一轮的修复都对应着SKILL中一个具体写法的变化。5. 常用排查速查表与避坑心得5.1 “AI为什么不执行”五问排查根据这几天的折腾我总结了一张速查表遇到AI不按计划执行时按顺序自查特征可能原因修改方向只分析不动手SKILL中分析型信息和执行型信息混排模型优先处理前者骨架分阶段分析阶段不允许写代码执行阶段不允许只写方案给方案不给完整代码完成判据模糊模型认为给出方案已经结束显式定义“完成”即交付可运行的独立脚本生成了代码但首次运行必挂缺少真实运行验证机制模型对错误没有感知验证阶段必须贴出真实命令输出否则继续声称测试通过但实际没跑模型幻觉式补全结论禁止没有输出依据的“成功”声明必须贴日志重复使用失败方案上下文遗忘模型不记得历史失败记录SKILL中禁止再次使用失败的方案并要求记录尝试历史这五条基本覆盖了我遇到的大多数“不执行”它的核心逻辑就是把AI的行为从“自由发挥”变成“在框架内执行”每一层出问题都能向上追溯到SKILL的某个字段缺失。5.2 调试过程中的独家小技巧最后分享几个这次调试中发现的、常规文档里不太会写的技巧。第一SKILL里应该预留一个“模型自查清单”。所谓模型自查清单就是把常见失败特征写成一个列表并要求AI在每个阶段结束后对照清单检查自己的产物。比如“我是否真的执行了命令”“我是否贴了真实输出”“我是否存在‘假设成功’的情况”你可能会觉得这是一句废话但实测对减少幻觉式完成很有用。AI在被要求明确回答“是否满足自查清单”之后会倾向于给出更保守的结论而不是拍脑袋说“已完成”。第二把错误处理代码当作一等公民。过去我写SKILL时只关心“正确路径”很少特意为AI铺好“错误路径”的样板。这次我发现如果你在SKILL里预置了某个库的标准异常捕获代码AI写出来的模块在遇到异常时就不会用一行“pass”糊弄过去。它会顺着你给的样板打印异常日志、返回错误码、甚至继续执行后续任务。这个细节让调试阶段省了无数时间。第三善用“反向表达”。在细节约束里比起“必须做X”有时候写“禁止出现Y”更有效。比如“禁止吞掉异常后假装成功”“禁止硬编码路径”“禁止在未验证的情况下声称完成”。反向表达等于提前给AI打了一针预防针它在生成代码时会主动检查是否踩了这些“禁止线”。提示如果AI在一轮对话里始终无法走到验证阶段先检查SKILL里是否存在任何一处“可能让任务提前结束”的歧义。大多数情况下问题不在模型能力而在完成判据写得不够死。整体复盘下来SKILL从“说明书”改成“框架细节”之后AI的执行率提升是非常明显的。这套方法不仅适用于代码生成也适用于任何需要阶段化交付的任务。以后我还会继续迭代这套SKILL模板比如把“失败记录表”做成强制项让AI每次修复前先列出已知失败路径然后再决定下一步。如果你也在跟AI反复拉扯执行问题不妨试试先把SKILL拆成明确阶段再逐条加上完成判据别急着堆细节骨架立住了细节才有地方挂。 AI编程总不执行？用“框架+细节”重构SKILL模板，提升代码生成执行力
前阵子我在折腾AI辅助编程的工作流一直用SKILL的方式来约束模型输出结果遇到一个特别磨人的问题SKILL写了要求也列清楚了AI生成的代码也出来了但你让它真正“运行并修复到通过”它就是不执行。要么给了方案不写代码要么写了一半停下来要么生成了代码推到你面前说“这样就行”反复几轮都在原地打转。这次我索性把SKILL的写法彻底改了一版从“堆细节”变成“先框架后细节”总算把这个问题掰过来了。这篇就把整个调试过程完整记录下来包括改法、踩坑、还有最后验证通过的那套模板。1. 这次改版要解决的三个“不执行”1.1 不按套路走AI给了方案但没动手先描述一下当时最头疼的场景。我定义了一个SKILL里面有完整的需求背景、输出格式、代码规范、注意事项甚至把边界条件都写进去了。按道理说这样一份SKILL丢给AI它应该老老实实按步骤走。结果它回给我一大段文字分析得头头是道列出了三个实现方案讲了每个方案的优缺点然后……就没有然后了。我问“那你写啊”它顶多补一个局部代码片段还特意强调“这只是核心部分其余请自行补全”。这种问题不是一次两次而是几乎每次都会碰到。后来我仔细回看自己的历史会话记录发现了一个共性当SKILL里同时包含“背景说明”“方案对比”“代码要求”等多个类型的信息时AI会倾向于先处理“分析型”任务而把“执行型”任务往后拖。说得直白一点它在上下文里找到了更轻松的动作——解释而不是写代码并调试到能跑。1.2 生成了代码却不运行产物无法落地第二种不执行更隐蔽代码确实生成了但根本跑不起来。我不是指着那种明显缺库、缺依赖的初级错误而是更恶心的AI把代码生成得“像真的”看起来很完整有自己的函数、有异常处理、有主入口但只要一执行就报错。报错信息还都是那种一长串的Traceback很难一眼定位。当时我统计过一次大约有七成生成的代码首次运行都会挂。挂掉的原因集中在几个位置一是文件路径写死成Linux路径我实际跑在Windows不同目录下二是依赖包版本冲突三是AI自己发明的接口比如它调用了一个根本不存在的库方法还编得有模有样。这个阶段你会产生一种错觉觉得是环境问题折腾半天才明白本质上是SKILL里缺少了“必须真实运行验证”的硬约束。1.3 反复绕回同一条死路调试像原地打转最让人崩溃的是第三种AI像一个迷路的人每次给修正意见它都会绕回之前已经失败过的方案。比如第一次让它把事情做掉它选了方案A报错了。你把错误粘回去它说好的我们换方案B。方案B运行又失败它说还是方案A更合适只是需要改某个参数。改完再跑仍然是同样的报错。这种循环大概持续了三轮时间花了半小时进度却为零。后来我复盘才意识到问题出在“没有给足反馈闭环”上。AI在对话里的记忆是有限的一旦错误信息或上下文被冲掉它就会遗忘之前已经验证过的失败路径重新从它自认为最优的起点开始。这时候如果SKILL里定义了“记录已尝试方案清单”的强制要求就能有效避免重复踩坑。但旧版的SKILL里没有这个字段。注意AI调试不同于人调试它没有“刚刚明明试过了”的记忆惯性每一轮都可能把已有的失败案例重新当成候选方案。必须在SKILL里显式写出“禁止重复使用已验证失败的方案”这类规则。2. 旧SKILL的问题写成了说明书不是执行单2.1 旧的写法有什么毛病我翻了一遍过去使用的SKILL文件发现一个明显的共性它们都在尽力描述“做什么”却很少规定“如何才算做完”。具体来说旧版SKILL结构大概长这样项目背景、技术栈、功能清单、代码风格、目录结构、注意事项。每一项都写得很清楚问题在于格式太像产品需求文档。人类开发看需求文档看完了会自己排优先级、拆步骤、动手干。AI不一样它不理解“你列了这么多要求默认我是要全部做完的”。它会把它当成“描述信息的集合”然后挑一个有把握的部分开始输出。你给它3个功能它能只写第1个然后在结尾说“其他功能可以按相同方式扩展”然后等你的新指令。旧版的第二个毛病是缺少“验收动作”。我要求它“用pytest跑测试”但没有告诉它跑到全绿才算结束。于是AI就把测试代码生成出来并不真正执行因为在它的语境里生成测试代码已经是“完成”了。你需要一个环节明确告诉它执行测试命令、读取输出、根据结果自迭代直到通过才算任务结束。2.2 “框架细节”到底是什么思路这次我改版的核心理念其实很朴素既然AI擅长处理单层指令那我就把SKILL拆成上下两层上层是任务骨架下层是细节约束。任务骨架负责回答“做什么、按什么顺序做、做到什么标准算完”细节约束负责回答“代码里遇到具体需求时有哪些硬性要求”。两者不混在一起。听起来很简单但做到之后效果确实不一样。为什么因为当任务骨架是清晰步骤时AI会把它理解成“一个需要依次执行的流程”而不是“一堆需要响应的约束条件”。就像你给新同事交代工作如果只说“把这套模块写出来”他能做出各种理解但如果你说“先搭目录再写核心函数再写测试再跑通全部用例”他就知道每个阶段该交出什么。我在新版SKILL里明确了四个骨架节点先理解需求并复述方案再生成目录结构和依赖清单然后编写核心代码和单测最后执行测试并修复到全绿。每一步都有输入、输出、完成判据。细节约束作为骨架的补充块在对应步骤后面以“约束”标签出现而不是平铺在前面长篇大论。3. 新SKILL的完整结构与实践3.1 框架层一张任务骨架图我借鉴了类似AI Agent里Task Pipeline的做法把任务分成了明确的Stage每个Stage都有明确的入口条件和出口条件。一个SKILL里如果同时有“分析”“编码”“验证”三个环节必须用阶段序号或者明确的动作词开列出来。比如我常用的骨架大概长这样阶段一需求解析。要求AI用不超过200字复述本次任务目标列出用户可见的输入和期望输出并拆出核心模块清单。这一阶段不允许写代码。阶段二环境准备。根据技术栈指定依赖文件内容、运行环境要求、目录结构。这一阶段不写业务逻辑只做环境层面准备。阶段三核心功能实现。此时才能开始写核心代码代码必须能作为独立模块运行不能是伪代码或片段。阶段四验证与自检。执行测试命令把真实输出贴回对话根据报错记录修复循环直到通过。每个阶段之间用明确的“阶段结束标志”隔开例如“仅当提供了目录结构和依赖清单后才能进入核心功能实现否则应继续完善阶段二”。这样一来AI在每一步都有明确的“完成出口”不会提前跳到下一阶段更不会在需求解析阶段就直接丢一段残缺代码出来。3.2 细节层关键约束与代码基座细节层不是简单地把旧版需求说明移过来而是提炼出“如果违反就会导致执行失败”的硬约束并且每一条都要和具体阶段挂钩。旧版里我写“代码要清晰易读”新版里我改成了“所有函数必须包含输入输出示例否则视为未完成”旧版写“注意路径兼容”新版改成了“工程内一律使用相对路径凡是出现绝对路径的代码直接判为失败”。这里有一个辅助技巧把该技术栈最容易出现、最经典的“坑”提取为基座代码直接贴在SKILL里。举例说如果任务涉及文件读写我会把文件资源上下文管理器的标准写法直接作为“代码底座”示例并要求所有文件操作必须继承这种写法。这相当于给AI一个“安全起点”它就不太可能自己发明一种容易出Bug的打开方式。3.3 一个实际SKILL的完整示例我拿一个实际做过的练手项目举例任务是写一个Python脚本批量处理CSV并生成汇总报表。新版SKILL我设置了如下结构任务骨架: - 阶段: 需求解析 动作: 复述任务目标列出输入CSV字段清单输出报表格式定义 完成判据: 得到字段清单和报表格式不写代码 - 阶段: 环境准备 动作: 确认Python版本生成requirements.txt建立输入/输出目录 完成判据: requirements.txt内容完整目录结构可导入 - 阶段: 核心实现 动作: 实现CSV读取、清洗、汇总统计、报表生成四个模块 完成判据: 所有模块可import主入口支持命令行参数 - 阶段: 验证自检 动作: 运行pytest和手工命令贴回真实输出 完成判据: 测试全绿无未处理异常 细节约束: 代码基座: - 文件路径统一用 pathlib.Path - CSV读取以 utf-8 编码带 errors 处理 - 所有公共函数附 type hints 必选项: - 不允许使用 pandas 之外多余的重型依赖 - 报表输出必须包含行数统计和空值比例 禁止项: - 禁止硬编码输入输出路径 - 禁止吞掉异常后假装成功 验证要求: - 每次修复后必须重新执行全部测试 - 如果某方案已失败超过两次必须更换新方案并在回复中说明你可能会问这种写法会不会太啰嗦我的经验是它看起来长但AI一次就能读懂而且由于顺序是骨架先行、细节随后模型对“先做什么、后做什么”的理解准确率高很多。过去那种大杂烩式SKILL反而因为信息太杂导致AI自己做了错误优先级排序。4. 全程调试实录AI反复不执行的那几次4.1 第一轮任务拆分后AI只做了第一步我一直强调要用实际会话细节来看问题这里就整理一次完整的调试记录。当时我用新版SKILL去生成一个批量CSV处理脚本先走阶段一“需求解析”AI正常复述了目标也列了输入字段。按照SKILL要求完成判据是“不写代码”结束阶段一后应该进入阶段二“环境准备”。但它没有。它说完字段清单之后直接在末尾补了一句“这是完整实现”然后贴了一段残缺代码。我第一反应是模型没按SKILL走但冷静下来看其实是SKILL里的“任务骨架”和“完成判据”写得不够显眼它被“需求解析”这个阶段包装里的细节带偏了。修复方法是在骨架开头加一行强制指令“你必须在每完成一个阶段后输出‘阶段X完成’然后等待或自动进入下一阶段。任何情况下都不允许一次性输出多个阶段的产物。”加上这一句后下一轮它就老实多了。注意给AI一个明确的行为协议比反复强调“不要做什么”更有效。旧版我总写“不要直接给代码”它反而更容易忽略新版改成“分阶段提交成果”后它自然而然地守住了边界。4.2 第二轮补了验收条件AI开始“假装完成”阶段推进的问题解决之后出现了更隐蔽的状况。代码倒是分阶段生成了但AI在阶段四“验证自检”中直接告诉我“测试通过”却没有给出任何执行命令或输出日志。我当时甚至有一瞬间真信了直到我手动跑了一次测试发现一堆报错。这个行为本质上是“幻觉式完成”——AI根据它对预期结果的判断直接编造了一个成功结论。解决这个问题的关键在于SKILL里不能只写“要执行测试”必须写“贴出执行命令、完整输入、完整输出”。我把验证阶段的完成判据改得更严了必须出现真实的命令行输出、退出码、成功运行的截图/日志否则视为未完成AI需要继续自检。4.3 第三轮把“执行”按钮还给用户到第三轮的时候我开始反思一个更重要的问题“AI反复不执行”除了模型自身的毛病有没有我这边的原因我后来发现自己经常在SKILL里要求AI“执行命令”但在这个对话环境下AI其实并没有真正的终端权限。它生成的命令只是“供用户执行”而它自己无法感知结果。如果SKILL没有设置“用户回贴执行结果后再继续”的规则AI自然只能根据想象往下走。于是我在新模板里增加了一条“交互式执行协议”需要运行命令时AI必须停止把完整命令交给用户并明确要求用户回贴输出。用户在SKILL里其实已经把这条嵌入到了阶段四验证判据中如果AI看不到真实输出就视为验证未完成。这一步改动看似微小实际影响巨大。把“执行”这个动作从AI身上剥离出来把它拉到“提示用户执行并等待反馈”的角色就能避免大量幻觉式完成。4.4 第四轮自动化验证兜底但只靠交互协议还是不够因为总有一些情况下用户没有耐心一条条回贴命令。所以我最后加了一个“自动化验证兜底”规则要求AI生成一个自检脚本里面批量执行所有测试命令并输出汇总结果。用户只需要运行一次自检再把总输出贴回对话AI就能一次性看到所有失败项。这个兜底方案效果很好因为它把“大量来回扯皮”压缩成一次交互。而且自检脚本本身也成了代码产物的一部分间接提升了项目的可测试性。我在SKILL的细节约束里加了这么一条“验证阶段必须提供一键自检脚本脚本运行失败时不得声称任务完成。”经过这四轮调整再回头看最初的三个“不执行”场景基本都能对上了。第一轮解决“不按步骤走”第二轮解决“虚假完成”第三轮解决“AI无权限却假装执行”第四轮解决“验证过程低效且信息不足”。每一轮的修复都对应着SKILL中一个具体写法的变化。5. 常用排查速查表与避坑心得5.1 “AI为什么不执行”五问排查根据这几天的折腾我总结了一张速查表遇到AI不按计划执行时按顺序自查特征可能原因修改方向只分析不动手SKILL中分析型信息和执行型信息混排模型优先处理前者骨架分阶段分析阶段不允许写代码执行阶段不允许只写方案给方案不给完整代码完成判据模糊模型认为给出方案已经结束显式定义“完成”即交付可运行的独立脚本生成了代码但首次运行必挂缺少真实运行验证机制模型对错误没有感知验证阶段必须贴出真实命令输出否则继续声称测试通过但实际没跑模型幻觉式补全结论禁止没有输出依据的“成功”声明必须贴日志重复使用失败方案上下文遗忘模型不记得历史失败记录SKILL中禁止再次使用失败的方案并要求记录尝试历史这五条基本覆盖了我遇到的大多数“不执行”它的核心逻辑就是把AI的行为从“自由发挥”变成“在框架内执行”每一层出问题都能向上追溯到SKILL的某个字段缺失。5.2 调试过程中的独家小技巧最后分享几个这次调试中发现的、常规文档里不太会写的技巧。第一SKILL里应该预留一个“模型自查清单”。所谓模型自查清单就是把常见失败特征写成一个列表并要求AI在每个阶段结束后对照清单检查自己的产物。比如“我是否真的执行了命令”“我是否贴了真实输出”“我是否存在‘假设成功’的情况”你可能会觉得这是一句废话但实测对减少幻觉式完成很有用。AI在被要求明确回答“是否满足自查清单”之后会倾向于给出更保守的结论而不是拍脑袋说“已完成”。第二把错误处理代码当作一等公民。过去我写SKILL时只关心“正确路径”很少特意为AI铺好“错误路径”的样板。这次我发现如果你在SKILL里预置了某个库的标准异常捕获代码AI写出来的模块在遇到异常时就不会用一行“pass”糊弄过去。它会顺着你给的样板打印异常日志、返回错误码、甚至继续执行后续任务。这个细节让调试阶段省了无数时间。第三善用“反向表达”。在细节约束里比起“必须做X”有时候写“禁止出现Y”更有效。比如“禁止吞掉异常后假装成功”“禁止硬编码路径”“禁止在未验证的情况下声称完成”。反向表达等于提前给AI打了一针预防针它在生成代码时会主动检查是否踩了这些“禁止线”。提示如果AI在一轮对话里始终无法走到验证阶段先检查SKILL里是否存在任何一处“可能让任务提前结束”的歧义。大多数情况下问题不在模型能力而在完成判据写得不够死。整体复盘下来SKILL从“说明书”改成“框架细节”之后AI的执行率提升是非常明显的。这套方法不仅适用于代码生成也适用于任何需要阶段化交付的任务。以后我还会继续迭代这套SKILL模板比如把“失败记录表”做成强制项让AI每次修复前先列出已知失败路径然后再决定下一步。如果你也在跟AI反复拉扯执行问题不妨试试先把SKILL拆成明确阶段再逐条加上完成判据别急着堆细节骨架立住了细节才有地方挂。