用 Codex 配 Superpowers 跑过并行任务吗？

跑着跑着，子代理就卡在那里不动了。日志里什么都输出，Codex 也在运行，可就是不出结果。你去翻 AGENTS.md，里面写的是 wait。错了。正确的写法是 wait_agent。

这是 V2 版本踩过的坑。现在 V3 把这个问题修了，还顺手精简了整个流程。

为什么 V3 不是简单升级

V1 和 V2 的 AGENTS.md 试水性质比较浓。V1 讲究任务分流，V2 在这个基础上加了自动判断，叙述重复、逻辑冗长，上下文占了一堆，跑起来效果一般。

V3 干了三件事：精简分流流程（把绕来绕去的判断条件压扁了），修子代理等待 bug（用 wait_agent 替 wait，向 Superpowers 提过 PR），加并行优先化（writeplan 后自动研究并行可行性）。

结果就是：上下文更短了，但覆盖场景反而更完整了。

AGENTS.md 优先级逻辑：四层覆盖

AGENTS.md 不是随便写，它是按优先级生效的。从高到低：

1. 当前会话中用户的明确要求
2. 仓库自身规则、文档与约定
3. 本 AGENTS.md
4. 相关 Superpowers / skill 流程定义

Codex 启动时会读取 ~/.codex/AGENTS.md（全局）和项目根目录的 AGENTS.md（项目级），项目级覆盖全局，逻辑和 .gitignore 一样。

这个设计的好处是：你在公司项目里套一层公司的规范，回家开个人项目又有另一套规矩，两边互不干扰。

轻重分流：让 AI 学会偷懒

V3 里最核心的原则就一句话：适合并行的优先并行，不适合的才串行。

“偷懒"这个词在这里是褒义。AI 如果遇到一个小任务，比如改一行配置或者修一个单文件的 bug，你让它走完整的 brainstorming、writing-plans、implementation、review 全套流程，等于让大厨去炒一盘蛋炒饭还要写菜品设计文档。

V3 把任务分成两类：

  • 只读任务：分析、解释、架构说明、代码阅读，直接处理，不进实现流程。
  • 轻量任务：单文件修改、明确 bug 修复、配置调整，跳过 brainstorming 和重 review，直接实现。

剩下就是重量任务。新功能、公共 API、并发逻辑、大规模重构——这些老老实实走完整流程。

这里的关键不是"什么时候降级”，而是"什么时候升级"。改动超出初始判断、涉及共享 contract、需求不清晰——这些信号一出现，立刻升级到更重流程，而不是硬撑着走轻路径。

并行开发的正确打开方式

V3 在并行这块下了重手。

子代理派发有硬性规定：model 和 reasoning_effort 必须显式设置。模型只允许用 gpt-5.4 和 gpt-5.3-codex，默认用 gpt-5.4。推理强度只允许 high 或 xhigh，有歧义一律上调。

这个限制初看有点死板。随手选个不匹配的模型，子代理产出质量飘忽，整个并行策略就废了。

调度闭环也写死了：

spawn_agent → 记录 agent_id → wait_agent 等待 → 收集结果 → close_agent

不能用普通命令等待替代子代理等待语义。这条规则卡死了，并行才能真正跑通。

并行准入也划了线：任务可拆为 2 到 4 个边界清晰的子任务，scope_write/scope_read 明确，可独立验证，无明显同文件写冲突——才适合并行。

如果改动集中在 1 到 2 个核心文件，涉及 shared contract 或 shared types，或者拆分后返工整合风险明显增加——老实串行，别硬拆。

Ownership 规则也很直接：禁止两个子任务同时改同一个文件、同一个配置源、同一个 contract。package.json、lockfile、根级 build/lint/test 配置、CI、schema、migration、公共适配层——默认串行或统一收尾。

子代理等待的坑：wait vs wait_agent

这是 V2 到 V3 之间踩出来的坑。

很多人在 AGENTS.md 里写的是 wait，结果子代理就卡在那里。原因是 wait 的语义和你想的不一样——它不会等子代理真正产出结果，它只是等待一段时间然后继续。

wait_agent 才是正确的选择：它会等子代理完成任务或者真正阻塞，再返回控制权。

这个 bug 已经在 Superpowers 的代码里修了，V3 的 AGENTS.md 用的就是修正后的语义。

Codex 测试分级：不是每个任务都需要 TDD

V3 给了四个测试级别，按场景选择：

Level 0：定向验证 — 局部、低风险、小改动
Level 1：回归测试 — 中小修复或局部行为变化
Level 2：TDD — 新功能、明确行为变更、共享逻辑
Level 3：Code Review — 遵循 review 规则
Level 4：Completion Verification — 完成前最终验证

TDD 不是默认选项。按"行为影响、共享范围、回归风险、测试价值"这四个维度显式判定要不要 TDD。

很多团队一听到 AI 编程辅助就想着全上 TDD，结果 AI 生成一堆测试，真正的核心逻辑反而没覆盖。V3 的建议是：定向验证先走，覆盖关键路径，测试价值不高的场景不强求。

commit 规范：说人话，别废话

格式是 <type>(scope): <summary>，scope 可选，summary 用中文、动词开头、长度不超过 50 字、不加句号。

常用 type：feat / fix / refactor / docs / test / chore

举例：fix(auth): 修复 token 过期后不刷新

AGENTS.md 完整配置

这份 AGENTS.md 整合了上面所有规则。复制到 ~/.codex/AGENTS.md 或者项目根目录，按需调整。

# 全局 Agent 规则

## 指令优先级
1. 当前会话中用户的明确要求
2. 仓库自身规则、文档与约定
3. 本 AGENTS.md
4. 相关 Superpowers / skill 流程定义

## 默认原则

### 最短路径与并行轻重分流
- 默认采用"满足质量要求的最短路径"
- 默认先判断任务是否适合并行；适合则优先并行，不适合再串行
- 能直接完成并验证的，不升级为更重流程
- 能用轻量 planning 解决的小任务，不升级为重文档流程
- 能用单一专项 skill 解决的，不扩展为 full Superpowers

### 轻量任务默认策略
- 轻量任务：单文件修改、明确 bug 修复、配置调整、小测试补充
- 默认可跳过完整 brainstorming、writing-plans、using-git-worktrees 与重 review 链
- 提问：轻量任务首次最多问 1 个关键问题；中任务优先一次性给 2 到 3 个方案
- 默认授权边界：当前分支内可默认修改直接相关的应用代码、测试、局部文档
- 以下操作必须确认：删除文件、大规模重构、shared contract、根配置、CI、数据库变更

### 流程升级 / 降级
- 升级：影响边界超出初始判断、涉及公共 API / schema / 持久化 / 并发、需求不清晰
- 降级：改动局部边界清晰、不涉及共享核心逻辑、验证直接

## 任务分流模型

### 只读任务
- 分析、解释、架构说明、代码阅读——直接处理
- 问题排查优先用 systematic-debugging

### 实现任务
- 默认流程：brainstorming -> writing-plans -> implementation
- 轻量版 planning 至少明确：目标、边界、风险、验证方式
- Review 用 requesting-code-review / receiving-code-review
- 完成前执行 verification-before-completion

## 并行开发总控

### 子代理派发
- spawn_agent 必须显式设置 model 和 reasoning_effort
- 模型仅允许 gpt-5.4（默认）和 gpt-5.3-codex
- reasoning_effort 仅允许 high 或 xhigh

### 调度闭环
- spawn_agent → 记录 agent_id → wait_agent 等待 → 收集结果 → close_agent
- 不要用普通命令等待替代子代理等待语义

### 并行准入
- 适合并行：可拆 2-4 个边界清晰、可独立验证的子任务
- 不适合并行：改动集中在 1-2 个核心文件、涉及 shared contract、需要独立分支隔离

### 收尾整合
- 子任务完成后必须统一收尾
- 至少包括：汇总改动、检查冲突面、运行最终验证、输出 merge plan

## 测试策略
- Level 0：定向验证（局部、低风险）
- Level 1：回归测试（中小修复）
- Level 2：TDD（新功能、共享逻辑、高风险改动）
- Level 3：Code Review
- Level 4：Completion Verification

## commit 规范
- 格式：<type>(scope): <summary>
- 常用 type：feat / fix / refactor / docs / test / chore
- summary：中文、动词开头、≤50 字、不加句号

## Safety Rules
- 不运行破坏性命令（git reset 等），除非用户明确要求
- 不使用非 Git 工具操作 .git
- 不将密钥、API Key 硬编码进源码
- 数据库访问使用参数化查询
- 不用不可信输入拼接 shell 命令或 SQL

## 技能调用
主干整合方式：
- 实现前：brainstorming -> writing-plans
- debug：systematic-debugging
- review：requesting-code-review / receiving-code-review
- 完成前：verification-before-completion
- 前端设计：ui-ux-pro-max

用起来的几个建议

拿到这份 AGENTS.md，不要直接全量上。先挑一个中等规模的项目试水，观察 Codex 的行为是否符合预期。

重点盯几个信号：并行任务有没有真的在同时跑，子代理有没有出现"假死"（看起来在运行但不出结果），commit message 的格式有没有被正确遵循。

这几个点没问题，再迁移到其他项目。

FAQ

Q: 全局 AGENTS.md 和项目级 AGENTS.md 同时存在时哪个生效？

项目级覆盖全局。Codex 会把两个文件的内容合并，项目级的规则优先级更高。

Q: 子代理卡死了怎么办？

先检查是不是还在用 wait 而不是 wait_agent。V3 的配置里已经统一用 wait_agent。如果问题依旧，检查任务是否真的适合并行——有些场景拆分后整合成本反而更高。

Q: 轻量任务不想跳过 brainstorm 可以吗？

可以。AGENTS.md 是默认规则，用户在当前会话提出明确要求时，优先级高于 AGENTS.md。

顺便分享一个我常用的 AI自媒体运营工具 ，覆盖内容排版、素材处理和效率提效，写公众号会更省力。

最近在玩 Claude Code 的新功能，发现官方出了个 Codex 增强版门户 ，把各种智能编程能力整合在一起了，感兴趣可以去看看。

如果你想看到更多这类工具测评和 AI 编程实战，欢迎关注我的公众号「梦兽编程交个朋友」，每周更新。