★ FEATURED ARTICLE 先说结论这套叫 AI-Infra-Auto-Driven-SKILLS 的工作流本质上不是给你塞十几个花哨提示词而是把 Codex、Claude Code 这类 AI 编码代理从你说一句它做一步的被动状态掰成按固定推理框架自主拆解、执行、验证、留痕的主动状态。v0.1.5 是我自己迭代到第五轮的版本号里面沉淀的是技能包的组织方式、推理协议的编排规则以及接入两个代理时的踩坑记录。如果你正在用 AI 写代码、做 Code Review、重构老项目但总觉得模型聪明但不听话答得对但做不全那这套框架就是冲这个问题去的。下面我把设计思路、技能文件怎么写、怎么接进 Codex 和 Claude Code、以及我踩过的坑一次说清楚。1. 为什么需要一套推理框架工作流1.1 裸用 AI 编码代理的三个痛点先说我最早裸用 Codex 和 Claude Code 的感受。单论单次问答这俩都很强复杂逻辑能给你拆得明明白白。但一旦把任务放大到改完一个模块、跑通测试、再提交 PR问题就冒出来了。第一个痛点是步骤漂移。你让代理重构这个函数它可能直接开写不读调用方也可能读了一堆无关文件改完才发现破坏了对外的接口。不是模型笨是它缺少一个先想后做、做完校验的强制流程。第二个痛点是每次对话都是失忆状态。同一个仓库今天问它这个模块怎么优化它给一套方案明天再问它可能给出完全不同的另一套。没有可复用的技能缓存等于每次都在让一个聪明但没记性的实习生从头开始摸索。第三个痛点是产物不可校验。人写代码有自测AI 写完代码往往直接说完成了但它没有跑测试、没有过 lint、没有看 diff 是否符合预期。你作为人类还得重新审一遍省下的时间又吐回去一部分。1.2 从一次性提示词到可复用技能当时我的第一反应是写更长的提示词。试了几天发现没用——提示词越长模型越容易在后半段走样而且同样的内容换个任务就没法复用。后来我换了个思路把提示词升级成技能包。技能包不是一段话而是一个包含元信息、执行步骤、输出格式、校验规则的结构化文件。模型按需加载某个技能包就像工人拿到一张标准作业卡上面写明什么时候用、按什么顺序做、做到什么程度算完。这背后其实是把人怎么带新人的经验搬给模型。你带一个新人不会只说帮我把代码审一遍你会给他一张检查清单先看什么、重点查什么、结论按什么格式写。技能包干的就是这件事。1.3 这套框架解决了什么AI-Infra-Auto-Driven-SKILLS 把上面三个痛点对应拆成三个机制用推理协议约束步骤顺序解决步骤漂移用可复用的 SKILL.md 库沉淀经验解决失忆问题用强制校验和产物回填保证输出可验收解决做完但没做好。名字里的 Auto-Driven 不是营销词而是指技能包的自动触发机制模型先看任务描述再匹配技能包里的 when 条件命中后自动进入该技能的推理流程。你不需要每次手动粘贴提示词只需要把技能包放进指定目录并要求模型遇到对应场景必须加载剩下的由它自己驱动。2. 整体设计三层结构与运行机制2.1 技能定义层SKILL.md 就是最小单元这套框架的最小单位是一个技能包。每个技能包是一个目录里面必须有一个 SKILL.md 主文件可选的还有 examples/、scripts/、references/ 三个子目录。SKILL.md 的开头是 YAML Frontmatter相当于技能的身份证。我常用的字段包括 name技能名、description一段话说明这个技能干什么、when什么场景必须触发、version版本号。这些字段不是摆设——description 和 when 是模型判断要不要加载这个技能的依据写得不精确模型就会在错的时候用、该用的时候不用。examples 目录放案例比如一个技能包code-review里面可以放一份好的审查报告示例和一份差的审查报告示例。scripts 目录放可执行脚本比如自动跑 diff、自动统计变更行数的 shell 脚本。references 放详细规则文档只在技能主文件说要读时才被加载。为什么要拆目录而不全塞进 SKILL.md因为上下文窗口是稀缺资源。模型只要读技能主文件就能开工细节按需再翻 references这样每次消耗的 token 是固定的、可控的。2.2 推理编排层Plan-Execute-Verify 循环技能定义层解决做什么推理编排层解决按什么顺序做。我在框架里内置了一个五步推理协议所有技能都必须遵守RESTATE先用自己的话复述任务目标和验收标准不超过三行。这一步看着多余实际上能逼模型对齐意图避免自嗨式执行。DECOMPOSE把任务拆成子步骤预估每步产物。比如重构任务拆成定位调用点、改写核心逻辑、跑测试、更新注释。EXECUTE按拆解顺序逐步执行。每步执行前要声明我要做什么、读哪个文件、产出什么。VERIFY对照第一步的验收标准逐项检查。没通过就回到第 3 步重新执行并说明原因。RECORD把执行过程、关键决策、已验证的结果写回会话记录或日志文件供下次复用。这五步不是口号我在每个 SKILL.md 里都用代码块把这五步写死并要求模型严格按此协议执行不得跳步。实测下来加了这层后代理的完成率有明显提升尤其是重构和排查类任务很少再出现改完全套测试都没跑就宣布完成的情况。2.3 执行与反馈层产物校验和上下文回填第三层管的是收尾。很多任务失败不是执行时失败而是收尾时没人把关。所以我在框架里定了一条硬规则任何技能执行完毕必须产出三类东西——变更摘要、验证结果、遗留风险。变更摘要控制在 100 字以内说明改了哪几个文件、为什么改验证结果要写明跑了什么测试、结果如何不许写应该没问题这种话遗留风险是列出当前改动可能影响但没覆盖到的点。这套要求看着死板实际价值很大。它把 AI 的输出从一段话变成了一份可归档的记录你扫一眼就能判断这活儿干得靠不靠谱。同时RECORD 步骤会把每次执行的关键信息回填到项目目录下的 .ai-infra/state 文件里下次同一个技能被触发时模型能读到上次的执行状态相当于给了它一份短期记忆。3. 核心细节技能文件怎么写才不容易翻车3.1 SKILL.md 的骨架与 Frontmatter写技能文件最容易犯的错是把 SKILL.md 写成提示词。两者的区别在于提示词是解释给模型听的技能文件是约束模型执行的。所以技能文件里的每一个指令都应该是必须做什么、禁止做什么、做到什么程度算完而不是你可以考虑建议这类模糊表述。我自己的 SKILL.md 骨架长这样--- name: bug-hunt description: 根据报错信息/日志定位根因并给出修复建议 when: 出现异常堆栈、测试失败、线上报错或用户明确说帮我排查这个 bug version: 1.3.0 max_tokens: 8000 --- # Bug 排查技能 ## 执行协议 1. RESTATE复述 bug 现象与影响范围附上复现步骤或无复现步骤的说明 2. DECOMPOSE列出可能的根因假设按概率排序 3. EXECUTE逐条验证假设每验证一条必须给出证据日志行、代码片段、测试结果 4. VERIFY确认根因后给出修复方案和验证方式 5. RECORD记录根因、修复点、验证命令 ## 禁止事项 - 禁止在未读取实际日志/报错的前提下猜测根因 - 禁止只给修复建议而不给验证命令 - 禁止在无 P0 证据时同时修改多个文件 ## 输出格式 - 根因结论一句话 - 证据链必须带具体行号/文件名 - 修复方案按优先级排列 - 验证命令可直接复制执行注意 Frontmatter 里有个 max_tokens 字段这是我用来限制单个技能执行预算的。推理框架最怕的是模型在一个技能里无限循环设一个 token 上限超了就强制让模型总结中间结果并退出由人来决定是否继续。这个字段不是标准配置但我强烈建议加上。3.2 推理步骤的颗粒度另一个关键问题是步骤拆多细。拆太粗模型还是会自由发挥拆太细光读步骤就消耗大量上下文而且模型容易机械执行、失去判断。我的经验是步骤数量控制在 3 到 7 步之间每一步必须是有明确输入、有明确输出动作的不能是思考一下分析一下这种虚词。比如EXECUTE先读取 config.json 中的应用名再根据日志中的 traceId 过滤对应时段请求就是合格的步骤描述因为模型知道要读什么文件、处理什么数据、产出什么结果。判断颗粒度是否合适的标准很简单如果把每一步截图给你团队里的初级工程师看TA 能不能不用补充说明就照着执行。能说明颗粒度合适不能说明还要拆细。3.3 版本 v0.1.5 迭代了什么版本号这块我说下 v0.1.5 相对前几版的变化也能帮你看清框架的演进方向。v0.1.1 是第一版只有三个技能包code-review、refactor、test-writer和一个五步推理协议的说明书当时还是纯文本约定模型经常不遵守。v0.1.2 加上了 Frontmatter 的 when 字段技能触发率肉眼可见地上来了。这版也第一次验证了技能是目录不是单文件的价值。v0.1.3 引入了禁止事项块。起因是我发现 refactor 技能经常顺便改一堆无关代码加了 explicit 的 RED_LINE 列表之后这类问题少了很多。v0.1.4 做了上下文压缩优化把 references 目录独立出去主文件控制在 5KB 以内。v0.1.5 就是当前版本核心改动是把 RECORD 步骤规范化增加了 .ai-infra/state 状态文件让技能之间有状态衔接。这版开始你可以串起两个技能比如先 bug-hunt 定位根因再 refactor 修复重构中间的状态传递不需要你手动复制。4. 实操把这套技能库接进 Codex / Claude Code4.1 目录布局建议接入的第一步是定目录布局。我目前用的是这样的结构ai-infra-skill/ ├── SKILLS.md # 技能索引相当于目录总览 ├── protocol.md # 五步推理协议的完整说明 ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── examples/good-report.md │ │ └── examples/bad-report.md │ ├── bug-hunt/ │ │ ├── SKILL.md │ │ └── scripts/extract-logs.sh │ └── refactor/ │ ├── SKILL.md │ └── references/scope-rules.md └── state/ └── .ai-infra-state.jsonSKILLS.md 是给模型看的索引文件里面用表格列出所有技能包、各自的 when 条件、以及一句话说明。这样模型收到任务时只需要先读这个 2KB 左右的索引就能快速判断该加载哪个技能不用逐个打开每个 SKILL.md 去猜。4.2 接入 Codex 和 Claude Code 的两种方式两种工具对全局指令的加载方式不太一样但思路一致把协议文件和技能索引挂到它们的全局配置里让每次会话启动时自动读入。Claude Code 这边依赖 CLAUDE.md 这个约定文件。我在全局 CLAUDE.md 里写了这么一段# 全局工作协议 你必须在收到任务后执行以下判断 1. 读取 ai-infra-skill/SKILLS.md 索引 2. 若任务匹配某个技能的 when 条件加载对应 SKILL.md 并严格按其执行协议执行 3. 任何情况下执行顺序必须遵守 protocol.md 中的五步推理协议 4. 执行结束必须输出变更摘要、验证结果、遗留风险Codex 这边则是用自定义指令文件方式类似指向同一个目录。关键是别把 SKILL.md 全文塞进全局配置全局配置只放索引和协议引用具体技能按需加载。这一个设计决定能让你的日常会话 token 消耗稳定在一个合理水平。目录本身放哪都行只要路径写进全局配置。但如果你的项目里有多个仓库我建议做一个全局的 ai-infra-skill 目录而不是每个仓库各放一份否则版本同步会变成噩梦。4.3 第一个技能的完整演示我拿 v0.1.5 里面最常用的 code-review 技能举个例子方便你照着落地。触发场景是你要让代理审查一个变更。正常情况下你需要写一大段请帮我看看这几个文件的 diff重点检查……但接好技能库之后你只需要说一句review 一下当前分支的改动。代理会先读 SKILLS.md命中 code-review 的 when 条件加载技能包然后按协议执行1. RESTATE复述当前分支相对 main 的改动范围 2. DECOMPOSE列出要审的文件清单预估变更量 3. EXECUTE - 读取 git diff --stat 获取变更概览 - 逐文件读取 diff 与上下文 - 按正确性、可维护性、性能、安全四类维度记录问题 4. VERIFY核对每个问题是否有证据行号、调用链 5. RECORD将审查结论写入 state 文件标记为待处理最后输出的审查报告里每个问题都带优先级和证据P0 是必须堵住的P1 建议修复P2 可选项。这套流程跑下来比裸用代理时稳定得多基本不用你再追问这个风险你看了吗。5. 常见问题与排查实录5.1 技能加载了但模型不按步骤走这是我在 v0.1.1 时期遇到最多的问题现象是模型明明读了 SKILL.md但一到执行环节就自由发挥把步骤顺序打乱。排查后发现问题出在两个地方。一是 SKILL.md 里用了太多可以建议这类弱约束词模型默认把它当成参考而非命令。二是全局配置里只写了请阅读技能而没有写必须严格按其协议执行模型的理解是读一下就行。解决方式是把全文的弱约束词全部替换成必须禁止同时在全局配置里增加一条硬约束若技能文件与模型自身习惯冲突必须优先遵守技能文件。改完这两个点之后执行顺序的遵从率明显提升。5.2 推理链过浅或过深推理链过浅的表现是模型跳步比如 bug-hunt 技能里没看日志就猜根因。推理链过深的表现是模型在一个子步骤上反复尝试甚至在没有新信息的情况下重复读取相同文件。我针对浅的问题在技能里加了禁止在未读取实际日志/报错的前提下猜测根因这类硬约束针对深的问题加上了前面提到的 max_tokens 预算并且定义了一个证据充分即停止标准当某个假设已有两条以上独立证据支持、且没有反证时不得继续验证其他假设。5.3 上下文被技能描述挤爆接触这套框架的人常有的顾虑是技能文件会不会吃太多上下文。实际跑下来只要保证主文件不超过 5KB、按需加载 references 子目录上下文开销是可控的。真正容易爆的情况是模型把技能里的长命令输出、大段示例日志也当成了必须读取的内容。我在 references 目录里加了一条约定任何 reference 文件开头必须用一行说明什么场景才需要读我。同时技能主文件里的示例只保留结构示意不放大段真实日志。这样即使模型误读引用成本也是有限而不是灾难级的。问题现象排查方向解决方式技能不生效模型忽略 SKILL.md全局配置是否引用、when 是否匹配强化全局约束、精简单一 when 条件执行顺序错乱步骤跳变、先斩后奏SKILL.md 弱约束词过多换为必须/禁止声明优先级推理过浅跳过证据直接下结论缺少禁止项补充 RED_LINE 列表推理过深重复读文件、死循环无执行预算设 max_tokens 并定义停止条件上下文膨胀token 消耗异常高引用了大文件主文件限 5KB引用按需加载结果不可归档输出无法复用缺 RECORD 步骤强制 state 文件回填6. 我在维护这套框架时的一些体会从 v0.1.1 到 v0.1.5最大的感受是给 AI 编码代理做框架本质是在做约束设计不是在做功能设计。模型的能力已经够用真正决定产出质量的是你给它划的那条跑道——在什么情况下必须用什么流程、做到什么程度算完、哪些动作绝对不许做。每一条约束都对应一次踩坑删掉任何一条都有可能回归到模型自由发挥的失控状态。另一个体会是技能库的价值会随时间复利。第一周你可能觉得写技能比直接敲提示词还慢但当你积累了十几个技能包之后你会发现大部分重复性工作都能一句话触发标准流程而且每次执行的结果都是可对比、可追溯的。这个越用越省力的拐点大概在技能数量超过十个时出现。目前 v0.1.5 的下一步我在考虑给技能之间加一层依赖声明让一个技能能显式调用另一个技能并传递上下文而不是像现在这样靠 state 文件做弱衔接。如果你也在折腾 Codex 或 Claude Code 的技能化工作流建议直接从 v0.1.5 的目录结构开始别从零写协议——用现成的框架先跑通一轮再按自己的项目习惯去改会比闭门造车快很多。
阅读完成 · 觉得有帮助？
