★ FEATURED ARTICLE Codex 和 Claude Code 这类 AI 编程助手用久了你一定会撞上同一个尴尬简单需求一句话就能搞定可一旦任务复杂起来它们就频繁“失控”——拆解不清、改错文件、跑完不验证甚至中途开始自说自话。这套 AI-Infra-Auto-Driven-SKILLS 推理框架工作流就是我为了解决这个问题持续迭代的一套方案目前版本是 v0.1.5。简单说它是一份“技能库 推理流程”的组合把 AI 干活的方式从“自由发挥”变成“照着 SOP 执行”让 Codex 和 Claude Code 在复杂任务里也能稳定交付。如果你也在被 AI 的“不可控”折磨这篇内容值得读完。1. 项目动机与核心思路拆解1.1 复杂任务失控不是模型不行是缺流程先说一个我踩过无数次的坑。早先让 Claude Code 处理一个带数据库迁移的后端重构它第一轮就给出了非常漂亮的计划标题、步骤、风险点齐全我当时心里还挺美。结果执行到一半它忽然跑去调整了一个完全无关的配置文件然后因为那个文件报错又花了两轮对话在“修复”自己制造的问题。最后任务倒是完成了但我额外多花了四十分钟做代码审查和回滚。这不是个别现象。Codex 和 Claude Code 对短任务的处理能力很强但任务一旦超过三步、涉及多个文件、牵涉到外部状态进程、端口、数据库它们就很容易出现三种典型问题一是目标遗忘做到后面不记得最初要什么二是领域漂移越改越偏离需求甚至开始“自创需求”三是验证缺失改完代码不跑测试、不查语法直接宣布完成。问题不在模型本身而在缺少一套结构化的执行约束。好比一个新员工能力很强但你只丢一句“把这个项目搞定”给他他大概率也会乱来。给方法、给步骤、给检查清单才能把能力用在正确的方向上。AI-Infra-Auto-Driven-SKILLS 的核心思路就是用一套明确的工作流和技能定义把这些约束“外挂”给 AI让它的每一步都有依据、有检查、有反馈。1.2 技能库与推理框架双轮驱动的设计逻辑整套工作流拆成两个互相咬合的部分。SKILLS 层解决“AI 会做什么”的问题。它把常见的工程任务——代码审查、缺陷修复、重构、写测试、生成文档——封装成一个个结构化的“技能包”。每个技能包里包含触发条件、执行步骤、约束规则、验证方式和输出格式。AI 在干活时不再是凭空推理而是像查手册一样调用一个已经定义好的流程。推理框架层解决“AI 该怎么想”的问题。它是一套引导模型思考的流程告诉 AI 拿到任务之后要先做什么、再做什么。具体包括五步理解上下文、拆解任务、匹配技能、执行并验证、沉淀复盘。SKILLS 层负责“怎么做”推理框架层负责“做什么、为什么做”两者缺一不可。这个设计和人类团队运作是同一个逻辑。团队里既要有明确的岗位职责对应技能库又要有项目管理流程对应推理框架。有职责没流程协作会乱有流程没职责执行会空。这套工作流就是把这两样东西同时交给 AI。1.3 v0.1.5 版本定位从“能用”到“能用得稳”v0.1.5 这个版本号很有代表性——不是 1.0说明这套框架还没到盖棺定论的时候但也不是 0.1说明核心骨架已经跑通过了。这个阶段做的事情总结起来是三件事。第一把推理框架的五阶段流程固定成可复用的模板不再每次手工编写。第二技能库从最初的三四个基础技能扩展到十几个覆盖开发中更常见的场景。第三针对 Codex 和 Claude Code 两种环境做了适配层优化——两者在上下文处理、指令执行方式上差异很大同一套技能在不同工具里要微调才能发挥最大效果。这个版本解决的最核心痛点是“稳定性”。功能可以少但已有的功能必须每次都能生效。实测下来这套 v0.1.5 在跨文件重构、遗留代码接入测试、批量修改后回归验证这三类任务里表现最稳定。2. 推理框架核心设计五阶段工作流2.1 阶段一Context-First 需求解析大部分 AI 编程任务翻车的起点都在于“没看清楚就开始动手”。我早期用 Codex 时发现一个规律只要我给的指令里信息不完整它就会立刻“脑补”而且脑补的内容经常和项目实际结构对不上。所以这套框架的第一阶段强制要求 AI 在执行前先做上下文收集。具体动作包括三个扫描项目文件结构搞清楚代码目录和模块划分搜索与任务相关的关键词定位需要修改的文件读取关键文件的开头注释和现有测试理解模块约定。这个阶段我用一个简单规则约束在未完成上下文收集之前禁止输出任何代码。相当于人类开会时先“对齐信息”再讨论方案。实测这个规则能减少大约六成“改错文件”的低级错误。2.2 阶段二WBS 任务拆解上下文收集完毕进入任务拆解。框架要求 AI 使用类似 WBS工作分解结构的方法把任务逐级拆到“叶子节点”。叶子节点的标准是能由一个技能独立完成且执行结果可以验证。举个例子需求是“给登录接口增加验证码校验”拆解结果大致是这样修改接口入参定义、补充验证码校验逻辑、更新接口文档、新增验证码相关的单元测试、运行全量测试确认无回归。每个叶子节点都是一个可独立执行、可独立验证的单元。拆解这一步有两个要点。一是每个叶子节点必须包含明确的“完成定义”否则 AI 会在“做完”和“做对”之间摇摆。二是拆解顺序应该遵循“先改依赖、后改被依赖最后回归验证”的原则避免一次修改多个相互影响的地方。2.3 阶段三技能路由匹配有了任务清单之后AI 需要为每个叶子节点选一个技能执行。这一步我称之为“技能路由”——本质上是一个匹配过程就跟路由器根据目标地址转发数据包一样。路由规则首先是精确匹配任务里出现的关键动作重构、审查、调试、写测试等直接对应技能库中同名技能。如果找不到匹配就走规则兜底根据任务的标准产物来推断——需要产出测试用例就启用测试编写技能需要修改数据表结构就启用数据库变更技能。这个阶段有个容易掉进去的陷阱AI 倾向于“自创技能”。它可能不知道该怎么执行某个任务然后现场编一套流程。v0.1.5 的约束是技能库中不存在的任务类型一律走“最小手动路径”—— AI 先明确告知用户“我没有该技能”然后按用户的补充指令执行。这样可以避免 AI 自作主张地“发明”一个不靠谱的流程。2.4 阶段四执行与验证闭环每个叶子节点在执行后都必须经过验证。这个验证不是走形式而是有一套硬性的检查方法。代码变更类任务至少要做三项检查语法编译检查、相关单测运行、影响面扫描。文档类任务要检查格式规范、链接有效性、术语一致性。配置类任务要检查配置项合法性、变更文件是否遗漏、与默认值的差异。验证失败的情况下框架强制执行“回溯机制”—— AI 必须回到当前叶子节点的执行起点重新分析失败原因然后修正后重跑。如果连续两次失败则必须暂停把问题反馈给用户而不是无限循环重试。这条规则尤为重要它防住了 AI 最让人头疼的行为同一个错误反复犯每次都说着“我再试一次”实际是用同样的方法撞同一堵墙。2.5 阶段五复盘与技能沉淀这是整套框架里最容易被忽略、但长期价值最高的一步。任务完成后AI 需要输出一份简短的复盘记录包括实际执行步骤与计划的偏差、遇到的问题及解决方式、可供沉淀的经验。如果是新类型的任务AI 还会根据这次执行过程生成一个新的技能草稿追加到技能库中。这个机制让整套框架用一种“经验累积”的方式自我进化。v0.1.5 新增的几项技能就是之前某个线下项目任务结束后复盘生成的。复盘环节还有一个作用为下一次任务提供“记忆”。很多 AI 编程工具本身没有跨会话的持久记忆但通过把复盘记录写入项目文件下次任务启动时推理框架第一步就能读这些记录来了解项目的“历史坑点”。这等于给 AI 加了一份项目专属的长期记忆。3. SKILLS 技能库的实操解析3.1 技能定义的结构化格式技能库里的每个技能都是一份结构化定义文件我用 YAML 编写。字段设计上借鉴了函数式编程的思路——每个技能像是一个带输入、输出和执行逻辑的“函数”。一个典型的技能定义长这样name: fix_bug description: 根据错误信息定位并修复指定缺陷 trigger: 出现报错/异常/Bug/缺陷等关键词 inputs: bug_description: 错误信息的文字描述 reproduce_steps: 复现路径可选 execution: - step: 解析错误堆栈定位出错文件与行号 detail: 先读堆栈不要猜 - step: 检查相关变量与上下文 detail: 找到错误根源不要只修表面 - step: 实施修复控制修改范围 detail: 单次修复只动最小集 - step: 运行相关测试验证 detail: 必须执行禁止跳过 verification: - 编译或语法检查通过 - 相关测试用例全部通过 - 修改范围与任务描述一致 output: - 修改文件列表 - 修复原因说明 - 验证结果记录字段的含义很直观trigger 定义什么情况下该调用这个技能execution 是步骤清单每个步骤还带着“为什么这么做”的说明verification 是硬性检查项防止 AI 跳过验证直接交付output 规定了任务完成后的输出内容避免 AI 只丢一句“改好了”。3.2 三个实战高频技能拆解v0.1.5 的技能库里使用频率最高的是三个技能代码审查、跨文件重构、回归测试。代码审查技能的核心不是“看代码有没有 bug”而是固定一套审查维度。执行时按顺序检查接口变更是否兼容、异常处理是否完善、并发场景是否存在竞态、新代码是否符合项目现有风格。每个维度都是一条 prompt 指令避免 AI 凭感觉随机翻代码。跨文件重构技能的设计重点是“增量式搬迁”。它强制要求每次只移动一个文件或一个函数并且每一步都运行编译检查确保中间状态可用。我最开始写这个技能的时候把它设计成“整体替换式”——一次重命名一条链路的所有文件结果中途报错也不知道是哪一步引入的回滚都麻烦。后来改成增量式稳定性大幅提升。回归测试技能的作用是在一次较大范围代码改动之后自动识别受影响模块并匹配对应的测试用例。它比简单“运行全量测试”更高效——全量测试在很多中型项目上要跑一两个小时而这个技能可以只挑出与改动相关的几十个用例把验证时间压缩到几分钟。3.3 技能路由表设计为了让 AI 在路由阶段能快速做出选择我在项目里维护了一张技能路由表。它不是给用户看的说明文档而是直接喂给 AI 的映射规则。任务类型触发关键词路由技能默认输出产物代码审查review, 审查, 检查代码code_review审查报告清单缺陷修复bug, 报错, 异常, 崩溃fix_bug修复说明 验证结果跨文件重构refactor, 重构, 重命名cross_file_refactor增量变更记录测试编写test, 测试, 覆盖test_writer测试代码 覆盖率报告文档更新doc, 文档, READMEdoc_updater文档变更 diff数据变更migration, 迁移, 数据库db_migrator迁移脚本 检查记录配置排查config, 配置, 环境变量config_debugger配置差异分析 修复步骤路由表的好处是让 AI 的决策过程可预测。同一类任务进来永远走同一条路线不会这次选技能 A、下次选技能 B导致行为不一致。3.4 上下文管理技能文件的加载策略技能库越来越大的时候一个新问题出现了如果每次对话都把十几个技能的完整定义塞进上下文很容易把窗口撑爆反而影响 AI 对真正关键信息的注意力。我的解法是“分层加载”。第一层是一个约 300 字的技能索引只列出技能名称和一句话说明常驻在 AGENTS.md 中。第二层是完整技能定义存放在 skills/ 目录下按文件名组织。AI 在路由阶段拿到任务关键词后再去读取对应技能文件的完整内容。这样上下文里始终只保留当前真正用到的技能细节而不是全量加载。实测下来这种加载方式比全量灌输要稳得多。上下文窗口不被冗余信息占满关键指令的生效概率明显提高。4. 在 Codex 和 Claude Code 中的落地配置4.1 环境初始化与目录结构一套工作流再完善如果接入环境的配置太复杂用两次就会放弃。v0.1.5 做了不少简化目前的初始化只需要三步。第一步在项目根目录创建 skills/ 目录把所有技能定义文件放进去。第二步在项目根目录放置一个 AGENTS.md 文件Claude Code 环境下也可以命名为 CLAUDE.md里面写入推理框架五阶段流程的提示词和技能索引。第三步在 AGENTS.md 末尾附加一条规则任务启动后先读取技能索引再根据路由表按需加载技能文件。目录结构大致如下project_root/ ├── AGENTS.md ├── skills/ │ ├── code_review.yaml │ ├── fix_bug.yaml │ ├── cross_file_refactor.yaml │ ├── test_writer.yaml │ ├── doc_updater.yaml │ └── ... ├── memories/ │ └── project_history.md └── src/memories/ 目录放着每次任务结束后的复盘记录。这是我自己加的一个设计——Codex 和 Claude Code 本身没有内置跨会话记忆但通过读写这个文件AI 能回忆起上一个会话踩过的坑。4.2 推理框架的核心提示词模板推理框架流程不是靠程序实现的而是靠一段结构化的系统提示词来约束模型。v0.1.5 里的核心模板精简后的大致内容是这样的你是一个遵循工作流执行任务的 AI 工程师。 任务开始后必须按以下五个阶段推进 1. Context-First: 扫描项目结构收集与任务相关的上下文禁止在收集完成前动手写代码。 2. WBS 拆解: 将任务拆成可独立执行的叶子节点每个节点必须有明确的完成定义。 3. 技能路由: 为每个叶子节点从技能库中选择一个技能技能不存在时先询问用户禁止自创流程。 4. 执行与验证: 按技能定义逐步执行每步完成后必须执行验证验证失败时回溯重试同一问题最多重试两次。 5. 复盘沉淀: 输出执行报告将新增经验写入复盘记录文件。 全局约束: - 修改代码前先说明修改原因 - 每次变更范围应控制在最小集 - 禁止跳过验证步骤 - 遇到不确定的信息时先询问不要假设这段模板真正起作用的点在于它把“反 AI 直觉”的规则写进了系统提示词。AI 的天性是尽快生成内容但这段提示词反复强制它“先收集、再拆解、后执行”相当于给它的回答速度踩了刹车。4.3 Codex 与 Claude Code 的适配差异同一个模板在 Codex 和 Claude Code 里的表现并不完全一样这个我实测过很多轮。先说差异再给适配方案。Codex 环境更适合“短促、单线程”的指令节奏。它对一长段系统提示词的遵循度不够稳定如果五个阶段一次全丢进去它经常会在执行到第三阶段之后遗忘先前的规则。我的做法是把模板切成几段分别在关键节点重复注入——比如在执行阶段开始前再单独强调一次“必须先验证再下结论”。Claude Code 的长对话记忆能力强一些整段模板它能基本守住。但它的问题是“过于顺从”如果任务在技能库里找不到对应项它倾向于自行发挥而不是停下来询问。因此在这套环境里需要把“技能不存在时必须询问”的约束用更强的语气写两遍。还有个实操细节Codex 和 Claude Code 对 AGENTS.md 的读取时机不同。Codex 倾向于在会话开始或执行工具调用时读取文件Claude Code 则会在每次对话时自动加载。如果修改了技能文件Codex 环境需要重启会话才能生效Claude Code 通常下一条消息就能刷到变更。4.4 一键校验工作流的自检命令接入新项目时我习惯先跑一遍“自检模式”来确认框架有没有被正确加载。做法是给 AI 下发一条固定指令运行技能自检先列出你能从 skills/ 目录中找到的技能列表再按顺序输出推理框架的五个阶段名称。不要执行其他任务。如果 AI 能准确列出技能清单和五个阶段说明框架加载正常如果它答不上来或开始自由发挥那大概率是 AGENTS.md 没有被正确读取。这种自检动作几秒钟就能完成但在每次接入新项目时能省下后面一长串调错的痛苦。5. 常见问题与排查技巧实录5.1 技能文件被忽略索引先行我在某个项目里遇到过一个很怪的现场AGENTS.md 里写了技能路由表skills/ 目录里也放了完整的技能定义但 AI 执行任务时完全无视这些文件自顾自地工作。排查了半天发现原因是在 AGENTS.md 的开头我先写了一段项目简介技能路由表的说明放在比较靠后的位置。AI 在处理长文件时对前后内容的关注度是不同的——前几百字是“注意力高区”后面的内容容易被弱化。解决方法是把技能索引和“先读取技能库”这条规则放在 AGENTS.md 最顶部项目简介等描述性内容往后放。调整之后AI 对技能的遵循度立刻上来。这个顺序问题很隐蔽也是我在排查了好几个项目之后才总结出来的规律。5.2 上下文溢出与关键规则遗忘当项目文件多、任务链条长时对话上下文会越来越臃肿。AI 后期经常忘记早期注入的约束规则比如“禁止跳过验证”“最小改动”这些。预防方案是“分段刷新”。我不用“全局规则只提一次”的策略而是在每个技能定义的开头重复一次核心约束。比如 fix_bug 技能里单独写上“修复完成后必须运行测试”这个约束就不会因为对话变长而被遗忘。分散强化比集中灌输要有效得多。如果真的发生上下文溢出最务实的做法不是继续对话而是开启一个新会话然后在第一条消息中让 AI 读取复盘记录文件和技能索引重建上下文。用几分钟的“重新加载”换回后半段任务的稳定执行这笔账很划算。5.3 推理流程“跑飞”无限循环与自嗨AI 在某个任务上失败后最让人头疼的状态就是“自嗨循环”。同一段错误重复修每次都假装分析出“新的根本原因”实际还是在原地打转。我是在加了“连续失败两次必须暂停”这条硬性规则之后才彻底解决这个问题。这条规则直接写进了核心模板并且在执行阶段又重复了一遍。实测效果很好——AI 不再闷头瞎试而是会主动把问题抛回给我“以下是我两次修复失败的原因需要你确认是继续尝试还是更换方案。”这个方法背后的逻辑很简单AI 的行动成本极低、试错不心疼所以很容易陷入无效重试。给它设定一个“熔断阈值”本质上是用规则约束它的消耗把决策权交还给人类。5.4 版本迭代中的兼容性维护每次技能库升级我都会检查旧项目里的 AGENTS.md 是否需要同步更新。v0.1.5 版本为了保证向后兼容在技能文件命名上加了命名空间前缀比如 fix_bug 保持原名而新增的技能用带版本前缀的名字存放。这样旧项目即使不更新也能正常使用原有的基础技能。技能升级还有一个原则值得分享改进现有技能时不要直接覆盖原文件而是在原文件里新增一个“v2 执行路径”并保留原路径作为默认路径。等新版路径在多个项目中验证稳定后再切换默认值。这种灰度切换方式让我避免了好几次“升级技能反而把原有稳定行为改坏了”的尴尬。从 v0.1 迭代到 v0.1.5这套工作流帮我解决的最大问题是让 AI 编程助手从“聪明但不可靠”变成了“按部就班但稳定交付”。这个过程里最核心的体会是约束不是限制而是生产力。给 AI 写清晰、可验证、带熔断机制的流程效果比单纯换更强的模型要明显得多。如果你也在用 Codex 或 Claude Code 处理复杂任务可以先把一个项目的复盘记录沉淀成技能草稿再逐步扩展成自己的技能库——你会发现AI 的可靠性不是靠运气而是靠设计出来的。
阅读完成 · 觉得有帮助？
