大概八个月前我把自己的编码工作流从一个塞满各种小技巧的提示文档重构成了一套有版本号、有技能目录、有推理解析路径的工作流也就是现在的 AI-Infra-Auto-Driven-SKILLS v0.1.5。名字确实很长但核心解决的事情特别具体当你同时面对 Codex 和 Claude Code 这类有自主规划能力的编码代理时怎么让它们拿到同一个需求用同一套思考路径拆解而不是靠模型的临场发挥。先说结论如果你的需求是帮我把这个函数改成异步那么直接对话就够了上框架反而是负担。但如果你经常让编码代理处理跨多文件、有依赖关系、需要回归验证的任务比如升级依赖、重构模块、补测试那么一套技能目录 推理编排 执行钩子的工作流价值会立刻体现出来。这篇内容适合两类人一类是在两个 CLI 工具之间来回切换受够了行为不一致的工程师另一类是刚开始搭自己的编码代理基础设施、想少踩几个坑的人。下面我把 v0.1.5 背后的设计思路、实际落地步骤、走查案例和翻车记录都摊开写一写。1. 先说痛点编码代理不是不会干活是经常在错误的时机干活1.1 为什么多扔几个 Prompt 进去这条路走不通早期我做提示词资产的方式很朴素把几十个常用任务的指示写进一个大文档然后让编码代理任何时候都带着这份文档工作。听起来很完整实际上用起来很痛苦。第一个问题是上下文被大量无关指令占据代理在长会话里处理到一半往往会把某个任务的规则带入另一个任务第二个问题是任务路由完全靠模型自己猜同一个需求今天可能命中这个分支明天可能命中另一个分支输出稳定性很差。后来我把方案改成按需加载但很快就发现按什么依据来决定加载哪些指令比我预想的复杂得多。依赖升级的规则需要加载测试生成的规则也需要加载可如果两条规则同时命中代码风格约束又要听谁的这时候我才意识到缺的不是更多指令而是一个能让代理先想清楚再行动的固定框架。1.2 推理框架到底和普通提示词模板差在哪普通提示词模板是一份静态文本模型动手之前看一遍然后就进入正常对话了。推理框架则是把处理一个需求的过程拆成几个明确阶段每个阶段都有对应的输入、输出标准和检查动作。你可以把它理解成给代理装了一个内置的流程状态机它在每个阶段必须产出特定结构的内容才能进入下一阶段。在 v0.1.5 里我固定了五个阶段REP 代表重述需求ANA 代表分析任务类型PLAN 代表生成执行计划EXE 代表动手修改VERIFY 代表验证结果。这个编排层做的事就是强制代理在改代码之前先花几个输出 token 把问题边界拉清楚。很多人担心这会拖慢速度实际测试下来大部分简单任务只会增加不到两秒的延迟但复杂任务的返工率下降非常明显。2. 框架的骨架技能目录、推理编排、执行钩子三件套2.1 技能层一份跨 CLI 的技能规格整个框架最底部是技能目录层。v0.1.5 不是直接往各个 CLI 的配置文件里塞提示词而是先定义一套中立的技能规格文件再由同步脚本生成不同工具需要的格式。每个技能包含四个核心字段唯一标识、路由条件、执行指令、验证标准。其中路由条件是整套框架能跑起来的重中之重它描述的是什么任务该触发这个技能什么任务不该触发这部分写得越清楚技能路由准确率越高。下面是技能规格的一个片段我用依赖升级技能举例skills: - id: dep_upgrade name: 依赖升级与回归验证 triggers: include: [升级依赖, 更新 package.json, 处理 lockfile 冲突, 依赖版本过期] exclude: [新增依赖功能, 不涉及版本变更的普通修改] instructions: - 先读取当前依赖清单和锁定文件识别直接依赖与传递依赖 - 执行升级命令记录升级前后的版本差异 - 运行项目已有测试套件并针对升级包相关代码补测 - 输出变更报告标明需要人工关注的不兼容项 verify: - 锁定文件是否一致 - 测试是否全量通过 - 是否有未记录的版本变更这份规格本身不绑定任何 CLI 工具。Codex 环境下它可以生成一份独立 markdown 文档Claude Code 环境下则生成对应的 SKILL.md。这种设计让维护成本大幅降低改一次规格两个环境同步生效。2.2 编排层五个固定阶段每个阶段都有输出要求技能层解决的是每种任务该怎么干编排层解决的是代理该按什么顺序想问题。v0.1.5 里我把编排层的提示词做成一段固定注入文本要求代理在每个工作流周期里按 REP、ANA、PLAN、EXE、VERIFY 顺序输出。这五个阶段各自的职责可以看下面这张表阶段核心动作必须包含的输出常见跳过后果REP用自己的话重述需求明确的任务边界、涉及文件列表遗漏非典型文件只改表层ANA给任务分类命中的技能 ID、不命中其他技能的理由多技能互相抢规则输出漂移PLAN编写执行计划按依赖关系排序的操作步骤先改依赖后改代码编译不过EXE执行修改对应技能指令的具体落地无VERIFY验证结果测试结果、变更清单、遗留风险改完不测或者只测了冒烟这段编排文本本身像一张表格但实现时不是让模型输出表格而是要求它把每个阶段压缩成一到三行短句。一开始我把每个阶段写得很复杂结果模型花大量时间在写计划而不是执行后来把所有阶段都改成够用即可的输出规格效果反而稳定多了。2.3 执行钩子层把验证动作固化到工作流边界上纯粹靠提示词让模型自律上限很有限。v0.1.5 里我在工作流边界上加了一些轻量钩子主要做三件事第一在 EXE 阶段开始前自动检查当前分支的工作区状态避免代理在一堆未提交改动里叠新改动第二在 VERIFY 阶段调用预设的验证命令集比如测试、构建、锁文件一致性检查第三把每次工作流的阶段输出追加到独立的日志文件方便事后退查。钩子层的位置很讲究不能放在代理每说一句话都触发的位置那样会频繁打断思路而要在阶段切换时触发。v0.1.5 的实现方式是让代理在阶段输出里带一个特定标记行外部脚本监视输出流碰到标记就执行对应的钩子。这种方法有轻微延迟但胜在不需要改 CLI 本身的行为通用性更强。3. v0.1.5 的双端落地在 Codex 和 Claude Code 里分别怎么接3.1 同步机制一份技能源两个 CLI 各取所需很多人在 Codex 和 Claude Code 之间反复横跳最容易崩溃的就是两边的技能写法完全不同。Claude Code 有相对成熟的 Skill 目录格式Codex 则主要靠项目级指令文件里的索引来触发按需加载。v0.1.5 用一个小脚本把这层差异抹平了。技能源文件是一个 YAML脚本读取后分别生成两个目标# sync_skills.py 的简化逻辑 import yaml from pathlib import Path with open(skills.yml) as f: data yaml.safe_load(f) for skill in data[skills]: # 生成给 Claude Code 的 SKILL.md claude_path Path(.claude/skills) / skill[id] / SKILL.md claude_path.parent.mkdir(parentsTrue, exist_okTrue) claude_path.write_text(build_claude_skill(skill)) # 生成给 Codex 的独立技能文档 codex_path Path(docs/skills) / f{skill[id]}.md codex_path.write_text(build_codex_doc(skill)) # 再生成 AGENTS.md 里需要追加的技能索引段落 append_codex_index(data[skills])这一步看起来平平无奇但它是整个 v0.1.5 能双端共存的基石。没有这个同步层之前我经常在 Codex 里调好了技能转头在 Claude Code 里忘了补一份行为分裂到让人崩溃。3.2 Codex 端AGENTS.md 只写索引技能文件按需展开很多人在 AGENTS.md 里越堆越多恨不得把整个团队的编码规范都写进去。我的建议是反过来的AGENTS.md 里永远只放骨架和索引具体技能内容放 doc 文件等命中需求时再让代理去读取。这样做的原因很简单AGENTS.md 的内容几乎全程在上下文里它有 2000 字就相当于白白占了 2000 字越臃肿代理越容易忽略关键信息。我在 AGENTS.md 的末尾加了这样一段索引## AI-Infra-Auto-Driven-SKILLS v0.1.5 技能索引 当任务是以下类型之一时先完整读取对应技能文档再开始规划 - dep_upgrade: docs/skills/dep_upgrade.md - test_gen: docs/skills/test_gen.md - refactor_module: docs/skills/refactor_module.md 读取技能文档后按 REP-ANA-PLAN-EXE-VERIFY 的顺序输出并执行。这套机制能在 Codex 里生效靠的是代理先看到索引再自主决定读取哪个文档。只要技能文档的标题和开头说明足够清晰代理的文档拉取准确率相当高。3.3 Claude Code 端Skill 目录里最容易忽略的两个约定Claude Code 端相对标准每个技能放在.claude/skills/技能ID/SKILL.md。这份文件由两部分组成YAML frontmatter 里的 name 和 description以及正文里的指令、示例和验证清单。frontmatter 的 description 特别重要因为它是技能路由的依据模型就是靠它来决定当前任务要不要激活这个技能。我写的一个典型 SKILL.md 长这样--- name: dep_upgrade description: 当用户要求升级项目依赖并做回归验证时使用。触发条件包括版本号变更、锁文件处理、依赖冲突解决。如果任务不涉及依赖版本变动切勿使用此技能。 --- # 依赖升级与回归验证 ## 执行步骤 1. 读取依赖清单与锁定文件标记直接依赖和传递依赖 2. 执行升级操作记录升级前后版本差异 3. 运行全量测试针对性补测升级包相关用例 4. 输出变更报告标注兼容性风险 ## 验证清单 - [ ] 锁定文件与清单文件一致 - [ ] 全量测试通过 - [ ] 无未经确认的版本跳跃有两个约定是最容易踩的。第一个是 description 里必须写不触发条件只写触发条件的话代理会把很多相邻任务都路由进来。第二个是正文首行不要写你是一个专家这类废话直接写执行的第一个动作模型在激活技能后需要极快地进入干活状态情绪铺垫没有任何价值。3.4 装好之后的第一件事写一个最小技能验证路由接入完成的验证方式不是直接拿真实项目试而是先做一个一比一的最小案例。我当时的做法是建一个只有两个文件的小仓库一个技能是给函数补 JSDoc另一个技能是把函数改为 async。然后给同一段代码发同一个需求观察两个 CLI 是否正确只命中一个技能、是否输出了完整的五个阶段、是否在技能激活时读取了正确文档。这个验证过程帮我提前发现了大量路由和提示词写法问题。如果你跳过了这一步直接在大型仓库里用出了问题很难分清是技能写得不对还是仓库本身的复杂度干扰了代理的判断。4. 完整走查一次依赖升级需求是怎么被框架拆解执行的4.1 REP 和 ANA动手之前的两个刹车拿一个真实场景走查一下。某仓库里某依赖版本落后我向代理发出指令把某个工具库从 3.x 升到 4.x跑一遍测试看看有没有破坏性变更。按框架要求代理第一步先输出 REP。它会把需求重述为需要修改依赖声明文件、锁定文件以及与之相关的引用代码目标是测试通过且无隐藏破坏。REP 写的不是复述原话而是把任务边界列清楚比如该需求不涉及更新其他无关依赖。第二步是 ANA代理需要输出对任务类型的判断。它会把命中技能 dep_upgrade 的关键词列出来同时说明为什么没有命中 test_gen 和 refactor_module。这一阶段看起来有点浪费但我实测下来它大幅减少了多技能指令打架的概率。没有 ANA 的时候代理经常把测试生成技能里的补测试要求和依赖升级技能里的回归规则混在一起执行最后产出一堆互相矛盾的改动。4.2 PLAN 和 EXE计划要细到能够自查执行要严格限定范围进入 PLAN 阶段后代理会生成按依赖关系排序的执行计划通常是三步先升级声明文件里的版本号再更新锁定文件接着运行现有测试定位失效用例。这个计划的好处是代理在 EXE 阶段不会想一出是一出。我设定过一个规则如果 EXE 过程中发现实际改动和 PLAN 偏离超过一个文件就必须停下来重写 PLAN。EXE 阶段还有一条很重要的纪律代理不能顺手修改与任务无关的代码。很多编码代理表现出色时会顺手做点自认为应该的重构比如把某个旧 API 用法换掉这往往是回归 bug 的温床。框架在 EXE 阶段加入了提示词约束同时在钩子层检查了变更文件列表避免越界修改。4.3 VERIFY 阶段的闭环允许自动回退但必须有记录VERIFY 阶段做的第一件事是全量测试。第二件事是对照技能文档里的验证清单逐项核验比如锁定文件是否一致、是否存在未经确认的版本跳跃。第三件事是生成变更报告把升级前后的版本差异和对测试的影响整理成可阅读的摘要。这里我说一个实际经验VERIFY 发现测试失败时可以让代理尝试自行修复一到两次。v0.1.5 的做法是给代理授权一次回退回退前必须保存当前改动为补丁文件这样即使自动修复失败人力介入时也有完整现场。多数依赖升级导致的测试失败其实是某个 API 在新版本里改名或删除代理有能力顺着编译错误找到新 API 并修复但要给它一个明确的边界防止它在修复中无限发散。5. 实测翻车记录六个最值得写的坑5.1 技能描述写得太详细路由准确率反而下降这是我最开始犯的错。我以为 description 越详细模型判断越准于是把触发条件写了好几段还带各种例子。结果代理在简单任务上频繁误触发开始用升级依赖的思路去处理不相关的改动。排查过程很有意思我把同一个技能分别用短描述和长描述做了对照测试短描述版本的路由准确率更高。后来我想明白了技能路由本质上是模型在做语义匹配描述太长会引入大量噪声反而干扰匹配置信度。v0.1.5 的规则是description 只保留核心触发词、明确的排除条件、一句话任务目标详细步骤全部放在正文里。5.2 五个阶段的输出要求模型总在简单任务上跳过框架搭好之后我发现一个规律复杂任务模型还会按阶段来简单任务基本上一句话就带过了。刚开始我以为是提示词没生效后来发现这是很多编码代理的自然倾向任务越简单它越觉得没必要走流程。解决方式不是强行禁止跳过而是把阶段输出格式设计成压缩态允许用极短标记表示。比如 REP 可以压缩成REP: 升级工具库依赖并验证兼容性ANA 可以压缩成ANA: dep_upgrade。对简单任务整个框架加速变成了三行文本对复杂任务模型会自然展开成多行。这种弹性设计比强制输出要好因为强制格式只会让代理产生一堆敷衍的空话。5.3 同一个技能在两个 CLI 里的表现不一致Codex 端和 Claude Code 端用的是同一份技能规格同步生成的文件但实测发现某些技能在 Codex 里执行正常在 Claude Code 里却总是少了验证步骤。后来定位到问题根源两边的知识库对技能文档的主次顺序理解不同。Claude Code 端会优先看 SKILL.md 的 frontmatter 和后文结构Codex 端则更看重文档开头两段。修复方案是让同步生成器针对两个 CLI 调整了文档排版权重把执行指令在不同位置的强调程度做了差分处理。这算是一个平台差异的隐性坑如果你自己搭了同步层一定要为每个 CLI 单独做一轮文档结构适配。5.4 上框架之后上下文开销不降反升问题出在日志钩子我最初把执行钩子的日志设计得特别详尽每个阶段都记录长文本还要求代理在阶段切换时输出一些思考过程。结果这些日志和思考过程全部占用了上下文窗口一个中型任务还没做完上下文就已经过半了代理的行为开始明显退化。后来我把日志内容做了两级降级内部强制记录改成仅记录标记行详细内容写入外部日志文件阶段思考过程的详细度从默认完整缩减为默认两行只有复杂任务才允许展开。这个改动之后上下文开销才真正降到比无框架时代更低。记住一个原则框架的价值在于帮助代理少走弯路而不是制造额外的上下文负担。5.5 技能之间的依赖链处理不好就会互相污染v0.1.5 里有相当一部分任务是组合型的比如先重构模块再补测试。独立跑这两个技能都没问题串行执行时就会出现指令重叠的冲突代理会同时遵守重构技能里的代码风格约束和测试技能里的用例命名规则反而两边都不彻底。我的处理方式是给每个技能声明前置技能和后置技能并且在编排层增加一条规则当前一个阶段命中了两个技能时PLAN 必须明确划分它们的作用范围和交接条件。目前这套机制只处理了一层的链式依赖递归依赖设计得还不够好这也是我准备在下个版本重点优化的方向。5.6 代理反过来修改技能文件需要设一道安全边界这个问题很有意思。框架跑得越久代理对技能文件的熟悉度越高于是有几次它在处理任务时顺手把技能文档里的步骤改成了它认为更好的版本。从内容上说不一定是坏事但在没有评审的情况下技能文件被模型擅自改动整个工作流的稳定性就无法保证了。我在同步脚本里加了一步校验把技能文件视为只读资产执行前对比哈希值检测到改动就提示冲突并回退所有改动。真正想迭代技能的开发者不应该依靠模型在任务执行中偷偷改配置而应该回到 yaml 源文件显式调整再跑同步脚本生成所有端。把变更流程收拢到单一入口是维护这类基础设施的一个重要原则。6. 什么场景值得上这套框架以及后续迭代的方向6.1 适合与不适合的画像经过这段时间的实测我对这套框架的适用边界有了比较明确的判断。它适合的是需要稳定复现、多步骤、涉及验证的工程任务包括依赖升级、模块重构、批量调整代码风格、生成和补齐测试等。它也适合那些需要多个编码代理协作的场景至少代理之间能共享同一套任务拆解语言不至于各想各的。它不适合的场景也很明确零散的问答、一次性小改动、原型验证和探索式编程。在这些场景里框架的强制结构会让代理显得笨重而且容易扼杀那种发散式的探索过程。我自己的策略是维护两套配置默认轻量模式不带推理框架接到复杂任务时再显式激活技能集。这种模式切换的配置字段也是 v0.1.5 在双端都保留的。6.2 v0.2 的三个准备方向路由指标、技能注册表、评审链路下一步迭代我主要想解决三个问题。第一个是给技能路由加一个可观测层把每次任务的命中技能、最终是否成功、上下文开销记录下来用真实数据来调整技能 description 和触发条件。目前很多调整还是靠感觉我不太满意。第二个是设计一个技能注册表的入口让同一个技能可以带版本号同时存在切换版本时能对比行为差异。第三个是技能变更的评审链路在源文件变更后生成 diff并附带一次评审测试只有通过才更新到双端。如果你在我这种工作流里投入很多我个人觉得这三块会是下一个阶段的标配。技能资产不该是一堆一次性提示词而应该像代码一样有版本、有测试、有可追溯的变更记录。这套思路说穿了不复杂难的是在每个小细节上坚持做结构化把它做成基础设施而不是临时拼接的脚本。最后分享一个我现在还在用的习惯每加入一个新技能我都会强迫自己先用最小案例跑通双端再放进真实仓库。这个习惯看着慢实际上它帮我省掉的返工时间远远超过那几分钟。如果你也想复刻整套框架不妨从一两个最常做的任务类型开始跑通路由和双端接入再逐步扩充技能目录。