Codex agent team：让 Codex 有团队干活

我最近越来越强烈地感觉到，Codex 真正难的地方，已经不是“它会不会写代码”了。

小任务当然没问题。你让它改一个组件、补一个脚本、修一个构建错误，它通常都能很快下手。麻烦的是项目一复杂，事情就不再只是“把这段代码写对”。它会开始牵扯设计判断、测试复现、规范维护、文档补充、交付收口。一个 agent 在做 A 的时候，常常会顺手发现 B。B 可能不是它该改的东西，但如果这个发现只留在对话里，过一会儿就丢了。

我之前用 Codex 时，最常遇到的就是这种场面。它在修一个前端问题，顺手发现设计规范不一致；它在补一个功能，顺手发现 README 过期；它在跑验证，顺手发现另一个交互 bug。每个“顺手”看起来都很高效，但项目一大，就会慢慢变成失控。你开始搞不清楚谁处理了什么，哪些问题只是被看到，哪些已经有人接了，哪些改动做完了但还没验证。

我后来发现，Codex 缺的不是多一个聪明 agent，而是一个交接层。Skill 获取方式：

我最早是从 Claude Code 那边得到启发的

Claude Code 的 Agent Teams 给我最大的启发，不是“它能同时开很多 agent”，而是它把协作这件事本身当成了一等公民。不同角色分开，主线程负责判断和收口，中间的交接不是靠记忆，而是靠机制。

我借鉴的其实也就三件事。

第一，职责要拆开。复杂项目里的问题本来就不是一种问题。体验问题、实现问题、规范问题、验证问题、文档问题，看起来都跟“做项目”有关，但判断方式完全不一样。全塞给同一个 agent，它迟早一边修 bug 一边越改越散。

第二，发现跨职责问题时，不要顺手改，先交接。这个规则非常重要。很多项目不是死在能力不够，而是死在边界不清。谁都能碰一点，最后谁都说不清为什么这么改。

第三，交接一定要留下记录。不是为了仪式感，而是因为线程会变，主线程会换，人也会忘。只有把问题、owner、状态、验证方式留在项目里，后面的人才能接得住。

我后来想，既然 Codex 现在没有内置这层东西，那我就先用最土的方法把它补出来。

我最后选的做法，其实很朴素

我没有去搭一个很重的系统，也没有上什么新的后端。最后留下来的，是项目里的几个 Markdown 文件和一个校验脚本。

AGENTS.md
ROSTER.md
agent-reports/
  QUEUE.md
  open/
  assigned/
  resolved/
  archived/

AGENTS.md 负责写规则。什么问题可以直接做，什么问题必须先写 report，哪些角色存在，各自管什么，交接发生时怎么处理，都会写在这里。

ROSTER.md 负责记角色席位。哪个角色现在有没有活跃 seat，当前 agent_id 和 thread_id 是什么，线程换掉以后该怎么恢复，靠它来接住。

agent-reports/ 是真正的交接区。一个 agent 在自己职责之外发现问题，不再“顺手修一下”，而是先写成 issue report。主线程看过以后分配 owner，处理的人再把 solution 和 integration summary 写回去。这样一个问题就不只是“有人提过”，而是会变成一条能分配、能追踪、能验证、能归档的记录。

我自己很喜欢的一点是，这套东西都留在项目里。它不是某个聊天窗口里的临时上下文，也不是一个外部工具里只有当事人才知道的状态。项目本身就是协作现场。

这个 skill 最后做成的样子

一开始我只是自己在项目里试这套方法。后来发现，真正麻烦的不是“想到这个思路”，而是每次都要重新把协议补一遍。

你得反复解释 report 怎么写，状态怎么流转，QUEUE.md 能不能直接改，ROSTER.md 和 issue owner 谁说了算，线程换了以后角色怎么恢复。只要这些边界有一点没说清，协作又会重新滑回“大家都在做事，但现场很乱”的状态。

所以我后来干脆把它整理成了一个 skill，叫 codex-agent-team。

它做的事情其实很明确：

• 把角色、状态、字段名、目录规则都收进统一 schema

• 规定 issue、solution、integration summary 的写回顺序

• 规定单 issue 只能有一个有效 owner

• 规定写 report 前要做版本复核，避免多人覆盖

• 提供 validator 去检查 ROSTER.md、agent-reports/ 和 QUEUE.md 有没有漂

如果你已经在 Canvasight / Codex 里开始做复杂项目，这个 skill 的价值不在于“帮你写几段提示词”，而在于它把原本容易口头约定、容易失效的协作规则，直接固化成一个可复用的协议。

它到底帮我挡掉了什么问题

最典型的一种情况，是测试 agent 发现了一个它不该自己修的问题。

比如测试时发现移动端下，需求卡片底部的完成按钮被固定底栏遮住了。以前这件事很容易变成一句对话里的提醒，或者被某个 agent 顺手改掉。改了也不是不行，但后面你很难知道它改了什么，为什么改，测过没有，风险在哪里。

现在我的做法会更克制一点。测试 agent 先在 agent-reports/open/ 写一个 issue，把复现方式、影响范围、相关文件和建议 owner 写清楚。主线程看过以后，再把它移到 assigned/。负责实现的 agent 修完以后，不是在对话里说一句“好了”，而是回到同一个 report 里写处理结果、修改文件、验证方式和后续风险。最后主线程或者测试再复验，通过之后再归档。

这套流程看着比“顺手修一下”慢一点，但项目大起来以后，它反而更快。因为你不用再反复捡上下文，不用猜某个问题是不是有人碰过，也不用在聊天历史里翻证据。

最值钱的不是“分工”，而是“可恢复”

很多 AI 协作方案都会讲角色，讲多 agent，讲分工。但项目真正跑久了以后，最值钱的其实不是你当下开了几个角色，而是几天后你还能不能把现场接回来。

线程会结束，任务会中断，角色会重建，甚至主线程自己也会换。这个时候，如果所有状态都只存在于一段对话里，那协作几乎等于没沉淀。

codex-agent-team 让我比较安心的一点，就是它默认把这些协作痕迹都落在项目里。新线程进来，先读 ROSTER.md，再读最新 report 和 integration summary，就知道哪些 seat 是活的，哪些问题还在跑，哪些已经收口。它不需要重新扮演“第一次理解这个项目的人”。

这件事听起来不性感，但它很实用。很多复杂项目最后拼的不是某一次输出有多聪明，而是谁能更稳定地持续工作。

注意事项

我现在不会把它用在每一个小需求上。

如果只是改个样式、补个文案、修个一眼能做完的小 bug，直接在主线程里做掉通常更合适。硬拆角色、硬走交接，反而会把简单问题搞复杂。

但如果你的项目已经开始出现这些信号，这个 skill 就会很有价值：

• 一个任务会跨产品、设计、开发、测试、文档几类角色

• 同一个问题需要跨多个回合推进

• 你已经遇到过“明明有人看到了，但后来没人接”的情况

• 你不想再靠聊天记录恢复上下文

• 你希望协作过程能沉淀成项目资产，而不是对话残影

它不是一个“让 AI 看起来更热闹”的 skill，而是一个“让复杂项目没那么容易乱掉”的 skill。

总结

我现在越来越少把 AI 编程理解成“随便说一句，让模型自己发挥”。对真正的项目来说，这种方式能跑一小段，但很难稳定跑很久。

我更愿意把接下来的重点理解成另一件事：人负责定边界、定协议、定收口方式，agent 在这个协议里执行、发现问题、交接问题、回写结果。模型当然还是要够强，但在很多时候，一个更适合长期工作的环境，比再多一点即兴聪明更重要。

codex-agent-team 就是在这个思路下长出来的。它不花哨，也不是某种“未来协作”的概念演示。它更像是我在真实项目里反复踩坑之后，最后留下来的一套工作方式。要说它最核心的价值，其实也很朴素：让 Codex 在复杂项目里，不只是会做事，而是能把事情接住、交出去、再收回来。