1. 为什么“能力”不是 Agent 的瓶颈1.1 一个被反复验证的观察过去一年我参与过几个 AI coding agent 的落地项目从最初用现成框架搭原型到后来自己写编排逻辑踩过的坑不算少。有一个结论越来越清晰Agent 做不好事情绝大多数时候不是模型能力不够而是流程没有被显式地写下来。你让一个资深工程师去修一个线上 bug他不会上来就改代码。他会先看日志、复现问题、定位到具体模块、写一个失败的测试、再改代码让测试通过、跑一遍回归、最后提交。这一整套动作他做了十年已经内化成肌肉记忆。但 Agent 没有这个肌肉记忆。你给它一个“修复这个 bug”的指令它可能直接跳到改代码那一步改完还挺自信地告诉你“已修复”。问题出在哪不是它不会写代码是它不知道在什么阶段该做什么、不该做什么、做完之后要验证什么。这就是流程的缺失。1.2 把流程写成 skill 到底是什么意思这里说的 skill不是指某个具体平台的插件格式而是一个更通用的概念把一段可复用的工程流程用结构化的方式描述出来让 Agent 能够按步骤执行并且在关键节点上有明确的判断依据。打个比方。你招了一个新人能力很强但不懂你们团队的规矩。你不会指望他看一眼代码库就什么都明白你会给他一份 onboarding 文档告诉他提交前必须跑 lint、PR 必须关联 issue、改数据库要写 migration、上线前要走灰度。这份文档就是 skill。Agent 也一样。它的“能力”已经够了缺的是这份文档。而且这份文档不能是给人看的自然语言散文得是 Agent 能解析、能执行、能在中途做判断的结构化描述。1.3 谁适合参考这套思路如果你正在做以下几件事这篇内容应该对你有用在用 AI coding agent 做实际项目但发现它总是“差一口气”想把自己的工程经验沉淀成可复用的资产而不是每次重新解释在搭 agent 框架需要一套编排流程的方法论对 agent skill 这个概念感兴趣但不确定怎么落地不需要你是 agent 专家但最好有一定的工程实践背景因为很多流程细节是从实际项目里长出来的不是凭空设计的。2. 流程拆解一个资深工程师到底在做什么2.1 从接到任务到交付的完整链路我先拿一个最常见的场景举例修复一个线上报告的 bug。一个资深工程师的完整动作链路大概是这样理解问题读 bug 报告确认现象、影响范围、复现条件复现问题在本地或测试环境重现确认不是环境问题定位根因看日志、加断点、二分查找找到出问题的代码评估影响这个改动会影响哪些模块、哪些接口、哪些数据写测试先写一个能复现 bug 的失败测试修改代码用最小改动让测试通过跑回归确保没有破坏其他功能自查看 diff、检查边界条件、确认没有遗留调试代码提交写清楚的 commit message关联 issue观察上线后看监控确认问题真的解决了这十步里Agent 最容易出问题的是第 3、4、5、8 步。它可能定位到错误的根因、忽略影响范围、跳过测试、提交前不自查。而这些恰恰是资深工程师和普通工程师的分水岭。2.2 哪些环节可以写成 skill不是所有环节都值得写成 skill。我的经验是满足以下条件的环节才值得沉淀重复性高每次做类似任务都要走一遍有明确判断标准什么算完成、什么算通过能说清楚容易出错新手或 Agent 经常在这里翻车有隐性知识不写下来就传不下去的经验按这个标准筛一遍上面十步里值得写成 skill 的大概是复现问题、定位根因、评估影响、写测试、自查。理解问题和提交这两步相对简单可以合并到其他 skill 里。2.3 一个反直觉的发现我一开始以为 skill 要写得越详细越好把每个动作都拆到原子级别。后来发现不对。写得太细Agent 会变成提线木偶失去灵活应对的能力写得太粗又等于没写。比较合适的粒度是每个 skill 对应一个明确的阶段目标内部给出关键检查点和判断依据但具体怎么执行留给 Agent 自己决定。比如“定位根因”这个 skill我会告诉它先看最近的变更、再查日志中的异常模式、如果十分钟内没定位到就考虑二分查找。但我不会告诉它具体用哪个命令、看哪个文件。这个粒度是我试了好几版之后才找到的。太细的版本 Agent 执行起来很僵硬遇到稍微不同的情况就卡住太粗的版本又回到了“你自己看着办”的状态。3. 核心细节skill 到底该怎么写3.1 结构比内容更重要写 skill 最容易犯的错误是把它写成一篇教程。教程是给人看的线性阅读从头到尾。但 Agent 执行 skill 不是线性的它会在不同阶段跳来跳去需要快速定位到当前该做什么。所以 skill 的结构应该是模块化的每个模块有明确的入口条件和出口条件。我常用的结构是这样的skill: 定位根因 前置条件: 问题已复现 输入: 复现步骤、错误现象、相关日志 步骤: - 检查最近的代码变更 - 分析日志中的异常模式 - 如果未定位执行二分查找 判断点: - 能否用一句话描述根因 - 根因是否解释了所有观察到的现象 输出: 根因描述、相关代码位置 后置条件: 根因已确认可以进入修复阶段这个结构的关键在于判断点。判断点是 skill 的质量门Agent 必须在这里停下来自问而不是一路往前冲。没有判断点的 skill等于没有刹车。3.2 判断点怎么写才有用判断点不能是“检查是否正确”这种废话。它必须是可操作的、有明确答案的。我总结了几种有效的判断点写法一句话测试能否用一句话说清楚说不清楚说明还没想明白反例测试有没有反例能推翻当前结论有的话说明结论不牢边界测试极端情况下还成立吗比如空输入、超大输入、并发场景回归测试改动后原有功能还正常吗必须有测试覆盖这几种判断点我在不同 skill 里反复用效果很好。它们的好处是不依赖具体技术栈不管是前端、后端还是数据工程都能套用。3.3 一个完整的 skill 示例我拿“写测试”这个环节举例展示一个完整的 skill 长什么样skill: 写失败测试 前置条件: 根因已定位 输入: 根因描述、相关代码 步骤: - 根据根因构造最小复现用例 - 写一个测试断言期望行为 - 运行测试确认它失败 - 确认失败原因与根因一致 判断点: - 测试失败的原因是否就是根因 - 测试是否足够小只覆盖这一个问题 - 测试是否稳定多次运行结果一致 输出: 失败的测试用例 后置条件: 测试失败且原因正确可以进入修复阶段注意这里有个关键点必须先确认测试失败再改代码。很多 Agent 会跳过这一步直接改代码然后写个通过的测试。这样测试就失去了意义它变成了对当前实现的描述而不是对期望行为的约束。这个细节我在 skill 里会特别强调因为它是区分“真测试”和“假测试”的分水岭。4. 实操把流程落地成可执行的 skill4.1 从现有项目里提取流程不要凭空设计 skill。最好的来源是你自己或团队正在用的流程。我的做法是找一个最近做过的、有代表性的任务把实际做过的每一步写下来包括那些“顺手就做了”的动作标出哪些步骤是必须的哪些是可选的标出哪些步骤容易出错需要加判断点把必须步骤和判断点整理成 skill 结构这个过程我做过好几次每次都能发现一些自己都没意识到的习惯动作。比如我发现自己每次改代码前都会先看一眼 git status确认工作区是干净的。这个动作我做了十年从来没想过要写下来但它其实很重要——工作区不干净的时候改代码很容易把无关改动混进去。4.2 参数选择粒度、长度、抽象层级写 skill 的时候有几个参数需要权衡参数太小的表现太大的表现我的建议粒度Agent 执行僵硬遇到变化就卡等于没写Agent 还是自由发挥每个 skill 对应一个阶段目标长度信息不足Agent 需要猜信息过载Agent 抓不住重点控制在 20-50 行结构化描述抽象层级绑定具体工具换个环境就废太抽象Agent 不知道怎么做描述做什么和为什么不描述用什么粒度这个参数我调了好几版。最开始我按“每个动作一个 skill”来拆结果 skill 数量爆炸Agent 在它们之间跳来跳去反而更乱。后来改成“每个阶段一个 skill”数量控制在 5-8 个效果好很多。4.3 实操现场一次完整的 skill 执行记录我拿一个真实案例来展示。任务是修复一个 API 返回错误数据的问题。阶段一复现问题Agent 按照 skill 执行先看 bug 报告构造请求确认返回了错误数据。判断点能否稳定复现答能每次请求都返回错误。进入下一阶段。阶段二定位根因Agent 检查最近变更发现三天前有个 PR 改了数据转换逻辑。看日志发现转换后的数据在某个字段上多了一层嵌套。判断点能否用一句话描述根因答数据转换时多包了一层对象。进入下一阶段。阶段三评估影响Agent 检查这个转换逻辑被哪些地方调用发现有五个接口共用。判断点影响范围是否明确答明确五个接口都受影响。进入下一阶段。阶段四写失败测试Agent 写了一个测试断言转换后的数据结构。运行失败。判断点失败原因是否与根因一致答一致都是多了一层嵌套。进入下一阶段。阶段五修复Agent 修改转换逻辑去掉多余的嵌套。运行测试通过。判断点是否有回归答跑了全量测试没有回归。进入下一阶段。阶段六自查Agent 看 diff确认只改了转换逻辑没有遗留调试代码。判断点改动是否最小答是只改了三行。提交。这个流程走下来Agent 的表现比没有 skill 的时候稳定很多。关键差别在于它在每个阶段结束时都会停下来自问而不是一路往前冲。4.4 注意事项几个容易踩的坑不要写“正确的废话”比如“确保代码质量”这种判断点等于没有。要写“是否有测试覆盖”“是否有边界条件未处理”不要绑定具体工具写“运行测试”而不是“运行 pytest”这样换个项目也能用不要忽略失败路径skill 不仅要写成功路径还要写“如果判断点不通过怎么办”不要一次写太多先写两三个核心 skill用起来之后再扩展提示skill 写完之后一定要拿一个真实任务跑一遍。很多问题只有跑起来才会暴露比如判断点太模糊、步骤顺序不对、缺少必要的输入。5. 常见问题与排查技巧5.1 Agent 不按 skill 执行怎么办这是最常见的问题。原因通常有三个第一skill 描述不够明确。Agent 不知道当前处于哪个阶段或者不知道判断点该怎么判断。解决办法是把前置条件和后置条件写清楚让 Agent 能明确知道自己在哪里。第二skill 太长Agent 抓不住重点。我试过写一个 200 行的 skill结果 Agent 执行的时候经常漏掉中间的判断点。后来拆成三个 50 行的 skill问题就解决了。第三缺少强制机制。如果 skill 只是“建议”Agent 可能跳过。解决办法是在关键判断点加硬性要求比如“必须输出判断结果才能进入下一阶段”。5.2 判断点太严导致 Agent 卡住有时候判断点写得太严格Agent 会反复检查同一个东西陷入死循环。比如“确认根因是否正确”这个判断点如果没有明确的判断标准Agent 可能会一直纠结。解决办法是给判断点加时间或次数限制。比如“如果十分钟内无法确认根因记录当前最佳猜测并进入下一阶段”。这样既保证了质量又避免了无限循环。5.3 多个 skill 之间怎么衔接skill 不是孤立的它们之间有依赖关系。比如“写测试”依赖“定位根因”的输出。如果衔接没做好Agent 会在 skill 之间跳来跳去或者重复执行已经做过的步骤。我的做法是显式定义输入和输出。每个 skill 的输入必须来自上一个 skill 的输出这样 Agent 就知道该从哪里拿数据。同时每个 skill 的后置条件就是下一个 skill 的前置条件形成一条链。5.4 常见问题速查表问题可能原因排查方法解决思路Agent 跳过判断点skill 没有强制机制检查判断点是否有明确的输出要求加硬性要求必须输出判断结果Agent 卡在某个阶段判断点太模糊或太严格看 Agent 在判断点上的输出加时间限制或明确判断标准skill 之间衔接混乱输入输出没有显式定义检查每个 skill 的输入来源显式定义输入输出形成链条Agent 执行结果不稳定skill 粒度太细或太粗看 Agent 在哪些步骤上表现不一致调整粒度每个 skill 对应一个阶段目标skill 换个项目就废了绑定了具体工具或环境检查 skill 里有没有硬编码的工具名描述做什么和为什么不描述用什么5.5 几个独家避坑技巧技巧一用“反例”测试 skill。写完一个 skill 之后拿一个不适用它的任务跑一遍看 Agent 会不会硬套。如果会说明 skill 的适用条件没写清楚。技巧二让 Agent 自己解释判断点。在判断点之后加一步“解释你的判断依据”这样你能看到 Agent 是怎么想的也更容易发现 skill 里的模糊之处。技巧三skill 要版本化。每次修改 skill 都记下来改了什么、为什么改。我用了一个简单的 changelog记录每个 skill 的演进过程。回头看的时候能发现很多有价值的模式。技巧四不要追求完美。我第一版 skill 写得很粗糙但用起来之后很快就发现了问题改了两三版就稳定了。如果一开始就追求完美可能永远写不出来。6. 从 skill 到质量门让流程真正起作用6.1 质量门是什么质量门是 skill 里的关键判断点但它比普通判断点更严格。普通判断点是“建议检查”质量门是“必须通过才能继续”。比如“测试必须通过”是质量门“测试最好覆盖边界条件”是普通判断点。质量门的作用是防止 Agent 带着问题进入下一阶段。很多 Agent 的问题不是它做错了而是它做错了还继续往下走最后交付了一个有问题的结果。质量门就是在这个链条上设卡。6.2 哪些环节适合设质量门不是所有判断点都适合升级成质量门。质量门太多Agent 会寸步难行太少又起不到把关作用。我的经验是在不可逆的环节设质量门。什么是不可逆的环节比如提交代码之前提交了就进历史了部署到生产之前部署了就影响用户了删除数据之前删了就找不回来了这些环节一旦出错修复成本很高。所以必须在这些地方设质量门确保 Agent 停下来确认。6.3 质量门的实现方式质量门的实现可以很简单就是在 skill 里加一个强制检查步骤质量门: 提交前检查 必须满足: - 所有测试通过 - 没有遗留调试代码 - commit message 关联了 issue 不满足时: 停止提交返回修复阶段关键是不满足时的处理。很多 skill 只写了“必须满足”但没写“不满足怎么办”。Agent 遇到不满足的情况可能会忽略或者卡住。明确写出“返回修复阶段”这样的指令Agent 就知道该怎么做了。6.4 一个完整的质量门链条我把一个完整的开发流程拆成了六个质量门复现门问题必须能稳定复现否则不进入定位阶段根因门根因必须能用一句话描述否则不进入修复阶段测试门必须有失败的测试否则不进入修复阶段回归门全量测试必须通过否则不进入自查阶段自查门diff 必须最小且干净否则不进入提交阶段提交门commit message 必须关联 issue否则不提交这六个门串起来就是一条完整的质量链。Agent 在每个门上都必须停下来确认确认通过才能继续。实测下来这套机制能把 Agent 的交付质量提升一个档次。6.5 质量门不是越多越好我一开始设了十几个质量门结果 Agent 执行一个简单任务要停下来确认十几次效率极低。后来精简到六个只保留不可逆环节的门效果好很多。质量门的原则是只在真正重要的地方设卡其他地方让 Agent 自由发挥。这跟管理团队是一个道理你不可能每个动作都审批但关键决策必须把关。7. 我个人的一些体会这套东西我用了大半年最大的感受是Agent 的能力上限很高但它的下限取决于你给它多少约束。没有 skill 和 quality gate 的时候Agent 的表现波动很大有时候惊艳有时候离谱。加上这套流程之后它的表现稳定了很多虽然偶尔还是会出错但至少不会犯低级错误。另一个体会是写 skill 的过程其实是在梳理自己的工程思维。很多我以为自己“知道”的东西写下来才发现其实没想清楚。比如“定位根因”这个环节我一开始写得很模糊后来逼着自己把判断标准写清楚才发现自己对“什么是好的根因描述”其实没有明确标准。写 skill 的过程也是自我校准的过程。最后分享一个小技巧skill 写完之后让 Agent 用它跑一个真实任务然后看它在哪个判断点上卡住或者跳过。卡住的地方说明判断点太模糊跳过的地方说明判断点不够强制。根据这些反馈改一两版skill 就基本可用了。不要指望一次写对迭代才是常态。