# Codex Workflow Template：连接推理模型与编程Agent的闭环工作流 > 该开源模板为使用Codex CLI的开发者提供了一套完整的工作流框架，实现推理模型负责架构设计、Agent负责代码实现的协作模式，通过结构化的文档体系确保知识在两者之间顺畅流转。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-04-01T14:38:36.000Z - 最近活动: 2026-04-01T14:50:31.187Z - 热度: 141.8 - 关键词: Codex CLI, AI辅助开发, 工作流模板, 推理模型, 编程Agent, 闭环反馈, 架构设计, 代码评审 - 页面链接: https://www.zingnex.cn/forum/thread/codex-workflow-template-agent - Canonical: https://www.zingnex.cn/forum/thread/codex-workflow-template-agent - Markdown 来源: ingested_event --- ## 引言：AI辅助开发的新范式\n\n随着大语言模型能力的不断提升，越来越多的开发者开始尝试将AI工具融入日常开发流程。其中一种颇具前景的模式是"双模型协作"：由擅长推理和规划的模型（如Claude、o1等）负责高层架构设计和需求分析，再由专门优化的编程Agent（如Codex CLI、Claude Code等）负责具体实现。这种模式理论上可以兼顾战略层面的系统性和战术层面的执行效率。\n\n然而，实践中的挑战在于如何让这两个角色有效协作。推理模型产生的规格说明如何准确传达给编程Agent？Agent在实现过程中遇到的问题和做出的决策如何反馈给推理模型？如何避免信息在传递过程中的丢失和扭曲？\n\n**Codex Workflow Template**正是为解决这些问题而设计的开源模板项目。它通过一套精心设计的文档结构和自动化工作流，在推理模型和编程Agent之间建立了一个双向反馈的闭环系统。\n\n## 核心理念：闭环反馈\n\n该模板的设计哲学可以概括为"规格进，评审出"。具体来说：\n\n**正向流程**：推理模型产出的规格说明（Specs）通过结构化的方式流入Codex CLI，指导其进行代码实现。\n\n**反向流程**：Codex CLI在完成实现后，自动生成评审文件（Review Files）、进度记录（Progress Records）和文档更新提案，回流给推理模型。\n\n这种双向流动确保了架构决策能够在代码层面得到忠实执行，同时代码实现中的实际情况也能及时反哺架构设计，形成持续改进的良性循环。\n\n## 文档体系架构\n\n模板定义了一套层次分明的文档结构，每个文件都有明确的职责和更新规则：\n\n### AGENTS.md —— 项目总览\n\n这是整个项目的"入口文件"，Codex CLI每次启动会话时都会自动加载。其中包含：\n\n- 技术栈定义（Tech Stack）\n- 架构规则（Architecture Rules）\n- 项目结构说明（Solution Structure）\n- 编码规范和质量标准\n\n通过维护这个文件，开发者可以确保AI助手始终基于正确的上下文进行工作。\n\n### docs/specs/ —— 需求规格库\n\n每个新功能都需要在这里创建一份规格文档，基于提供的`_template.md`模板。规格文档应包含：\n\n- 功能背景和业务价值\n- 详细的需求描述\n- 验收标准\n- 潜在的边界情况和异常处理\n\n这些规格由推理模型（或人类架构师）撰写，是Codex CLI实现功能的权威依据。\n\n### docs/architecture.md —— 活文档架构\n\n不同于传统的静态架构文档，这是一份"活文档"（Living Document）。随着项目演进，架构决策和系统结构的变化会在这里持续更新。它既是新成员了解系统的入口，也是AI助手理解整体设计的参考。\n\n### docs/domain-model.md —— 领域模型参考\n\n集中定义系统中的核心实体（Entity）、枚举（Enum）和不变式（Invariant）。当Codex CLI生成代码时，可以参照这份文档确保命名和结构的一致性。\n\n### docs/decisions/ —— 架构决策记录（ADR）\n\n每个重要的架构决策都应该在这里留下记录，使用`_adr-template.md`模板。ADR目录中的`index.md`提供了决策标签的索引，方便快速检索。这种做法不仅有助于团队成员理解决策背后的考量，也为AI助手提供了宝贵的上下文信息。\n\n### docs/review/ —— 自动生成的评审文件\n\n这是闭环反馈的关键环节。当开发者认为某个功能实现完成时，通过触发`$review-ready`技能，Codex CLI会自动生成评审文档，内容包括：\n\n- 实现与规格的符合度分析\n- 代码质量评估\n- 潜在问题和改进建议\n- 需要人工确认的事项\n\n这些评审文件随后被推理模型读取，作为下一轮架构调整的输入。\n\n### docs/progress/ —— 进度追踪体系\n\n该目录维护了项目进度的"单一事实来源"（Single Source of Truth）：\n\n- `index.md`：功能级别的总体进度，由Codex CLI在每次`$review-ready`运行时自动更新\n- `design-state.md`：架构层面的状态，由人类维护\n- `features/`：每个功能分支的独立记录文件，采用追加模式，一旦创建不再修改\n\n这种设计既保证了自动化的便利性，又保留了人类对关键决策的控制权。\n\n## 技能系统（Skills）\n\n模板在`.codex/skills/`目录下预定义了三个核心技能，通过特定的命令触发：\n\n### $new-feature\n\n启动新功能开发流程。Codex CLI会读取`docs/specs/`中的规格文档，理解需求后开始实现。这个过程中它会遵循AGENTS.md中定义的架构规则，确保代码风格和质量标准的一致性。\n\n### $review-ready\n\n触发代码评审流程。Codex CLI会对当前工作区进行分析，生成详细的评审报告，并更新`docs/progress/`中的相关文件。这是将实现层面的信息反馈给推理模型的关键步骤。\n\n### $review-fix\n\n根据评审反馈进行修复。在推理模型（或人类）审阅了生成的评审文件并提出修改意见后，通过这个技能让Codex CLI执行相应的代码调整。\n\n## 工作流示意图\n\n整个协作流程可以可视化为：\n\n```\n推理模型 → 规格文档 → Codex CLI\n ↑ ↓\n ADR/架构更新 ← 评审文件/进度记录\n```\n\n具体步骤如下：\n\n1. **规划阶段**：推理模型分析需求，撰写`docs/specs/`中的功能规格和`docs/decisions/`中的架构决策记录\n\n2. **实现阶段**：开发者通过`$new-feature`命令触发Codex CLI，AI助手基于规格进行代码实现\n\n3. **评审阶段**：实现完成后，通过`$review-ready`生成评审文档和进度更新\n\n4. **复盘阶段**：推理模型读取评审文件和进度记录，决定是否需要更新架构文档或撰写新的ADR\n\n5. **交付阶段**：人类开发者提交代码，发起PR，完成合并\n\n值得注意的是，Codex CLI在整个流程中不执行任何Git命令，版本控制操作完全由人类掌控，确保了代码安全。\n\n## 与Claude Code版本的对比\n\n该模板的作者同时维护了一个Claude Code版本（作为参考实现，经过充分的生产验证）。两个版本遵循相同的工作流模式，但在具体实现上有所区别：\n\n- Codex CLI版本针对OpenAI的Codex工具进行了适配\n- Claude Code版本针对Anthropic的Claude Code进行了优化\n\n开发者可以根据自己的主力工具选择合适的版本。\n\n## 快速开始\n\n使用该模板非常简单：\n\n1. 点击GitHub上的"Use this template"按钮创建自己的仓库\n2. 填写`AGENTS.md`，定义项目的技术栈和架构规则\n3. 填充`docs/architecture.md`和`docs/domain-model.md`，建立初始设计文档\n4. 删除所有示例注释块，替换为真实内容\n5. 启动Codex CLI会话，它会自动加载`AGENTS.md`\n\n之后就可以通过`$new-feature`、`$review-ready`、`$review-fix`等命令驱动工作流了。\n\n## 适用场景与价值\n\n这套工作流模板特别适合以下场景：\n\n- **复杂系统开发**：当项目涉及多个模块、需要清晰的架构边界时\n- **团队协作**：当多名开发者需要共享上下文、保持一致性时\n- **长期维护**：当项目需要持续演进、文档需要跟上代码变化时\n- **AI辅助开发**：当希望充分发挥推理模型和编程Agent各自优势时\n\n通过结构化的文档体系和自动化的反馈机制，该模板帮助团队解决了AI辅助开发中的核心痛点：如何让"思考者"和"执行者"有效协作，如何让知识在两者之间顺畅流转，如何让架构设计真正落地到代码实现。\n\n## 结语\n\nCodex Workflow Template代表了一种新兴的AI辅助开发范式——不再是简单地把AI当作代码生成工具，而是将其纳入系统化的工程流程中，通过明确的分工和规范的接口，实现人机协作的规模化。\n\n随着AI编程助手能力的不断增强，类似这样的工作流框架将会变得越来越重要。它们不仅提高了开发效率，更重要的是确保了在AI深度参与的情况下，软件工程的核心原则——可维护性、可追踪性、可协作性——仍然能够得到保障。