1. 为什么“能力”不是 Agent 的瓶颈流程才是先把结论摆在前面我折腾 AI coding agent 这两年最大的体会是——模型能力早就溢出了真正卡住产出质量的是流程没有被固化下来。你给一个资深工程师一个模糊需求他能交付一份能上线的代码你给一个能力更强的 agent 同样的模糊需求它大概率给你一份“看起来对、跑起来崩”的东西。差别不在智力在于那位工程师脑子里装着一套经过千百次踩坑沉淀下来的工作流。这个判断不是拍脑袋。我做过一个很朴素的对照实验同一个 agent、同一个模型、同一个需求给一个内部工具加一个带分页和筛选的列表接口唯一变量是我有没有把“流程”写清楚。第一次我只丢了一句“帮我实现这个接口”结果是它直接开写字段命名随意、没考虑空值、分页参数用 offset 还是 page 全靠猜、错误码自己发明了一套。第二次我把流程拆成“先读现有接口约定 → 再确认数据模型 → 再写实现 → 最后自测边界”同样的模型产出质量肉眼可见地上了一个台阶。所以这篇想聊的核心就一件事把资深工程师的流程写成 agent 能执行的 skill。这里的 skill 不是某个具体产品的专有名词而是一种通用思路——把“怎么做一件事”的隐性知识变成 agent 可以加载、可以复用、可以组合的显式资产。关键词里的 agent、skill、AI coding agents、流程、规范本质上都指向同一个问题如何让 agent 从“会写代码”进化到“会按规矩交付代码”。适合谁看如果你正在做 agent 开发、在团队里推 AI coding 工具、或者单纯想让自己的 agent 少犯低级错误这篇都是给你写的。我不打算讲空泛的方法论而是把我实际写 skill、调 skill、被 skill 坑过的经验摊开讲包括结构怎么设计、边界怎么划、哪些坑一定会踩。先说一个反直觉的点skill 写得越“全”往往越没用。我一开始也犯这个错恨不得把一个领域的知识全塞进一个 skill 里结果 agent 加载之后反而抓不住重点该遵守的没遵守不该管的瞎管。后面才慢慢摸到门道——skill 的价值不在于信息量而在于约束的精准度。这跟带新人是同一个道理你不会给新人一本 500 页的手册让他自己悟你会告诉他“这个项目里改数据库必须先写迁移脚本再改模型最后改接口顺序不能乱”。2. 拆解一个资深工程师的“隐性流程”2.1 从需求到代码中间到底发生了什么大多数人以为工程师的工作是“需求 → 代码”其实中间隔着一长串决策。我把自己做需求时的思维过程拆开大概是这么几步先判断这个需求属于哪一类是新功能、改现有逻辑、还是修 bug再定位相关代码在哪然后确认现有的约定和模式是什么接着才是设计实现方案最后写代码、自测、提交。每一步都有大量“默认规则”在起作用而这些规则恰恰是 agent 最缺的东西。举个具体的。资深工程师拿到“加个导出功能”的需求脑子里会自动跳出几个问题导出是同步还是异步数据量大不大要不要限流导出格式是 CSV 还是 Excel这些问题的答案往往不写在需求文档里而是藏在“我们团队一直这么做”的默契里。agent 没有这种默契它只能靠猜猜错就是返工。所以写 skill 的第一步不是急着写规则而是先把这些隐性决策显性化。我的做法是拿一张纸把一个典型任务从头到尾走一遍每做一个判断就记一笔“我为什么这么判断”。记完你会发现真正需要写进 skill 的就是这些“为什么”。2.2 哪些流程值得固化哪些不值得不是所有流程都值得写成 skill。我踩过的坑是一开始什么都想固化结果维护成本高得离谱skill 本身成了负担。后来我总结了一个筛选标准只有同时满足下面几条的流程才值得写成 skill高频这个任务一周至少出现几次固化下来才有复利。有明确对错流程执行得好不好有客观标准能判断而不是“看感觉”。容易出错新手或 agent 在这个环节经常翻车说明它有固化价值。相对稳定流程本身不会三天两头变否则 skill 刚写完就过期了。反过来那些一次性的、高度依赖具体上下文的、或者还在快速演进的流程就别急着固化。我见过有人给一个还在天天改的内部工具写了一套详细的 skill结果工具改版skill 全废纯属给自己找活干。这里有个很实用的判断技巧如果一个流程你需要反复跟新人解释那它就值得写成 skill。因为“反复解释”本身就说明它是隐性知识而隐性知识正是 agent 最缺的。2.3 把“手感”翻译成可执行规则最难的部分来了资深工程师的很多判断是“手感”怎么翻译成 agent 能执行的规则我的经验是手感背后一定有可量化的信号只是当事人自己没意识到。你要做的是把这些信号挖出来。比如“这段代码写得不够干净”是手感但拆开看可能是函数超过 50 行、嵌套超过 3 层、命名里有缩写、缺少错误处理。这些就是可执行的规则。再比如“这个改动风险有点高”是手感拆开看可能是改动了公共模块、影响了超过 3 个调用方、没有测试覆盖。把这些信号写成检查项agent 就能照着执行。我通常会用这样一个句式来翻译“当出现 X 信号时执行 Y 动作因为 Z 原因”。X 是可观测的Y 是具体的Z 是给 agent 理解意图用的。三者缺一不可——只有 X 和 Yagent 会机械执行加上 Z它才能在边界情况下做出合理判断。3. 一个 skill 的骨架应该长什么样3.1 触发条件让 agent 知道“什么时候该用我”skill 最容易出问题的地方是触发条件写得太模糊。我早期写的一个 skill触发条件写的是“当需要处理数据时”结果 agent 几乎在每个任务里都加载它包括那些根本不需要的白白占用上下文还干扰判断。后来我改成“当任务涉及数据库读写、且需要修改表结构时”精准多了。触发条件的设计原则是宁可窄一点也不要宽。窄了顶多是没触发你手动补一下宽了是到处乱触发污染整个执行过程。我现在的习惯是触发条件里至少包含一个“必须同时满足”的组合而不是单个关键词匹配。另外触发条件最好能区分“强触发”和“弱触发”。强触发是明确该用弱触发是可能相关、需要 agent 自己判断。这样 agent 在加载时就有了优先级不会一视同仁。3.2 执行步骤颗粒度怎么把握步骤的颗粒度是个技术活。太粗agent 自由发挥空间太大等于没约束太细agent 变成提线木偶遇到没预料到的情况就卡死。我摸索出来的经验是步骤要细到“可验证”但不要细到“可替代思考”。什么意思比如“写实现”这一步我不会写成“打开文件、输入代码、保存”那是可替代思考我会写成“实现必须覆盖正常路径和至少两个边界情况且每个分支都有对应的错误处理”这是可验证的。前者告诉 agent 怎么做后者告诉 agent 做到什么程度算合格。我一般会把一个 skill 的步骤控制在 5 到 9 步之间。少于 5 步说明拆得不够细agent 容易漏多于 9 步说明拆得太碎agent 容易在步骤间迷失。这个数字不是硬规定但确实是我试下来比较舒服的区间。3.3 检查点让 agent 自己发现跑偏这是我认为整个 skill 设计里最被低估的一环。大多数人写 skill 只写“怎么做”不写“怎么知道做对了”。但 agent 和人的区别在于人做错了会有直觉上的不安agent 不会它会一路错到底。所以每个关键步骤后面我都会加一个检查点。检查点的形式可以很简单比如“确认 X 已经完成如果没完成回到上一步”。关键是让 agent 在执行过程中有“停下来看一眼”的机会。我常用的检查点类型有三种前置检查做之前确认条件满足、过程检查做的过程中确认没跑偏、后置检查做完确认结果符合预期。前置检查防止无效劳动过程检查防止越走越远后置检查防止交付残次品。三者配合agent 的自我纠错能力会明显提升。3.4 反例库比正例更有价值的部分如果只能保留 skill 里的一个部分我会选反例库。正例告诉 agent“应该怎么做”反例告诉 agent“千万别怎么做”而后者往往更有效。因为 agent 的默认行为模式是“找一条看起来合理的路走”反例能直接堵死那些看起来合理但实际错误的路径。我的反例库一般这么组织每条反例包含“错误做法 为什么错 正确做法”。比如“不要在循环里做数据库查询因为会造成 N1 问题正确做法是批量查询后在内存里组装”。这样 agent 不仅知道不能这么做还知道为什么遇到变体情况也能举一反三。反例的来源很实际你被 agent 坑过的每一次都是一条反例。我现在养成了一个习惯每次 agent 产出有问题我不只是改代码还会把这个问题抽象成一条反例加进 skill。日积月累skill 就越来越“懂”这个项目的脾气。4. 把流程写成 skill 的实操路径4.1 从一次真实任务开始记录别一上来就想写一个覆盖全流程的大 skill那必然失败。我的做法是挑一次刚做完的真实任务边回忆边记录。记录的时候不要美化就写你实际做了什么、当时在想什么、哪里犹豫了、哪里返工了。我拿自己最近一次任务举例。任务是给一个后台加“批量操作”功能。我实际的过程是先看现有的单个操作接口长什么样确认能不能复用然后看批量操作的并发量大概多少决定是同步还是异步接着看有没有现成的批量处理工具类最后才动手写。这个过程里“先看现有接口”和“先评估并发量”就是两条值得固化的流程。记录完之后把过程里的每一步问自己三个问题这一步能不能省省了会怎样这一步能不能更明确能省的省掉不能省的写清楚。这样一轮下来一个 skill 的雏形就有了。4.2 用“失败驱动”的方式迭代skill 不是一次写完的是迭代出来的。我的迭代方式是失败驱动每次 agent 用这个 skill 出了问题就回来改。改的时候不是简单加一条规则而是先问“为什么这条规则没拦住它”是规则本身不清楚还是触发条件不对还是 agent 根本没加载。这里有个很关键的认知skill 出问题八成不是 agent 笨是 skill 写得有歧义。我早期总怪 agent 不听话后来发现是我自己写的规则模棱两可agent 理解成了另一个意思。所以每次出问题我第一反应是回去读 skill 原文看有没有可以两种理解的表述。迭代的节奏我建议是“小步快跑”每次只改一两个点改完立刻用一个小任务验证。别攒一堆改动一起上那样出了问题根本不知道是哪条改坏的。4.3 版本管理skill 也是代码这一点很多人忽略skill 应该像代码一样做版本管理。我现在所有 skill 都放在 git 里每次改动都有 commit message 说明改了什么、为什么改。这样做的好处是当某个 skill 突然不好用了我能快速定位是哪次改动引入的。更重要的是版本管理让 skill 可以“回滚”。有次我改了一个 skill 的触发条件结果它开始在不该触发的时候触发我直接回滚到上一个版本五分钟解决问题。如果没有版本管理我得手动回忆改了啥可能折腾半小时。我还习惯给每个 skill 打标签标注它适用的项目、依赖的工具、最后验证的时间。这样过一段时间回头看能快速判断哪些 skill 可能已经过期了。5. 那些年我被 skill 坑过的真实案例5.1 规则打架当两条 skill 互相矛盾最坑的一次是我同时加载了两个 skill一个说“所有数据库操作必须走 ORM”另一个说“复杂查询直接用原生 SQL”。结果 agent 在一个复杂查询任务里彻底懵了一会儿用 ORM 一会儿用原生代码风格割裂得没法看。这个坑的本质是skill 之间没有优先级。后来我加了一条元规则当多个 skill 冲突时按“具体优先于通用”的原则处理并且要求 agent 在冲突时明确报告而不是自己瞎选。这条元规则本身也写成了一个 skill专门管 skill 之间的协调。所以如果你打算维护多个 skill一定要提前想好它们之间的关系。是互斥、是叠加、还是有优先级这个不定义清楚skill 越多越乱。5.2 过度约束agent 变成了复读机有段时间我追求“零失误”把 skill 写得极其详细每一步都规定死。结果 agent 变得极其死板遇到稍微不一样的情况就卡住或者生搬硬套规则产出反而更差。最夸张的一次它为了遵守“每个函数必须有注释”的规则给一个三行的 getter 写了五行的注释。这个教训让我明白skill 的目的是提升下限不是锁死上限。规则应该约束“不能做什么”和“必须做到什么程度”而不是规定“具体怎么做”。给 agent 留出合理的发挥空间它反而能处理更多意外情况。我现在写规则会刻意留一些“弹性条款”比如“除非有明确理由否则遵循 X 做法”这个“除非”就是给 agent 的判断留的口子。当然弹性不能太大否则等于没规则这个度需要根据任务的风险程度来调。5.3 上下文污染skill 加载太多反而变笨还有一个反直觉的坑skill 不是加载越多越好。我有次为了测试把一个任务相关的五六个 skill 全加载了结果 agent 的表现比只加载一个还差。原因是上下文被大量规则占满agent 的注意力被稀释反而抓不住当前任务的重点。这让我意识到skill 的加载策略本身也是一门学问。我现在的做法是分层加载核心 skill 常驻领域 skill 按需加载边缘 skill 用到才加载。而且会定期清理那些长期不用的 skill保持整体精简。判断一个 skill 该不该常驻我的标准是如果去掉它agent 在 80% 的任务里都会出问题那它就常驻。如果只是偶尔相关那就按需加载。6. 让 skill 真正落地的几个关键习惯6.1 先手动跑通再交给 agent我有个铁律任何 skill我自己先手动按流程走一遍确认流程本身是对的才写成 skill 给 agent 用。因为如果流程本身有问题写成 skill 只会让错误被固化、被放大。手动跑通的过程也是发现流程漏洞的过程。很多你以为理所当然的步骤真走一遍才发现有坑。比如我写过一个“提交前必须跑测试”的 skill手动跑的时候才发现有些测试需要特定环境变量不设就跑不起来。这个细节如果不手动跑根本发现不了agent 用的时候就会卡在测试这一步。6.2 给 skill 配“最小可验证示例”每个 skill 我都会配一个最小示例用来验证 skill 是否正常工作。这个示例要足够小小到能在几分钟内跑完又要足够典型能覆盖 skill 的核心流程。这样每次改完 skill跑一下示例就知道有没有改坏。示例的另一个作用是给 agent 当参照。当 agent 不确定某个步骤该做到什么程度时看一眼示例就明白了。这比纯文字描述有效得多因为示例是具体的、可模仿的。6.3 定期“体检”清理过期 skillskill 会过期这是必然的。项目在变、工具在变、约定也在变半年前写的 skill 可能早就不适用了。我现在的习惯是每个月做一次 skill 体检逐个问这条规则现在还成立吗这个触发条件还准确吗这个反例还典型吗体检的时候我会特别关注那些“从来没被触发过”的 skill。它们要么是触发条件写错了要么是根本不需要两种情况都该处理。留着它们不仅占地方还会在检索时造成干扰。6.4 把 skill 当成团队资产来维护如果是在团队里用skill 就不该是个人行为而应该是团队资产。我们现在的做法是skill 放在共享仓库里谁都可以提改进但改动要经过 review。review 的重点不是格式而是“这条规则会不会误伤其他场景”。团队维护 skill 最大的价值是知识沉淀。以前老员工的经验只在他脑子里他一走就带走了现在写进 skill新人来了直接能用agent 也能用。这其实是一种组织能力的升级把个人经验变成了可复用的组织资产。7. 关于 skill 与 agent 能力边界的一点个人体会聊了这么多流程和 skill最后想说一个我反复验证过的判断agent 缺的从来不是能力是约束和方向。同一个模型给它清晰的流程它能交付惊喜给它模糊的指令它只能交付惊吓。这不是模型的问题是我们作为使用者的问题——我们习惯了把“怎么做”留在自己脑子里只把“做什么”丢给 agent。把资深工程师的流程写成 skill本质上是在做一件反直觉的事把我们最不愿意外化的隐性知识逼着自己写清楚。这个过程很痛苦因为很多判断我们自己都没意识到是怎么做的。但一旦写清楚收益是巨大的——不仅 agent 变强了你自己对流程的理解也更深了甚至能发现原来流程里一直存在的冗余和漏洞。我现在写 skill 的心态已经从“怎么让 agent 听话”变成了“怎么把我自己的经验讲清楚”。后者才是真正的难点也是真正的价值所在。毕竟能被写清楚的流程才是真正被掌握的流程。