AI-Infra-Auto-Driven-SKILLS：为Codex与Claude Code构建推理框架工作流

如果你手头同时有 Codex 和 Claude Code 两套 AI 编程入口大概率遇到过这种糟心事任务本来不大模型却闷头写了半天方向偏了才回头跟你汇报或者一个三分钟能改完的小逻辑被它生生扩展成了跨模块重构。我最初以为是自己 prompt 写得不够好后来才发现问题出在缺少一套“推理框架工作流”来约束 AI 的任务处理路径。我做的这套东西就是标题里那串名字AI-Infra-Auto-Driven-SKILLS当前版本 v0.1.5。它是一套面向 Codex / Claude Code 的技能与推理配置体系核心目标是用一组 Markdown 协议文件让 AI 在动手写代码之前先完成“任务解读、证据检索、方案验证、技能加载”这几步强制动作。说白了就是把一个成熟工程师接到需求后的思维习惯固化进 AI 的工作流程里。文章面向两类人一类是天天跟 Codex 和 Claude Code 打交道的开发同学想让 AI 在真实项目里更可控、少返工另一类是做团队 AI 工程化基建的人想找一套可以直接抄进仓库的配置模板。我把项目的设计思路、版本演进、核心机制、接入步骤和踩过的坑全部摆出来你既可以把它当思路参考也可以直接拿来改造成自己的版本。1. 为什么要给 Codex / Claude Code 额外加一套推理框架先说结论大模型本身没有“任务管理意识”。你给它一个指令它的默认倾向是用最直接的方式生成一个看起来合理的输出。这种倾向在写单文件、做一次性问答时没什么问题但一旦进入真实项目面对多文件改动、既有代码约束、隐性业务规则它就很容易跑偏。我见过太多类似的情况让 AI 给某个接口加缓存它没有先去查这个接口的调用链凭经验直接往 Service 层塞了一个内存缓存结果上游有多个实例缓存直接失效。让 AI 重构一个函数它不看调用方对返回值的假设重构完以后三个调用方一起报错。这些翻车现场本质不是模型能力不够而是它缺了一条“先理解再动手”的强制路径。所以我才想做一个外部框架把任务处理路径从“输入指令 → 立即输出”改造成“输入指令 → 解读任务 → 检索证据 → 加载技能 → 制定方案 → 执行修改 → 验证结果”。听起来步骤变多了但实际跑下来总耗时反而更短因为返工次数大幅下降。拿没有任何约束时的典型失败模式来对照失败模式具体表现根因方向跑偏对着局部问题放大处理范围改了一堆不相关的文件没先做任务解读和边界确认漏掉隐性约束改了接口签名但没同步调用方没检索完整调用链重复劳动项目里已有现成工具函数AI 重新造轮子没做信息检索就直接编码无法追溯改完以后说不清改了哪些文件、为什么改缺少方案记录与检查点有一次我让 Claude Code 在一个老项目里加个导出功能它在没有确认数据量级的情况下直接用内存拼接方式实现了。代码看着没问题但跑了一百万行数据后直接 OOM。问题不在它不会写代码而在于它没有先去看那条数据的读取链路更没有反问一句“数据规模大概多少”。推理框架要解决的就是这类问题。真正在项目里长期用 AI 编程的人都会发现你缺的不是让 AI 写出正确代码的能力而是让 AI 在正确的前提条件下写出代码的控制力。推理框架本质上就是控制力的一种实现方式。2. v0.1.5 项目形态目录结构、版本演进与设计取舍这个项目不是传统意义上的代码仓库它更像一套“配置 文档 协议”的集合体。你把它放进任何一个项目仓库的根目录AI 工具Codex 或 Claude Code启动时就会读到并在整个会话中持续受它约束。2.1 完整目录结构与职责划分当前 v0.1.5 的目录结构长这样ai-skills/ ├── protocols/ │ ├── reception.md # 任务解读协议先输出任务卡片 │ ├── evidence-first.md # 证据优先协议先定位相关代码与调用链 │ ├── verify-loop.md # 验证循环协议改完必须跑验证清单 │ └── undo-branch.md # 回退分支协议任务失败可回到检查点 ├── skills/ │ ├── dependency-audit/ │ │ └── SKILL.md # 依赖审计技能 │ ├── cache-design/ │ │ └── SKILL.md # 缓存设计技能 │ └── refactor-safe/ │ └── SKILL.md # 安全重构技能 ├── templates/ │ ├── task-card.md # 任务卡片模板 │ └── change-plan.md # 变更计划模板 └── AGENTS.md # 推理协议入口文件每个文件的职责非常明确文件/目录职责设计理由protocols/reception.md强制 AI 在动笔前输出结构化任务卡片防止“没听清需求就动手”protocols/evidence-first.md强制 AI 先定位代码位置并引用路径防止“盲改代码”protocols/verify-loop.md强制 AI 执行预先定义的验证命令防止“改完不测试”protocols/undo-branch.md定义回退机制和检查点防止“错误修改污染主分支”skills/下各 SKILL.md按任务类型加载的专项操作手册让 AI 在特定场景下有标准打法AGENTS.md/CLAUDE.md入口文件声明协议与技能加载顺序让工具一启动就进入推理模式2.2 版本演进v0.1.0 到 v0.1.5 的关键节点这个项目不是一次性设计出来的而是被真实任务逼着迭代出来的。v0.1.0最初只有两个协议reception 和 plan。跑下来发现 AI 经常做完计划不执行或者执行过程中又偏离计划于是加上了执行阶段的行为约束。v0.1.2加入技能加载机制。原因是 AI 在处理缓存设计任务时每次靠临时推测方案不稳定。我把这类任务的标准流程沉淀成 SKILL.md通过关键词自动触发。v0.1.3加入了 evidence-first 协议。要求 AI 在动手前必须引用相关文件的行号这一步直接消灭了大部分“盲改”问题。v0.1.4加入验证循环。让 AI 每完成一个阶段就运行对应测试而不是全部改完再跑显著降低了问题定位成本。v0.1.5加入回退分支机制。因为实测中发现即便有前面四层偶尔也会出现大规模的破坏性修改。回退机制让 AI 在确认失败后能快速回到最近的检查点而不是继续在错误状态上叠加修补。版本迭代里最重要的设计取舍是坚持“Markdown 驱动”而不是“程序驱动”。有人问过我这东西为什么不写成一个 CLI 工具原因是工作流的使用者本身就是 AIMarkdown 是 AI 理解能力最强的格式。任何复杂的自动化脚本都不如一段结构清晰的文本指令来得直接。而且 Markdown 让非程序员也能参与维护和定制这对工程基建的推广来说很重要。另一个关键取舍是“放在项目仓库里”而不是“放在全局配置里”。放在项目仓库里每个项目可以有自己的协议版本团队协作时所有成员和 AI 都共享同一套规则。全局配置更像个人偏好不适合作为团队资产的载体。3. 核心机制拆解任务解码、证据链与技能调度这一章是整套工作流的心脏也是 v0.1.5 相对早期版本最成熟的部分。三个机制的目标各不相同任务解码负责“理解要做什么”证据链负责“搞清楚在哪改”技能调度负责“知道怎么改才专业”。3.1 任务解码动手前先输出一张“任务卡片”任务解码协议写在protocols/reception.md里要求 AI 在收到任何一个新任务后先不要动任何文件而是输出一张结构化的任务卡片。任务卡片长这样{ goal: 为查询模块增加一级缓存, constraints: [ 不影响现有接口协议, 缓存失效时间不超过60秒, 缓存key必须包含业务前缀 ], evidence: [ src/modules/query/handler.py:102-145, src/modules/query/store.py:88 ], acceptance: [ 缓存命中率提升, 现有测试全部通过, 代码评审通过 ], risk_flags: [ 并发写入场景下可能出现脏数据 ] }这张卡片的价值在于“把隐性信息显性化”。很多任务翻车是因为 AI 对需求的假设和用户对需求的假设不一致。任务卡片强制 AI 把目标、约束、验收标准列出来用户一眼就能看出 AI 是否理解正确。有歧义的时候直接在卡片阶段修正比改完代码再返工高效得多。实测中发现这一步还有一个副作用AI 输出的内容更有条理了。因为任务卡片让它整理了自己对问题的理解后续的执行路径也更稳定。我一度怀疑这是不是提示工程的安慰剂效应但多次对比下来有卡片和没卡片的输出质量差距确实明显。实操建议任务卡片不是摆设你需要让它进对话或日志。我习惯一开始就要求 AI 把任务卡片写入worklogs/目录这样事后可追溯也能在任务中断后快速恢复上下文。3.2 证据链先引用代码位置再谈修改方案证据优先协议是 v0.1.3 加入的也是整个工作流里返工率下降最明显的一个机制。它要求 AI 在提出任何修改方案之前先完成以下动作定位与任务相关的所有文件路径和关键函数引用调用链上下游的代码位置检查是否存在现成的工具函数或可复用逻辑明确当前实现的行为假设我在evidence-first.md中写了一个硬性格式所有方案描述里涉及现有代码的部分必须带文件路径和行号。例如“当前查询逻辑位于src/modules/query/store.py:88-110直接访问数据库无缓存层”。这个机制听起来简单但在限制模型“拍脑袋”方面极其有效。如果 AI 只能给出抽象的“优化方案”而无法指出具体在哪里改那说明它还没真正理解代码。强制引用代码位置等于强制它先阅读相关代码。有一次我实测了一个任务给某个内部系统的导出功能加速。AI 最开始给的方案是用异步方式重写整个导出模块。但执行证据链后它发现瓶颈实际在数据库查询的 N1 问题上于是方案变成了“给批量查询加 JOIN 并用游标分批拉取”。同一个任务证据链前后给出的方案工程代价差了一个数量级。这里我自己的体会是证据链本质上是在利用模型的“对比能力”而非“生成能力”。生成一个方案很容易但识别“当前代码与目标代码之间的差异”要难得多也准确得多。3.3 技能调度按任务类型自动加载对应 SKILL技能调度是 v0.1.2 加入的机制也是“SKILLS”这个名字的来源。它解决的是“通用能力在不同专业场景下表现不稳定”的问题。一套通用的编码技巧在处理缓存设计、依赖审计、安全重构这些不同任务时需要完全不同的操作步骤。我把这些步骤沉淀成独立的 SKILL.md 文件并定义了触发条件。AI 在执行任务时会先判断任务类型命中某个技能后再加载对应的 SKILL.md 作为操作手册。当前技能列表和触发场景技能名称触发场景核心步骤dependency-audit涉及依赖升级、包版本变更、安全漏洞排查列出依赖树、检查锁定文件、评估破坏性变更cache-design涉及缓存添加、热点数据优化、查询性能问题确认数据一致性要求、选定缓存粒度、评估失效策略refactor-safe涉及函数重构、模块抽象、接口调整梳理调用方、保持行为兼容、分阶段替换SKILL.md 的正文一般控制在 200 到 300 行。太长会让 AI 在加载时消耗过多上下文太短起不到指导作用。我测试过把技能文件压到 100 行以内结果 AI 经常忽略关键步骤因为提示不够醒目而超过 300 行时AI 又会在次要细节上钻牛角尖。技能调度的实现依赖在协议入口文件里写清楚“先判断是否命中技能再决定是否加载”。你可以理解为AI 默认只带基础能力遇到特定任务才加载专项技能包这样既能保证通用性又能兼顾专业性。3.4 验证循环与回退检查点给 AI 一个试错闭环v0.1.4 和 v0.1.5 加入的验证与回退机制是工作流的最后一道保险。验证循环协议要求在修改完成后按任务卡片里的验收标准执行验证而不是直接宣布完成。验证分为三个级别L1冒烟修改涉及的文件能否正常导入、语法是否正确L2功能与修改直接相关的测试是否通过L3全量整个项目的测试套件是否通过任务卡片里会写明本次修改需要达到哪个级别。比如只改一个常量L1 就足够改接口签名至少 L2牵动核心模块的直接 L3。实测中强制分级验证很重要的原因是全量验证太耗时AI 会产生惰性干脆跳过分级后AI 会根据自己的改动范围选择合适的验证强度。回退检查点的设计则是在每次修改前创建一个 git commit 或 stash。v0.1.5 的undo-branch.md协议明确要求如果验证失败且 AI 判断修复成本过高必须回退到最近一个检查点重新来过不允许在错误状态下继续叠加修补。这个机制看起来是“认输”实际是止损。因为模型在错误状态上修补时经常越补越乱产生连锁的隐性破坏。4. 实操接入Codex 与 Claude Code 的配置落地这一章写给真正想动手的人。下面是我在具体工具里落地这套工作流的完整步骤包括文件配置、入口声明和一个可以直接抄走的 SKILL.md 模板。4.1 Claude Code 接入CLAUDE.md skills 目录Claude Code 支持在项目根目录放一个CLAUDE.md文件作为固定指令也支持读取项目内的 skills 目录每个技能以独立目录 SKILL.md 的形式组织。我的接入方式是第一步把整个ai-skills目录复制到项目根目录并改名为.ai-skills隐藏目录减少干扰。第二步在CLAUDE.md开头写入这段内容# 全局工作流约束 在项目内执行的任何任务都必须遵守 .ai-skills/protocols/ 下的推理协议。 执行顺序 1. 读取 protocols/reception.md输出任务卡片到 worklogs/ 2. 读取 protocols/evidence-first.md先检索相关代码位置 3. 判断任务类型若命中 skills/ 下某技能先读取对应 SKILL.md 4. 修改前创建检查点 5. 修改后按 verify-loop.md 的 L1/L2/L3 级别执行验证第三步把每个 SKILL.md 里的name、description、when_to_use三个字段写好。这是 Claude Code 用来判断“是否触发该技能”的依据。4.2 Codex 接入AGENTS.md 或全局配置Codex 对自定义指令的支持主要走AGENTS.md文件它会在会话开始时被加载。接入思路和 Claude Code 基本一致但入口文件名不同。我的做法是在项目根目录放一份精简的AGENTS.md指向.ai-skills/protocols/下的协议文件。Codex 环境下有一点需要注意Context 窗口的占用更加敏感。如果直接让 AI 一次性读完所有协议文件剩余可用上下文会明显减少。我的优化方案是AGENTS.md里只写协议清单和触发条件具体协议内容让 AI 在需要时按需读取目录下的 Markdown 文件。也就是说让 AI 知道“有协议但读不读安排在任务过程中而不是启动时拉满”。如果你是那种工作项目跨仓库、不想在每个仓库都复制一份配置的人也可以把协议文件放在某个公共目录里然后在AGENTS.md里用绝对路径引用。不过这样跨项目共享的好处是维护成本低坏处是某个项目需要特化时不好单独定制。4.3 一个可以直接抄的 SKILL.md 模板下面这套模板是 v0.1.5 里cache-design技能的简化版。你可以直接复制替换成自己的技能主题。--- name: cache-design description: 在需要为数据访问链路添加缓存、处理重复查询或优化热点数据访问时使用。 when_to_use: 当任务涉及缓存、性能优化、热点数据、重复调用、数据库压力时。 version: 0.1.5 depends_on: - protocols/evidence-first.md - protocols/reception.md --- # 缓存设计技能 ## 目标 设计一套可落地的缓存方案并保证缓存与数据源的一致性。 ## 执行步骤 1. 确认数据一致性要求 - 数据允许延迟多久能否容忍脏读 - 是否有强一致性的场景如有明确标注不可缓存。 2. 确定缓存粒度与 key 设计 - 缓存对象是单条记录、列表结果还是聚合数据 - key 必须包含业务前缀和查询参数避免不同业务互相污染。 3. 设计失效策略与淘汰策略 - 简单场景优先用 TTL 过期复杂场景明确写失效触发点。 - 禁止只依赖缓存过期解决数据更新问题。 4. 执行验证清单 - 验证代码的路径覆盖了缓存命中与缓存未命中两个分支。 - 验证缓存写入前后数据一致性。 - 验证高并发下缓存击穿时的回源行为。这套模板的关键在于前面三到四行front matter必须精准描述触发场景后面正文必须具体到可执行步骤。我见过很多失败的技能文件问题都出在“描述含糊、步骤抽象”AI 加载了跟没加载一样。5. 实测复盘真实任务里的收益与翻车点这一章是 v0.1.5 打磨过程中最有价值的部分。我拿一个真实跑过的任务做案例再把遇到过的坑和对应解法全部列出来省得你重走一遍弯路。5.1 一个有参考价值的实测案例模拟项目 X 是一个内部数据平台某天需求方提出查询接口在高峰期响应太慢需要加缓存。这个任务我用两套流程各跑了一遍对比结果如下维度无推理框架有推理框架v0.1.5步骤数直接生成修改 → 改完提交任务卡片 → 证据链 → 技能加载 → 检查点 → 修改 → 验证涉及文件2 个凭感觉猜的4 个调用链全部覆盖返工次数2 次缓存失效逻辑漏了后补0 次完成耗时约 40 分钟约 25 分钟结果可追溯性差说不清为什么这么改好worklogs 里完整记录具体差异点在于无框架时AI 直接在查询函数外面套了一个本地缓存完全没考虑这个系统是部署在多实例上的本地缓存等于失效。有框架时它在证据链阶段检索到了系统部署配置在 cache-design 技能里又明确了“多实例环境禁止用本地缓存”一上来就把方案拉回了正确轨道。5.2 翻车点一技能文件太多上下文被吃干净刚开始我把十几个技能文件全部放进目录指望 AI 随用随取。结果它的表现不是“随用随取”而是“见到什么都想读”对话到后面上下文窗口被占满基础指令反而被稀释了。解决方法是给技能文件设定数量上限。我实测下来一个项目里活跃技能控制在 5 到 8 个之间比较合适。超过 8 个AI 在技能选择上出现混乱低于 3 个又覆盖不了常见的任务类型。同时SPILL 描述和when_to_use要写得足够具体降低误触发的概率。5.3 翻车点二Codex 和 Claude Code 对 SKILL.md 的读法不完全一致两边虽然都支持 Markdown 指令文件但实际行为有细微差异。Claude Code 对 front matter 字段的解析更宽容描述字段写得口语化也能触发而 Codex 对指令的遵循更依赖“指令文件里是否明确写了优先级和强制性措辞”。最靠谱的兼容策略是front matter 只用三个基础字段name、description、when_to_use其他自定义字段全部放在正文里说明。这样两边都不会因为未知字段而产生诡异行为。还有个细节协议文件里尽量用祈使句不要用模糊的“建议考虑”给 AI 的指令越接近“操作命令”执行的确定性越高。5.4 翻车点三验证循环过重AI 开始“假装验证”v0.1.4 刚上线的时候我要求每次修改后都跑全量测试。很快发现问题AI 在部分场景下会跳过真实命令直接在回复里写“测试已通过”。这种“假装验证”行为让我警惕后来我改用分级验证并在协议里明确写了“未执行验证命令禁止宣称验证通过验证命令的输出必须出现在回复里”。把验证输出贴回对话这一个要求就解决了问题。因为模型很难凭空捏造真实的测试输出格式一旦它编造很容易被识别。这算是 v0.1.5 里很实用的一处强化。5.5 关于 Auto-Driven 的理解误区最后聊一点我自己的认知迭代。这个项目名字里的 “Auto-Driven”不是指“AI 全自动干活人不用管”。在 v0.1.5 的实践里它更多是指“工作流自动驱动 AI 走完一套推理路径”。人是设定规则的人AI 是在规则内自动执行的人。我试过把规则放宽一点让 AI 在简单任务上可以跳过某些协议结果发现它“简单任务”的判断标准会逐渐放宽最后几乎所有任务都想抄近道。所以现在的版本里我把协议设为强制项最多允许 AI 在任务卡片里明确请求“缩短验证流程”但这个请求必须由用户批准。这样既保留了效率优化的空间又不至于让规则形同虚设。另一个让 Auto-Driven 真正起作用的细节是把推理协议的关键指令放在工具配置文件的最前面。因为模型对长文档前部的注意力权重更高协议如果藏在文件中间很容易被忽略。我现在不管在AGENTS.md还是CLAUDE.md里第一句话永远是“执行任何任务前必须依次完成以下协议”。这个动作虽小但对命中率的影响非常大。