作者：泽哥｜灏仟亿前端技术团队
核心观点： AI 编程真正带来的变化，不只是单个工程师写代码更快，而是把需求理解、计划拆解、工具调用、代码实现和验证证据统一到一套可治理的交付流程里。团队可以由此把 Codex 从个人提效工具，落地成可复制、可审计、可持续优化的研发工作流。
1. 选型基础：为什么是 Codex + superpowers
在讨论工作流之前，需要先明确两个基础选择：Codex 提供的是可进入真实工程环境的执行载体，superpowers 提供的是可复用的工程方法层。前者解决“AI 如何参与实际开发”，后者解决“AI 参与开发时如何保持稳定质量”。
| 组成部分 | 选择原因 | 在工作流中的角色 |
|---|---|---|
| Codex | 能够进入本地仓库上下文，读取代码、编辑文件、运行命令、调用浏览器和外部工具，并受沙箱与审批机制约束。 | 作为执行层和工具编排层，负责把需求推进到真实代码、验证命令和交付结果。 |
| superpowers | 把计划、TDD、系统化调试、验证、代码审查、子 Agent 协作等工程习惯沉淀为可触发的 skills。 | 作为方法层和质量约束层，负责让 Codex 在不同任务中遵循一致的工程动作和完成标准。 |
组合价值： Codex 让 AI 能真正进入工程现场，superpowers 让 AI 在工程现场按可复用的方法工作。两者结合后，团队获得的不只是更快的代码生成，而是一套可以被配置、验证和持续优化的 AI 研发交付机制。
1.1 Superpowers 的流程角色
Superpowers 可以理解成一套给 coding agent 使用的“流程技能包”。它不是单纯 prompt，也不是独立的 multi-agent runtime，而是通过一组可组合的 SKILL.md，让 agent 在不同研发场景下自动进入对应流程，减少凭感觉执行。
| 机制 | 含义 | 对工作流的影响 |
|---|---|---|
| Skill 触发机制 | 每个 skill 通过 name 和 description 声明适用场景，agent 根据任务判断是否加载。 | 让 agent 先选择流程，再执行动作，减少一上来就写代码。 |
| 流程替代即兴发挥 | 把澄清目标、设计、计划、TDD、调试、review、收尾变成稳定步骤。 | 提升任务可复盘性，让复杂任务不依赖单次 prompt 质量。 |
| Skill 是流程合同 | 例如 brainstorming 要求先澄清和拿到设计批准，writing-plans 要求拆清文件、测试和验证步骤。 | 把团队希望 agent 遵守的工程纪律写进可复用文件。 |
| Subagent 是可选加速手段 | subagent-driven-development 适合边界清楚的并行任务；没有 subagent 支持时，可以退回顺序执行。 | 避免把 Superpowers 误解成 multi-agent runtime，本体仍是方法论和 skill 层。 |
| 与 Codex multi-agent 的关系 | Superpowers 决定什么时候拆任务、什么时候 review、怎么验证；Codex agent 配置决定可调用 agent、模型和权限。 | 两者互补：一个定义方法，一个提供运行时能力和治理边界。 |
| 场景 | 推荐路径 | 完成标准 |
|---|---|---|
| 新功能 / 行为变更 | brainstorming → writing-plans → test-driven-development → requesting-code-review → finishing-a-development-branch | 有设计、计划、测试和验证证据 |
| 已有计划执行 | executing-plans；任务可拆且边界清楚时使用 subagent-driven-development | 计划项逐项闭环 |
| Bug / 构建失败 / 测试失败 | systematic-debugging 先定位 root cause，再进入修复和验证 | 有根因说明和回归验证 |
| 代码评审 | requesting-code-review 提供精确上下文，优先处理 Critical / Important 问题 | 风险清单已处理或说明取舍 |
2. 为什么需要一套 AI 开发工作流
AI 编程已经进入日常研发，但真正的难点不在于让 AI 写出某段代码，而在于让它稳定地理解目标、选择工具、控制改动范围，并在完成前给出验证证据。没有工作流时，提效会停留在个人经验；有工作流后，团队才能把 Codex 纳入可治理的交付体系。
| 关键问题 | 没有工作流时 | 接入工作流后 |
|---|---|---|
| 需求理解 | 依赖临场提示词，容易直接跳到编码 | 先判断任务类型、风险和验收标准，再决定流程重量 |
| 工具调用 | shell、浏览器、MCP、文档工具各自分散，过程难复盘 | 按任务触发 skills、插件和本地工具，关键动作有权限边界 |
| 协作方式 | Multi-Agent 容易重复调研、覆盖改动或失去主控 | Main Agent 持有主线，子 Agent 只处理边界清晰的独立任务 |
| 完成标准 | “代码写完”容易被误认为“任务完成” | 完成声明必须带 fresh verification：测试、构建、页面检查或可复核证据 |
3. 接入前后：从个人提效到团队机制
这套工作流的核心变化，是把“会用 AI”升级为“会治理 AI 参与研发”。接入前，效果主要取决于个人提示词和临场判断；接入后，团队用同一套任务分层、工具边界和完成标准来约束 Codex 的执行行为。
接入前：个人经验驱动
- 需求一来就容易直接进入编码
- 计划、边界和验收标准依赖个人习惯
- 工具调用分散，出错后难以复盘
- 多 Agent 容易重复调研、互相覆盖或失去主控
- 完成判断常停留在“代码写完”或“看起来可以”
接入后：团队机制驱动
- 先判断任务风险，再选择流程重量
- skills、插件、MCP 和 shell 规则按任务触发
- 行为变更优先测试先行，复杂任务先拆边界
- Main Agent 对计划、集成和最终验收负责
- 完成声明必须附带 fresh verification 证据
4. 标准工作流：按任务风险分层
这张流程图的重点不是让所有任务都走完整链路，而是说明“任务风险决定流程重量”。轻量问题可以快速处理；涉及行为变化、线上风险或多人协作时，必须前置计划、验证策略和边界拆分。
| 任务类型 | 推荐流程 | 验证证据 | 治理重点 |
|---|---|---|---|
| 轻量任务 | 读取上下文 → 直接回答或小范围修改 → 最小验证 | 关键命令、静态检查或可复核输出 | 保持速度，避免过度流程化 |
| 功能开发 / Bug 修复 | 理解需求 → 计划拆解 → 必要时 TDD → 实现 → 验证 | 测试、构建、复现步骤或页面检查 | 让行为变更始终伴随证据 |
| 复杂任务 | 拆分边界 → 确认验收标准 → 决定是否引入子 Agent | 主线集成结果、分支任务摘要和最终验证 | 允许并行，但主控不能丢 |
| 代码审查 | 优先查缺陷、回归风险、遗漏测试和行为偏差 | 按严重程度排序，带文件和行号依据 | 审查重点是风险发现 |
关键原则： 这不是一套“越复杂越专业”的流程，而是一套“按风险加治理”的流程。小任务保持速度，大任务增加计划、测试和验证，避免 AI 把不确定性藏进代码里。
5. Multi-Agent：可控并行，而非放任协作
Multi-Agent 的价值不是“多叫几个 AI 一起做”，而是在边界清晰时把调研、实现和审查拆开并行。主线必须始终由 Main Agent 持有：它负责上下文、计划、写入边界、结果集成和最终验收。
| 协作角色 | 适用场景 | 治理规则 |
|---|---|---|
| Main Agent | 所有任务的事实源，负责计划、调度、集成和验收 | 不能把最终判断、风险取舍和完成声明外包 |
| Explorer | 定向调研代码库、依赖、接口、历史实现或文档 | 问题必须具体，输出结论和证据，不重复主线工作 |
| Worker | 处理独立、边界明确、写入范围不重叠的实现任务 | 必须声明文件归属，不回滚他人改动，交付可验证结果 |
| Reviewer | 做规格检查、代码审查、测试覆盖或风险复核 | 审查结论是输入，最终判断仍由 Main Agent 汇总 |
禁用边界： 任务边界不清、多个 Agent 会编辑同一文件、主线被子任务阻塞、或用户没有明确要求并行时，不启用 Multi-Agent。并行能力必须服务于交付确定性，而不是制造新的协调成本。
6. 落地：superpowers 与 Agent 配置
工作流要能复制，必须从“口头要求”变成“运行时约束”。落地时建议分三层：用 superpowers / skills 固化通用方法，用 AGENTS.md 固化仓库规则，用 Agent 调度策略固化协作边界。
6.1 superpowers / skills 配置
| 配置层 | 落地点 | 对团队的作用 |
|---|---|---|
| 全局 skills | $CODEX_HOME/skills、系统 skills、插件 skills | 沉淀计划、TDD、调试、验证、代码审查、文档读写等通用方法 |
| superpowers | 按任务触发的研发方法集合 | 让 Codex 在关键场景主动进入计划、测试、调试或验证流程 |
| 仓库规则 | 项目根目录 AGENTS.md | 固化命令前缀、权限边界、测试构建、UI 验收和输出语言 |
| 验证门禁 | verification-before-completion 与项目验证命令 | 把“完成”从主观判断改成可复核证据 |
推荐扩展的 SkillHub skills： superpowers 作为方法底座默认保留；团队落地时建议额外接入以下项目级 skills，用来把工作流从“会话方法”进一步固化到仓库和任务过程里。
- project-bootstrap-contract：用于初始化或刷新项目级工作合同，补齐
AGENTS.md、命令规范、验证入口和仓库约束，让 Codex 进入项目时先有稳定边界。 - planning-with-files-zh：用于复杂任务的中文文件化规划，把拆解、状态、验证和遗留风险沉淀到可追踪文件中，适合多人协作和长任务执行。
6.2 Agent 配置落地
| 配置对象 | 建议做法 | 必须固化的边界 |
|---|---|---|
| Main Agent | 由当前 Codex 会话承载，结合 AGENTS.md 和已加载 skills 执行 | 持有完整计划，保护工作区，统一调度，最终验收 |
| Explorer | 只在需要定向调研时派发，问题必须足够具体 | 只回传结论、证据和风险，不直接改主线代码 |
| Worker | 只处理清晰、独立、写入范围不重叠的实现任务 | 声明文件归属，不回滚他人改动，完成后列出改动路径和验证结果 |
| Reviewer | 用于规格检查、质量审查、测试覆盖或风险复核 | 输出按严重程度排序的问题，最终判断仍由 Main Agent 完成 |
| 模型选择 | 子 Agent 默认继承父模型；只有任务有明确理由时才覆盖 | 不维护固定角色-模型表，避免模型版本变化后文档失真 |
# 语言与输出
- 对话、计划和交付说明使用简体中文
# 命令规范
- 所有 shell 命令统一使用 rtk 前缀
- 优先使用项目已有的测试、构建和格式化命令
# 编辑与权限
- 手工改文件优先使用 apply_patch
- 不回滚用户或其他 Agent 的改动
- 沙箱外、联网和高风险写操作必须经过审批
# 完成标准
- 交付前必须执行 fresh verification
- 最终说明写清楚改动范围、验证命令和遗留风险
落地原则： 配置不是为了让流程变重，而是为了让关键规则自动生效。能写进 AGENTS.md 的仓库约束不要只写在会议文档里；能沉淀成 skill 的通用方法不要依赖个人提示词；能由验证命令证明的结果不要靠口头判断。
7. 工具与验证治理：让完成有证据
工具治理的重点，是让 Codex 的每一次外部动作都有边界。实际运行时会同时涉及 shell、文件编辑、浏览器验证、飞书文档、插件懒加载、MCP、沙箱权限和人工审批；这些能力必须共同服务于一个目标：完成声明要有证据。
| 治理对象 | 当前规则 | 团队价值 |
|---|---|---|
| Shell | 仓库命令统一前缀 rtk，减少冗余输出 | 让命令执行和日志摘要更适合长任务上下文 |
| 文件编辑 | 手工改文件优先使用 apply_patch | 降低误改范围，保留可审查的 diff |
| 权限审批 | 沙箱外、联网和高风险写操作需要显式批准 | 防止 AI 绕过组织的安全和变更门禁 |
| 浏览器 / UI | 页面变更后用 Browser、Playwright 或截图验证 | 让 UI 任务从“代码已改”走到“体验可验” |
| 飞书沉淀 | 计划、交付说明、复盘和方法文档沉淀到知识库 | 把个体经验转成团队资产 |
| 完成声明 | 没有 fresh verification，就不能声称完成 | 把“相信 AI”改成“验证 AI 的结果” |
8. 团队落地路线图
| 阶段 | 要完成的事 | 产出物 |
|---|---|---|
| 准备期 | 选择 1-2 个试点仓库，梳理常用命令、权限边界、核心 skills 和验证方式 | AGENTS.md、skills 清单、测试 / 构建 / UI 验收命令 |
| 试点期 | 挑选真实任务运行流程，记录计划、关键决策、工具调用和验证结果 | 任务样本、验证证据、返工原因分类 |
| 推广期 | 沉淀可复用模板，明确哪些任务轻量处理、哪些任务必须计划和验证 | 团队工作流说明、代码审查标准、实践案例 |
| 运营期 | 定期复盘指标，更新 skills、Agent 配置和仓库规则 | 月度复盘、配置变更记录、最佳实践样例 |
试点观察指标
| 指标 | 观察方式 | 判断价值 |
|---|---|---|
| 开发周期 | 对比同类任务从开始到可验收的耗时 | 观察是否减少等待、返工和上下文切换 |
| 首次验证通过率 | 统计完成声明后测试、构建、页面检查一次通过比例 | 衡量验证前置是否真正降低返工 |
| 返工原因 | 按需求理解、边界拆分、测试缺失、实现错误、工具误用分类 | 指导下一轮 skills 和 AGENTS.md 优化 |
| 复盘完整度 | 检查是否保留计划、关键决策、验证证据和遗留风险 | 衡量团队能否复制成功经验 |
9. 结论
这套方案最终要传递的不是“用了某个 AI 工具”，而是“团队把 AI 编程纳入了可治理的研发体系”。它既保留轻量任务的速度，也为复杂任务补上计划、协作、验证和复盘。
核心结论： 小任务保持轻量，大任务先计划和验证；Multi-Agent 只在边界清晰时受控并行；所有完成声明都必须有可复核证据。真正的提效，不是让 AI 多写代码，而是让团队更稳定地交付正确结果。
