Codex/Claude Code推理框架工作流：规划-执行-验证三阶段实战

最近半年，我一直在折腾 Codex 和 Claude Code 跑复杂任务，越用越觉得，这两类工具本身的底子都很好，但真正决定产出的，是自己塞给它们的那套“组织和指挥系统”。这个名为 AI-Infra-Auto-Driven-SKILLS v0.1.5 的推理框架工作流，就是用来解决这个问题的——它要干的事，是把一句“帮我改好了吗”升级成一套可执行的推理链路，让 Codex / Claude Code 在规划、执行、验证三个阶段都有章可循。

如果你只是偶尔用 AI 写个脚本、补个测试，那可能感受不到这套东西的必要性。但如果你已经在用 Codex 或 Claude Code 做模块重构、跨文件改造、自动化代码审查，你会发现一个很尴尬的现实：AI 写代码的速度确实快，但它“想到哪写到哪”的毛病也同样突出。没有框架约束的话，一个复杂的重构任务跑下来，你往往要花更多时间在 review diff 和收拾烂摊子上。

这篇文章就把我在 v0.1.5 版本里沉淀下来的东西完整讲一遍，包括目录结构、SKILL.md 的写法、hooks 自动验证、自动化模式下的参数配置，以及那些文档里不会写的坑。内容均来自我一个阶段的实操积累，你可以照抄大半部分，剩下的根据自己项目情况调整。

1. 项目背景与核心思路

1.1 为什么需要推理框架工作流

先说一个我自己的观察。Claude Code 和 Codex 这类工具，单论代码生成能力，已经是相当能打的了。但它们本质上是“对话式”的：你给一段指令，它回一段结果。当你把一个几百行的模块丢给它说“帮我重构一下”，它会怎么做？大概率是当场就开始改，而不是先把代码完整读一遍、列出修改方案、等你确认边界条件。

问题就出在这儿。代码重构、跨文件改造、系统迁移这类任务，真正难的从来不是“怎么写某一段代码”，而是“先改哪里、后改哪里、改到哪一步该停下来验证”。AI 不擅长自己建立这种优先级和依赖关系，它更擅长的是顺着上下文往下续写。如果你不给它一套硬性的思考规则，它就会用自己的“续写惯性”来干活——这也就是为什么很多人觉得 AI 写的代码在小任务上很惊艳，在大任务上却很失控。

所以这个工作流的出发点很简单：把人类工程师在动手前脑子里的那套推理过程，从“隐性的”变成“显性的”，然后写进文件里让 AI 照着执行。规划层负责拆解任务和排优先级，执行层负责按部就班改代码，验证层负责确保每一步没有把东西改坏。

我最初试过直接在系统提示词里写“请你先规划再执行”，效果有一点，但不稳定。AI 在高强度编码时经常会忘掉这些软性要求，尤其是当上下文窗口被大量代码 diff 塞满后，它连自己一开始说过的话都能忘了。后来我换成文件驱动的形式——把规则固化到 AGENTS.md / CLAUDE.md，创建 skills 目录，用 hooks 做强制验证，问题才真正被解决。

1.2 和“裸写提示词”的差别

很多人会问：我不就是用个工具吗，为什么要搞这么重？直接一句话让它干活不就行了。能行，但分场景。

如果任务是“给这个函数写个单测”，裸写提示词完全够用。但如果任务是“把用户认证模块从 JWT 改成 OAuth2，涉及 12 个文件、4 个外部服务依赖，还要求兼容旧 token”，裸写提示词几乎注定翻车。原因有三。

第一，上下文窗口有限。12 个文件不可能全都塞进一次对话里，AI 需要在执行过程中分批读取，这就意味着它必须记住“自己现在在做什么、下一步该做什么”。没有任何外部记录的话，它很容易在某个文件里改着改着就忘了整体目标。

第二，验证环节容易被跳过。AI 的默认行为是“写完代码就算完事”，它不会自觉去跑测试、检查类型错误、确认 API 兼容性。如果你不强制，它就会把一堆编译不过的代码交给你。

第三，任务是会漂移的。AI 在整个流程里可能会“灵机一动”想出某个优化方案，然后偏离原有计划。这种创新有时候是好的，但大多数时候会让 diff 变得难以 review。

用这套推理框架工作流以后，以上三个问题都有对应的机制：规划文件负责目标锚定，验证钩子负责质量兜底，里程碑检查点负责纠偏。当然代价是多了一些前期配置成本——但边际成本很快就会被省下来的 review 时间覆盖掉。

1.3 v0.1.5 的目标与适用范围

这个版本我主要解决的是“自动化驱动”和“技能复用”两条线。所谓自动化驱动，就是说工作流在 auto 模式下能够自己规划子任务、调用相应技能、执行验证命令，人工只在关键节点介入。所谓技能复用，是说把经常要做的操作封装成标准的 skills，在不同项目里反复使用。

适用场景比较明确：用 Codex 或 Claude Code 处理中型以上的代码任务（涉及多文件、多步骤、多验证环节），或者是团队里想统一 AI 协作规范的。如果你只是玩票性质地让 AI 帮你写点小工具，这套体系确实有点过重——就像你只是出门买瓶酱油，没必要开一辆货车。

2. 推理框架的设计与分层

2.1 三层推理链路

v0.1.5 的核心是把推理过程拆成三条链路：规划层、执行层、验证层。听起来学术化，但落到实际就是三组规则文件，分别对应 AI 在一个任务里不同阶段应该做什么。

规划层的职责是“先想清楚再动手”。它要求 AI 在接到任务后，先不碰代码，而是读取项目状态、理解需求、列出子任务清单，并标注每个子任务的依赖关系。这一层我把它写成 planning.md，里面明确要求 AI 输出类似“任务拆解：1. 阅读现有认证模块源码；2. 确认第三方 OAuth2 库选型；3. 设计 token 迁移方案；4. 分阶段改造；5. 全量回归验证”这样的结构化计划。它实际上是把 AI 的“思维链”变成了文件里看得见的文字。

执行层则规定了“具体怎么改代码”。这一层的规则包括：每次只处理一个子任务、禁止同时改动多个无关文件、修改前先读取目标文件的完整内容、改动要尽量小且保持风格一致。我把这套规则写进 execution.md，并且特别注明“如果没有把握，宁可不改也不要硬写”。AI 在写代码这件事上天然偏向“自信输出”，所以这条约束实际上是帮它踩刹车。

验证层解决的问题是“怎么知道自己没改坏”。它要求 AI 在完成每个子任务后，必须主动执行对应的验证命令，比如跑单测、跑 lint、检查类型。如果验证失败，AI 不得直接进入下一个子任务，而必须先修复当前问题。这一层我对应到 validation.md，同时在 hooks 层做了一道硬性拦截——AI 如果跳过验证就让它无法继续。

三层链路之间并不是割裂的，而是通过一个状态文件串联。AI 每完成一个子任务，都会把进度写进 state/progress.md，下一次读取上下文时先看这个文件，就知道自己进行到哪一步了。

2.2 上下文文件体系

这套框架的另一个设计重点是“上下文不是靠聊天记录，而是靠文件”。我自己实测下来，聊天记录在长任务里是最不可靠的，因为它会滚动丢弃、会被大量工具输出稀释、会随着模型指令历史变得稀疏。文件则相反，它稳定、可查、可被再次加载。

v0.1.5 在项目根目录下放了一套标准文件体系，如下所示：

.ai-framework/ ├── AGENTS.md # 全局行为准则，Codex / Claude Code 通用入口 ├── planning.md # 规划阶段规则 ├── execution.md # 执行阶段规则 ├── validation.md # 验证阶段规则 ├── skills/ │ ├── task-breakdown/ # 技能：任务拆解 │ ├── code-review/ # 技能：安全代码审查 │ └── test-fix-loop/ # 技能：测试失败修复循环 └── state/ └── progress.md # 任务进度与检查点

这些文件必须被 AGENTS.md 里统一的约定引用。比如 AGENTS.md 会这样写：

# 项目 AI 协作规则 1. 接到任务后，先读取 .ai-framework/planning.md，按其中流程执行任务拆解。 2. 执行修改时严格遵守 .ai-framework/execution.md 中的规则。 3. 每次修改后必须运行验证命令，规则见 .ai-framework/validation.md。 4. 每个子任务完成后，更新 .ai-framework/state/progress.md。 5. 涉及重复性操作时，优先调用 .ai-framework/skills/ 下的对应技能。

这套文件体系的好处是：它天然适配 Codex 的 AGENTS.md 机制，也适配 Claude Code 的 CLAUDE.md 机制。你只需要把 AGENTS.md 里的这些规则复制到 CLAUDE.md（或者做一个软链），两边就都能跑起来，不用各写一套完全不同的规则。

2.3 目录结构与配置清单

先聊清楚一个核心机制。Codex 和 Claude Code 在较新的版本里都支持“项目级指令文件 + 技能（skills）”的组合。Codex 主要认 AGENTS.md，Claude Code 认 CLAUDE.md，同时两者都开始兼容跨工具的标准技能格式——也就是一个目录里放一个带 YAML frontmatter 的 SKILL.md。

我的做法是：在项目根目录放 AGENTS.md 作为唯一的事实来源，然后把 CLAUDE.md 指到同一份内容。具体实现很简单：

ln -s AGENTS.md CLAUDE.md

在 v0.1.5 中，我还在.ai-framework/skills/下写了三个技能，覆盖最常见的场景。目录结构大概是这样：

.ai-framework/skills/ ├── task-breakdown/ │ └── SKILL.md ├── code-review/ │ └── SKILL.md └── test-fix-loop/ └── SKILL.md

每个技能目录下不一定只有 SKILL.md，如果你有配套脚本，也可以放在同一目录里。比如 code-review 技能我会配一个prettier_diff.py脚本，用来提取 git diff 并做初步格式检查。AI 在调用技能时，除了读 SKILL.md，还会自动发现同目录下的辅助文件，这样它就能拿到完整的操作上下文。

配置完成后，你可以自己检查一下整体效果：新建一个干净的 shell，进入项目目录，启动 Codex 或 Claude Code，输入一句“请按流程对这个项目做一次代码审查”，看它是否会主动读取规则文件、调用 code-review 技能、按步骤走完整个流程。如果它会，说明框架已经生效了。

3. SKILLS 机制详解与实操

3.1 SKILL.md 的标准写法

技能目录的核心是 SKILL.md。它在头部用 YAML frontmatter 写明元信息，正文则是操作步骤和注意事项。Codex 和 Claude Code 都会扫描项目里的skills目录，并把 SKILL.md 的描述内容作为“可选技能”注入到上下文中。

我写 SKILL.md 的经验是要把 frontmatter 里的 description 写得非常具体，因为 AI 主要靠 description 来判断“这个技能适不适合当前场景”。笼统的描述会导致技能被错误触发或根本不触发。

一个标准的 task-breakdown 技能大概是这个样子的：

--- name: task-breakdown description: 将复杂任务拆解为可执行的子任务列表，按依赖关系排序，并标注每个子任务的验收标准。适用于需要多个步骤、涉及多个文件、需要分批提交的任务。 when: 任务包含多个文件或有明显的前后依赖关系。 --- # 任务拆解技能 ## 步骤 1. 阅读当前需求并提取目标，明确最终交付物是什么。 2. 扫描项目中与需求相关的文件和模块，列出影响面。 3. 将整个任务拆成 3-8 个子任务，子任务之间尽量保持独立。 4. 明确每个子任务的优先顺序，标注依赖关系。 5. 为每个子任务写一条可验证的完成标准（例如“通过指定单测”）。 6. 将拆解结果写入 .ai-framework/state/progress.md。 ## 注意事项 - 不要将“读代码”和“改代码”混在同一个子任务中。 - 如果需求本身模糊，先列出需要向用户确认的问题。 - 子任务粒度不宜过大，也不宜碎到没法独立验收。

我这里要提醒一个容易踩的坑：description 里的when字段是我自己加的约定，并不是标准强制字段。这么写是为了让 AI 更精准地判断触发时机。实测下来，带上触发条件描述后，误触发的概率会明显下降。

3.2 三个核心技能示例

v0.1.5 里最重要的三个技能分别是任务拆解、安全代码审查、测试修复循环。它们对应了长任务里最容易翻车的三个环节。

code-review 技能我设计成专门用来检查 AI 自己或同事提交的 diff。它要求 AI 只读代码、不改代码，从正确性、安全性、风格一致性三个维度输出评审意见，并且每条意见都要给出行号级证据。实际操作里，这个技能最有效的一个功能是“阻止 AI 在代码审查过程中顺手改代码”——没有这个约束，AI 经常看到一个小问题就直接上手改了，最后 review 变成了新的 diff 制造机。

test-fix-loop 技能是用来应对“测试挂了”这种情况的。它的逻辑是：先看测试输出，定位失败的根因，再最小化修改代码，然后重跑测试。整个过程最多循环 3 次，3 次还没过就要停下来向用户汇报，而不是无限自我修复。这一点我觉得特别重要，因为 AI 在“执着”这方面有时候很可怕，它能为了一个不重要的测试失败反复折腾十几次，把上下文窗口完全耗尽。

具体到 code-review 的 SKILL.md，我会在其中写入这样的规则：

--- name: safe-code-review description: 对指定文件或 git diff 执行安全的代码审查，只读不改，输出带行号的问题清单。适用于提交前审查、AI 生成代码的复核、以及跨文件改动前的风险排查。 --- # 安全代码审查 ## 步骤 1. 通过 git diff 获取本次改动范围。 2. 逐个查看涉及文件，忽略格式风格类的主观意见。 3. 按“功能正确性 / 安全风险 / 兼容性影响”三类输出问题清单。 4. 每个问题必须标注文件路径、行号和说明。 5. 禁止修改任何代码，禁止主动重构。 ## 注意事项 - 如果审查过程中发现需要修改的地方，只记录，不改动。 - 重点检查：输入校验、异常处理、状态变更、敏感信息日志。

你不用照着抄，但建议至少理解这个思路：你的技能文档要让 AI 明确“什么时候用、步骤是什么、边界在哪里”。

3.3 技能触发条件与优先级

技能触发有两种途径。一种是 AI 在读到项目规则后，主动决定调用某个技能；另一种是你直接在对话里显式提到技能名，比如“用 task-breakdown 把这件事拆一下”。两种我都在用，但实际体验下来，主动触发并不总是可靠。

原因在于：AI 一次只能看到有限的上下文描述。description 写得好，它确实会更愿意触发；但遇到一些边缘场景，比如任务描述比较抽象、没有明确提到“多个文件”“多个步骤”，它就可能不触发任务拆解，直接开写代码。解决方案有两个：一是把 AGENTS.md 里的流程写得更强制，比如“凡涉及修改超过 3 个文件的任务，必须先从 skills/task-breakdown 技能开始”；二是在启动任务时手动点一句“先走标准流程”。

另外要注意技能的优先级问题。当项目里有多个技能时，AI 可能会同时匹配多个技能，然后选择一个它认为最合适的。为了减少这种不确定性，我给 AGENTS.md 加了一条规则：如果多个技能同时匹配，按“task-breakdown → test-fix-loop → safe-code-review”的优先级取用。当然这个顺序要按你实际工作流来定，但规则一定要显式写出来，别让 AI 自己临场判断。

4. 工作流自动化驱动的落地配置

4.1 hooks 与自动验证

规则文件算是软约束——AI 可以自觉遵守，但偶尔也会偷懒。真正的硬约束要靠工具层面的 hooks 机制来实现。Claude Code 支持配置 hook，在特定事件（比如每次工具调用后）触发自定义命令。Codex 也在不断补强这类能力。

我在 v0.1.5 里配置了两个比较关键的 hooks。第一个是“修改后自动跑类型检查”，监听对象是文件编辑类工具调用。每当 AI 改完一个文件，就自动对该文件做一次类型检查或语法检查，如果不过，AI 会立刻拿到失败反馈。第二个是“git diff 后的格式校验”，监听命令是git diff，用来校验输出是否存在明显的中文乱码、缩进错乱等问题。

配置片段参考如下（以 Claude Code 的 hooks 配置为例，配置放在项目根目录的.claude/settings.json）：

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "python3 .ai-framework/scripts/check_syntax.py" } ] }, { "matcher": "Bash(git diff)", "hooks": [ { "type": "command", "command": "python3 .ai-framework/scripts/check_diff.py" } ] } ] } }

注意，check_syntax.py 这种脚本不需要多复杂，它只要做到“读文件、做语法解析、输出 PASS/FAIL”就够了。关键是把验证时机前置，让 AI 在每个小步骤完成时就被检查，而不是等一整轮改动完了才跑一次全量测试——到那时如果挂了，你就得在巨大的 diff 里找哪里出了问题。

4.2 命令参数与模式选择

自动化驱动还需要在调用工具时设置合理的运行参数。以 Claude Code 为例，--mode可以切换 auto 或 plan 模式。Codex 也有类似的机制，比如让 AI 在“只规划不执行”和“全自动执行”之间切换。我在 v0.1.5 中总结出来的运行参数组合是这样的：

还有一个容易被忽视的选项是“每轮交互的 token 预算”和“自动接受编辑”。在自动模式下，如果开启了 auto-accept，AI 会直接修改文件而不弹确认框。这个选项对效率有帮助，但对操作安全有风险。我的建议是：在 auto 模式跑任务时保留 diff review 环节，至少让 AI 在改动后把 diff 汇总给你看一遍。

实际配置命令举例（根据你使用的工具对应调整）：

# Claude Code 进入自动模式并保持紧凑上下文 claude --mode auto --autoCompact # Codex 启用审批过的自动修正 codex --auto-accept --safe-mode cautious

参数名字在不同版本可能有变动，以你本机的 help 输出为准，我这边记录的是我习惯用的版本。

4.3 一个完整任务的自动执行流程

纸上谈兵太多没用，我直接讲一个实际跑过的场景。

某次任务是把一个 Python 项目里的用户模块从同步 SQLAlchemy 调用改成异步。改动范围涉及 8 个文件，包括模型定义、Repository 层、路由处理器和测试用例。整个任务我没有一句句指挥 AI，而是全程走框架的自动流程。

第一步，我给 Codex 下的任务指令是：“按标准流程完成用户模块异步化改造”。它读到 AGENTS.md 后，自动把 task-breakdown 技能跑了起来，输出了一个 6 个子任务的计划：

1. 梳理当前用户模块的 IO 调用点；
2. 设计异步改造方案，确认影响范围；
3. 改造 Repository 层；
4. 改造路由处理器；
5. 更新测试用例；
6. 全量运行测试。

计划里的每个子任务都写了验收标准。比如“Repository 层改造”的验收标准是“所有数据库查询函数返回 awaitable 对象”。它把计划写进了 progress.md，然后进入执行阶段。

第二步，AI 按照 execution.md 的规则，一次只处理一个子任务。它先读取了仓库里的相关文件，确认了代码结构，然后开始改 Repository 层。每次写完一个文件后，hook 自动跑语法检查，确保没有低级错误。

第三步，子任务 5 更新测试用例时，AI 遇到了旧代码里一个 fixture 不兼容的问题，跑测试直接挂了。这时候 progress.md 里记录的状态显示“子任务 5 验证失败”，AI 自动调用了 test-fix-loop 技能。它花了三轮找到根因：原来 fixture 里用了一个同步上下文管理器，异步改造后不再适用。第三轮修复后，测试通过，它才继续往下走。

整个过程我没有干预，只在最后审查 diff 时发现两点待改进：一个是事务边界处理得偏保守，多了几个不必要的锁；另一个是日志文案和旧风格不一致。但这些都属于优化层面，框架本身已经把“改坏代码”和“忘跑测试”这两类大问题挡住了。

5. 常见问题与排查技巧

5.1 上下文漂移与进度丢失

长任务里最典型的失败模式，就是 AI 干着干着忘了整体计划。它可能在第 10 个文件里突然开始用另一种风格写代码，或者干脆开始改一个和任务完全不相关的模块。

我的排查三步法：

1. 看 progress.md。如果文件内容还停留在第三四个子任务，而实际代码已经改得面目全非，说明 AI 没有按计划更新状态。
2. 看最近几次 commit 的消息。如果提交信息和子任务不对应，说明执行过程已经漂了。
3. 直接把当前进度回退到上一个检查点，重新加载 planning.md 和 progress.md，把对话上下文清掉重来，而不是在那个已经污染的对话里继续“纠正”它。

很多时候，你觉得 AI “蠢”不是因为它真蠢，而是它的上下文已经被代码噪声污染了。这时候与其花大量 token 让它自己绕回来，不如直接断开重开。这不是逃避，是最经济的选择。

5.2 技能不触发的问题

技能不触发通常有三个原因：description 写得不够明确、AGENTS.md 里没有给出强制的触发条件、或者技能目录路径没有被工具扫描到。

如果排除了路径问题，最有效的改法是把“必须触发某技能”写进 AGENTS.md 的开头部分。不要放在最后，放在最后它被读到的概率会低很多。我一开始就把规则埋在第三个章节里，结果 AI 经常忽略。后来我把所有“必须”级别的规则提到文件顶部，配合加粗标记，“不触发”的情况明显变少。

同时确认一下你把技能目录放在哪里。Codex 和 Claude Code 对技能目录的扫描范围有区别，有的只认用户级目录（比如~/.claude/skills/），有的只认项目级目录。为了保险，我在用户级和项目级都放了一份。技能这东西有点像共享类库，项目级放一份、全局放一份，哪个项目都能用。

5.3 自动模式下跑偏的纠偏

自动模式的问题在于 AI 一旦启动，就不会每步都问你，如果它做了一个错误的方向性决策，你往往要等它跑出很远的距离才发现。所以我在 v0.1.5 里就特意设置了“里程碑检查点”的概念。

具体做法是在 planning.md 里规定：每完成两个子任务，AI 必须停下来，输出一份简短的进展报告，然后等待用户确认后再继续。这样自动模式并没有变成完全无人值守，而是变成了“分段无人值守”。实测下来，这个机制让大任务的成功率提升了非常明显——AI 跑偏的距离被控制在了一两个子任务以内，不至于整套流程全部白费。

如果你用的是 Claude Code，可以用它的权限系统和“暂停”模式实现；如果用的是 Codex，可以在任务拆解时就把“检查点”写进拆解结果里，让 AI 自己遵守这个节奏。

5.4 多仓库与团队协作中的配置隔离

最后说一下团队扩展开的问题。我这个框架最初只在一个项目里用，后来 A 同学把它带到了另一个仓库，结果发现两个团队的编码习惯差别很大：一个要求强制类型标注，另一个完全不做类型检查；一个用ruff做 lint，另一个用black。

如果每个仓库都强制套用同一套 execution.md，迟早会出矛盾。所以 v0.1.5 的配置我改成了“分档灵活”的结构：

• execution.core.md：存放所有人都应该遵守的基本原则，比如“每次只改一个子任务”“不要同时改无关文件”。
• execution.repo.md：存放仓库特有的规则，比如 lint 工具、测试命令、commit 规范。

AGENTS.md 里按顺序先加载基础规则，再加载仓库规则。这样团队协作时不会出现“A 项目强制规则污染 B 项目”的情况，新成员加入后也只需要花十分钟通读一下文件即可了解全部协作方式。

6. 后续规划与个人体会

v0.1.5 并不是一个“完美版本”，它更像是我把过去一段时间使用 Codex / Claude Code 的经验教训固化成了可复用的工程产物。下一步我打算做两件事：一是给这套框架加一个“任务后复盘”功能，让 AI 在跑完任务后主动总结哪些步骤耗时最长、哪些部分最容易出错，沉淀成项目自己的经验库；二是把技能体系从“文件规则”升级到“可以执行脚本”的层级，让部分验证操作不再依赖 hooks 去拦截，而是由技能自身驱动完成。

最后说一点个人体会。做这套东西之前，我一直以为“让 AI 写好代码”的关键在模型能力；做完以后我觉得，模型能力只是下限，真正拉开差距的是我们怎么组织它的工作方式。Codex / Claude Code 本身已经很强，但它们强得像一个“有天赋但容易分心”的工程师，你需要给它一套流程、一些检查和几条边界，它才能释放出真正的生产力。这套框架的内核其实很朴素：把人的工程判断翻译成 AI 能执行的规程。

如果你也准备在自己的项目里跑起来，我的建议是从最小集开始——先只加一个 task-breakdown 技能和一个 progress.md，跑通一个任务，感受一下“有框架”和“没框架”的差别，再慢慢把其他技能和 hooks 补上。别一上来就把我上面所有配置一次性铺开，那样你反而会不知道问题出在哪儿。