最近我把手头三类不同形态的编程智能体统一整理了一遍一个负责在编辑器里逐行补全一个负责跨文件改代码的长会话任务一个负责在终端里自主执行命令完成测试和构建。整理完最大的感受是很多人讨论“提示词技巧”但实际开发中真正拖后腿的根本不是某一句提示词怎么问而是没有建立一套可维护、可验证的RULES与SKILLS规范。这篇就把我对三大编程智能体的规则文件和技能文件设计思路、编写方法、落地细节完整展开适合正在折腾AI编程助手的开发者和团队参考。1. 为什么现在的编程智能体离不开“规则文件”和“技能文件”1.1 RULES的本质把人的约定转成机器能判断的边界很多开发者第一次接触编程智能体时习惯把要求全部写进对话框里“帮我写一个接口注意代码风格要和项目一致不要破坏现有逻辑要写注释……”这些话在单次会话里可能有效但换个任务、换个会话就归零了。真正的项目级约束应该沉淀成独立的规则文件让智能体每次开工前都能读到。RULES规则解决的不是“让AI更聪明”而是“让AI不越界”。它类似于新员工入职时拿到的工作手册不教你怎么写业务代码只告诉你在什么条件下必须怎么做、什么操作绝对禁止。比如后端项目里最常用的一条规则“所有新增HTTP接口必须包含入参校验非法请求统一返回400和错误码。”没有这条规则智能体可能只做参数映射完全不处理异常输入有了这条规则它在设计接口时就会主动补上校验逻辑。我曾经在一个模拟项目X里做过对比同一套代码库同样让智能体新增一个用户查询接口。没写规则文件时它直接生成了一段跳过空指针判断的代码导致测试挂了才被发现写了规则文件后它在实现的时候顺手补上了空值判断和请求日志。差别不在模型能力而在于有没有把团队约定“前置”到智能体的决策过程里。1.2 SKILLS的本质把一次性任务抽象成可复用流程如果说RULES界定了行为的“不能做什么”和“必须怎么做”那SKILLS技能则是给智能体准备的“任务执行手册”。技能的本质是一份结构化的任务模板包含触发条件、执行步骤、检查项、输出格式让同类型的任务不需要每次从零开始“教”智能体。举个例子“编写单元测试”这个任务新手会让模型“帮我写测试”老手会定义一个技能里面写明先读取被测函数的输入输出类型再按“正常输入-边界输入-异常输入”三个分支组织用例统一使用项目的测试断言风格最后运行相关测试文件确认通过。这样定义完任何会话里只要说“给这个模块写测试”智能体就知道按流程走而不是自由发挥出一堆风格混乱的用例。我习惯把技能文件放在_skills_目录里每个技能一个Markdown文件。技能和普通提示词模板的区别在于技能有“触发条件”和“不适用场景”字段能被智能体主动检索、按需加载普通提示词只是贴在对话里的一段静态文本无法被检索和复用。1.3 三大类编程智能体对规范和技能的需求完全不同在规划规范之前必须先把“三大编程智能体”按工作模式拆开看因为它们对规则的读取能力、上下文上限、自主执行程度差异非常大。智能体类型上下文规模擅长场景规则侧重点补全型小只看当前文件和打开文件行级补全、函数实现、少量改动规则要精简每个约束必须立即可判断会话型大能读仓库文件、多轮对话跨文件重构、新功能开发、Bug定位规则要分层技能要完整、可编排命令执行型大能跑终端命令、自主循环测试修复、构建部署、批量改动规则要硬性约束技能要脚本化、可校验把同一份规范硬套给三类智能体是行不通的。补全型智能体如果加载一个300行的规则文件上下文窗口直接被占满补全出的代码反而莫名其妙命令执行型智能体如果只有“请谨慎操作”这种模糊规则它可能自作主张跑了一个危险命令酿成事故。下面我按三类智能体逐一展开讲清楚每套规范到底怎么写。2. 补全型编程智能体——规则做减法技能做迷你封装2.1 补全型智能体的上下文限制决定了规则只能“小而硬”补全型智能体工作在你的编辑器里它每时每刻都在根据当前文件和最近打开的代码片段预测下一段代码。它的上下文窗口通常非常有限可能只有几KB到几十KB超过这个范围早期的内容会被丢弃。这意味着你塞给它的规则文件越长关键规则被记住的概率越低。我给补全型智能体制定的规则文件一般控制在50到150行并且只保留三类内容技术栈与代码风格、当前模块边界、禁止事项。下面是一份精简规则示例# 项目规则补全智能体专用 - 技术栈TypeScript React新文件一律用 .ts/.tsx。 - 组件统一使用函数组件 hooks禁止 class 组件。 - 样式一律放 CSS Modules 文件禁止内联样式。 - 第三方依赖必须在 package.json 显式声明禁止引用全局对象。 - 新增对外导出必须带 JSDoc 注释。 - 路由改动必须同步更新路由测试文件。这里有个关键点规则不是写给“人”看的而是写给“模型”看的。模型的注意力机制对条件句式更敏感所以规则最好写成“若/则”结构而不是“应保持优雅”这种形容词。比如- 若新增表单组件则必须使用受控组件模式。 - 若调用后端接口则必须处理 loading 和 error 状态。 - 若修改公共工具函数则必须检查调用方是否受影响。这样改完之后补全型智能体在生成代码时会更容易命中约束。实际使用下来同样的代码库规则改写前后补全出的代码与项目现有风格一致率明显提升至少少了一半的人工修改变量。2.2 用“若/则”结构重写规则而不是用形容词有一类人写规则时容易把文件变成“愿望清单”“代码要优雅逻辑要清晰性能要好要有注释。”这个规则对任何模型都没有约束力。因为“优雅”“清晰”这类词没法被判断成具体的分支行为模型既不知道什么时候触发也不知道怎么执行。补全型智能体的记忆非常“局部”它更擅长匹配“看到A条件执行B动作”这种短模式。所以在设计规则时我会刻意把团队约定翻译成条件句。项目里曾经有一条开发约定——所有列表加载必须支持空态和失败态。翻译成规则就是- 若新增列表组件则必须包含 empty、error、loading 三态展示。这条规则在补全时非常有效一旦开发者创建列表组件智能体会主动生成三态逻辑而不是只画一个静态列表。这种“若/则”结构不需要智能体做复杂的意图推理它只需要在生成时识别出场景特征就能做出正确动作。2.3 迷你技能一个技能只解决一个局部动作补全型智能体不适合承载长步骤技能因为技能太长同样会超出它的执行能力。我给补全型智能体设计的技能都遵循“迷你原则”一个技能只解决一个局部动作步骤控制在三步以内能不用就不加额外上下文。比如“生成JSDoc”这个技能我可以压缩成一条规则- 为函数补 JSDoc 时读函数签名 - 用中文说明职责 - 补充 example。再比如“处理组件加载态”技能- 为组件补 loading 逻辑时找页面数据源 - 加 loading state - 渲染处加条件展示。这些“准技能”直接内联到规则文件里不需要额外的技能加载机制。实测中迷你技能比完整技能文件更适合补全场景——完整技能文件里的“第3步”“第4步”往往还没执行到上下文就被新代码冲掉了。3. 会话型编程智能体——规则分层、技能编排3.1 全局规则与项目规则必须分开维护会话型智能体是现在最常用的编程智能体形态它可以在一个长会话里读多份文件、做跨文件修改、执行多轮交互。它的上下文虽然大但也经不住塞一个几百行的“大杂烩”规则。所以我的做法是把规则拆成两个层次全局规则文件和项目规则文件。全局规则文件放在仓库的_agent_目录下负责所有项目通用的约定例如“禁止把密钥、令牌写入代码”“修改API接口时必须同步更新接口文档”“所有日志统一使用结构化日志格式”。项目规则文件放在项目根目录负责当前仓库的特定约束例如“改动只允许发生在src目录vendor目录只读”“数据访问层必须走repository类禁止直接用数据库客户端”。目录结构大致长这样.agent/ global-rules.md skills/ refactor/ rename-api.md test/ fix-test-failure.md docs/ update-changelog.md会话型智能体在开始任务时会同时读取全局规则和项目规则。把两者分开的好处是换项目时只需替换项目规则全局规则可以从其他仓库复制不会出现“所有规则混在一个文件里换项目得逐行删改”的窘境。3.2 跨文件改动前的“影响面声明”怎么写进规则会话型智能体最大的问题是“做得太多”。你让它改一个函数签名它顺便重构了调用方又顺手调整了测试断言最后把README也改了一遍。虽然改动是合理的但对代码审查来说范围失控非常危险。我会在会话型智能体的规则里强制要求“影响面声明”- 当一次修改涉及3个以上文件时 1. 修改前先输出受影响文件清单说明每个文件的改动目的。 2. 确认清单后再执行改动。 3. 完成修改后输出改动摘要内容包括文件清单、每个文件的改动点、测试结果。这条规则给智能体加上了一道“边界检查”先规划、再执行、后汇报。在实际项目中加这条规则前后会话型智能体的改动文件数平均少了一半代码审查时也更清晰因为审查者看到的不是一坨“顺便改的”注释和重构。3.3 技能编排把大任务拆成子技能会话型智能体真正体现出价值的地方在于技能编排。一个“新增功能”的大任务如果把它拆成“需求分析→代码定位→实现→测试补充→变更摘要”五个子技能每个子技能的输入输出都清晰智能体的执行质量会稳定很多。我这里举一个技能文件的骨架示例这个技能叫“开发新功能”--- name: new-feature description: 新增一个完整功能从需求到测试 when_to_use: 当任务要求新增接口、页面、模块或业务能力时 when_not_to_use: 只做局部修改或样式调整时不要使用 depends_on: [code-locate, unit-test, changelog] --- 1. 读取需求梳理输入输出输出实现计划。 2. 调用 code-locate 子技能定位相关文件。 3. 按项目规则完成实现保持代码风格一致。 4. 调用 unit-test 子技能补充单元测试。 5. 调用 changelog 子技能更新变更记录。 checkpoints: - 所有新接口都有入参校验。 - 相关测试全部通过。 - 没有出现未在计划中的文件改动。技能文件里的depends_on字段很关键它告诉会话型智能体在执行时可以调用哪些更小的子技能而不是把所有逻辑都堆在一个大步骤里。这种编排方式让技能库具备“组合性”新技能能复用已有能力而不是每个技能都是从头开始的长流程。4. 命令执行型编程智能体——规则要硬技能要脚本化4.1 命令执行型智能体需要“确定性规则”命令执行型智能体可以自主运行终端命令、循环尝试、修改文件。它的能力边界最强规则稍一放松就容易失控。我给这类智能体制定的规则有一套“刚性约束”关键动作必须走白名单或者暂停请求确认allowed_commands: - npm run build - npm test - npm run lint - git status - git diff sensitive_commands: - git push - git branch -D - npm publish - 任何修改数据库库表或数据的命令规则里明确要求白名单内的命令可以自主执行白名单外的一律停下来请求确认。敏感命令即使出现在任务描述中也必须输出命令内容和影响范围等待明确确认后才能继续。为什么用白名单而不是黑名单因为白名单更保守没列进去的操作统统需要人来确认安全风险天然更低。我还加了一条硬性规则“禁止智能体以任何理由跳过测试或删除测试文件。如果测试本身有错输出说明并等待确认。”这条规则看起来严苛但非常必要。因为命令执行型智能体的自主程度高一旦它觉得“跳过测试”可以加速任务完成它真的会这样做而且会给出一个看似合理的理由。这种“自由裁量权”必须从规则层面掐掉。4.2 技能脚本化预检查、执行、验证、异常分支命令执行型智能体的技能不能只是文字说明它需要把技能封装成类似“脚本流程”的结构——每个步骤有明确的检查动作和验证命令。我常用的技能模板包含四个部分预检查、执行、验证、异常分支。以“修复测试失败”技能为例它的核心流程骨架如下1. precheck: 检查 NODE_ENV 是否存在依赖是否安装。 2. execute: 运行 npm test -- --runInBand捕获失败用例清单。 3. diagnose: 逐条读取失败堆栈定位第一个非测试文件。 4. fix: 最小化修改实现代码禁止修改测试断言。 5. verify: 重跑失败用例再运行相关测试目录确认无回归。 6. summary: 输出改动摘要包含文件清单和测试结果。每个步骤都对应可执行命令智能体不需要“猜测”下一步做什么只需要照着流程跑。这样设计的核心目的是提高确定性。命令执行型智能体的工作链路往往有几十步如果每一步都要它“理解”后再决策出错概率会指数上升脚本化技能等于把“怎么执行”变成了固定流程留给模型自由发挥的空间被压缩到最小。4.3 幂等性与日志审计让执行过程可追溯命令执行型智能体的另一个大坑是“多次执行结果不确定”。比如修复测试失败时它可能第一次改了实现第二次又改了一遍测试第三次把测试删了。要避免这种问题技能里必须写清幂等性约定如果目标已完成则跳过修复步骤只做验证和输出。我在命令执行型智能体的规则里做了一个强制要求- 每一步操作完成后在 LOG.md 追加一行状态记录内容包括命令、退出码、关键输出摘要。 - 失败时优先输出失败日志原文再给出解释不允许用“推测”代替日志。日志要求看起来很简单实际价值非常大。有一次某命令执行型智能体在修复过程中反复重试虽然最后测试通过了但我完全不知道它改了什么。加了日志记录后我能从LOG.md里看到每一步的退出码和输出摘要出了异常也能快速定位到具体步骤。这就像给自主智能体加了一个“黑匣子”没有它你敢让它自主跑几十分钟的任务吗5. 三类智能体通用的RULES与SKILLS设计原则5.1 规则分四层全局、团队、项目、任务三类智能体侧重点不同但规则体系最好都统一采用四层结构它能让规范和智能体的读取机制解耦也便于换人、换项目时维护。规则层适用范围示例维护者全局层所有仓库、所有语言禁止硬编码密钥、统一日志格式团队基础设施负责人团队层组织内多个仓库共同约定PR合并前必须补测试技术负责人项目层单个仓库只改src目录、使用特定ORM项目owner任务层一次性指令本次会话内不允许改公共库发起者层级越高的规则越稳定越低的规则越易变。低层规则不能随意覆盖高层规则除非在文件中显式声明“本文件有意覆盖全局条目的第X条”。这样既保证底线安全又给具体场景留了灵活性。分层规则还有一个好处智能体在加载时可以按需读取。全局层和项目层文件固定加载团队层和任务层按任务匹配加载不会出现“所有内容混在一个文件里加载时什么都读哪条都没记住”的情况。5.2 技能文件的元信息与检索设计技能文件要能被智能体主动检索到必须设计好元信息。核心字段包括name、description、when_to_use、when_not_to_use、tags、version、last_reviewed、depends_on。其中最重要的其实不是name而是description和when_not_to_use。description要写清楚“这个技能解决什么任务适合什么场景”否则智能体在跨任务匹配时容易误加载。when_not_to_use则是“反向过滤器”明确告诉智能体“这个任务不要用此技能”能大幅减少误触发。举个反例很多人给技能起名“重构助手”结果智能体在普通的接口新增任务中也加载了这个技能导致大改代码结构。后来在技能里加了when_not_to_use: “新增逻辑、修复Bug、样式调整时不使用”误触发率明显下降。检索命中率、误触发率都应该成为技能库的评估指标而不能只看“技能写了多少”。5.3 规则和技能的版本管理与效果验证规则文件和技能文件本质上也是“代码”需要做版本管理。我会把整个.agent目录提交进Git仓库每次修改都走commit在技能文件头部维护version和last_reviewed字段。真正有价值的是一套“效果回测矩阵”。我准备五个固定任务新增一个REST接口、修复一个已知Bug、重构一个模块、更新某个页面组件、补全某模块的单元测试。每次调整规则就用这五个任务各跑一遍记录评价指标指标调整前调整后平均修改文件数4.82.2编译/测试一次通过率60%90%需要人工修正的点数3.40.8规则命中次数15有了这组数据改规则就不会变成“凭感觉调参数”而是明确知道“改动A带来了命中率提升代价是修改文件数增加”。我自己在实践中的经验是先跑回测矩阵再发布规则比让智能体试错几天高效得多。6. 实战编写“修复测试失败”技能的自检清单与三端适配6.1 先写规则再写技能很多人一上来就想写技能实际上顺序应该是反过来的先写配套规则再写技能。因为技能解决“怎么做”规则解决“允许做什么、禁止做什么”如果规则没定好技能执行时没有边界效果不稳定。以“修复测试失败”这个高频任务为例我写技能前先定了三条前置规则- 全局测试命令统一为 npm test新增测试统一放在 __tests__ 目录。 - 修复过程中禁止删除或修改测试断言如果断言语义本身有误必须线下确认后再调整。 - 修复完成后必须运行相关测试和全量测试两轮通过才能算完成。这三条规则看似简单实际上堵住了“修复测试失败”任务中最常见的三个坑找不到测试入口、直接把测试改绿、只修单条不跑回归。规则定好后技能本身反而很顺。6.2 技能正文五个步骤覆盖从复现到验证的完整链路“修复测试失败”技能正文我写得很固定总共七步每一步都很具体--- name: fix-test-failure description: 修复测试失败用例保持实现和测试的健壮性 when_to_use: 当测试报告出现失败用例、抛错、超时时 when_not_to_use: 新增测试、重构测试结构时不使用 --- 1. 运行 npm test捕获全部失败用例清单。 2. 顺序读取每个失败用例的堆栈定位第一个非测试文件。 3. 在实现文件中找到与堆栈对应的代码路径理解失败原因。 4. 最小化修改实现代码禁止为让测试通过而调整断言。 5. 重新运行失败用例确认该项变绿。 6. 运行相关测试目录确认没有回归。 7. 输出改动摘要文件清单、每个文件的改动原因、测试结果。第2步“先看堆栈再改代码”值得单独强调。很多智能体碰到测试失败第一反应是“重新读一遍整个文件然后重写”结果改了一堆没用的地方。而按堆栈定位能直接告诉它问题出在哪一行避免了无差别重写。在我的项目里加入“先读堆栈再改代码”这个约束后修复时长明显缩短。6.3 三种智能体上的适配差异同一个技能三类智能体的使用方式完全不同。我把适配方案整理成表格智能体类型技能粒度和读取方式执行方式典型产出补全型压缩成一句话内联进规则文件自动补全局部修复片段会话型完整技能文件按需读取多轮对话完整修改说明命令执行型脚本化步骤验证命令自主执行终端命令序列改动摘要日志我做了简单改造给补全型智能体的规则文件里加一句话版本——“修复测试失败时先读失败输出再改实现不要改断言。”给会话型智能体配置完整技能文件让它按步骤走完整个修复流程。给命令执行型智能体则把技能脚本化成上面那种带precheck、verify、summary的流程让它能自主监督测试验证。拿同一个模拟项目X做了三轮对比效果差异让我很意外改造之前让会话型智能体修复测试失败它平均会改动5个文件其中还有3次尝试调整断言全部过程大概要30分钟改造后它平均只动2个文件断言误改降到0次耗时才8分钟左右。真正的收益不在第一次修复有多快而在于每次修复后代码范围可控、审查可过不会因为“智能体自己发挥”引入新的问题。如果你也想在自己项目里落地这套规范我的建议是先选一个最高频的任务比如测试修复把配套规则和技能打磨好跑完回测矩阵再上线。不要一口气定义几十个技能技能库越大误触发和检索成本越高。先让一套规范稳定跑起来再逐步扩展。