Codex 高级用法：工程协作工作流 · 组织专业能力与角色交接
交接不是一句“继续”：让上下文跨角色不丢失
把 Agent 交接写成可验证的阶段契约，明确传递目标、真实路径、当前状态、授权、证据、风险和接收方产物，让下游角色先核对现场再继续工作。
“文章已经规划好了，请继续处理。”
这句话对刚参加完讨论的人似乎够用，换一个 Agent 就不够了。它不知道“文章”是哪一篇，规划写在哪个文件，用户确认了正文方向还是只确认了章节，前一个角色做到了什么，又有哪些事实没有核验。接收者只能翻聊天记录、猜路径，或者拿一句含糊授权继续往下做。
小编现阶段的判断是：Agent 交接要传递的不是一段对话气氛，而是一份可以重新核对的任务现场。 聊天历史可以辅助理解，不能代替目标、路径、状态、授权、证据和风险这些工程事实。
上一篇已经给三个专业 Agent 划清职责。本文只处理它们怎样串行交接，不重复角色定义，也不讨论实现完成后的测试与最终验收。
一、一句“继续”丢掉了什么
根据 OpenAI 的 Subagents 官方说明，subagent 在独立的 agent thread 中运行，主线程负责启动、等待和汇总结果。独立 thread 能隔离中间工作，但我们也不能假设接收角色天然拿到了上游没有明确传递的全部现场信息。
共享工作区只解决了一部分问题。新 Agent 可以重新读取磁盘，却仍要先知道应该读哪个目录、哪个状态文件和哪一份产物。对话历史则恰好相反：它可能保留讨论过程，但其中的旧方案、被否决选择和过期路径混在一起，不适合直接充当当前事实来源。
一句“继续”通常省掉了几类关键差异：
- 目标与对象：是继续规划、写正文，还是审阅现有草稿；
- 磁盘事实：系列根目录、状态文件和目标产物的实际路径；
- 授权边界：用户允许读取、创建、修改或发布到哪一步；
- 阶段状态：哪些工作已完成，哪些只是上游声称完成；
- 不确定项：哪些是事实，哪些是推断、用户选择或仍待验证的内容；
- 返回条件：接收角色要留下什么，失败时把任务退回给谁。
信息缺失后，下游可能重复做已经完成的工作，也可能把“用户认可方向”误解成“授权覆盖文件”。更麻烦的情况是，上游把一个尚未核验的判断写得很顺，下游接过来便当成了既定事实。
二、交接是一份阶段契约
当前 JVS 项目的根目录 AGENTS.md 已经规定了交接字段。把这些字段按用途整理后，一份可工作的交接可以分成现场、依据和返回要求三部分。
2.1 先把任务现场钉在真实路径上
交接开头应明确系列根目录、topic.md、文章编号、标题和正文绝对路径。绝对路径看起来啰嗦，却能避免接收者在多个同名目录、旧草稿和当前文件之间猜测。
目标也要写成当前阶段可以完成的一句话。例如“按已确认规划撰写 03-03，并执行写后自审”比“把这一章做好”更容易判断是否越界。当前状态应同时来自任务说明和磁盘检查；两者冲突时，以重新读取的文件为事实，并把冲突返回，而不是任选一个继续。
2.2 把事实、选择和未知项分开
“素材包已确认”这类压缩句容易隐藏问题。交接中至少要区分：
- 已确认事实：可以由项目文件或可靠来源重新核对；
- 用户选择：用户明确接受的方向、范围和取舍；
- 上游推断：基于材料形成、但不应冒充用户决定的判断；
- 待验证项：缺少证据，或会随产品版本变化的事实。
授权范围单独记录。用户同意章节规划，不自动等于允许写正文；允许本地写入，也不自动覆盖发布、删除或外部系统操作。需求或方案发生实质变化后，旧授权能否继续适用，应回到前一篇的确认门禁重新判断。
“已完成证据”同样不能只写成完成声明。它可以是已存在的文件、状态字段、差异结果或来源链接。这里记录证据是为了让接收者定位和复查上游产物，不代表整项任务已经通过最终验收。
2.3 写清产物，也写清失败返回
接收角色需要一个明确产物，例如指定路径的正文、独立审阅报告或结构化调研结论。还要说明允许修改哪些文件、应保持什么状态，以及完成后返回哪些摘要。
失败返回比“遇到问题及时沟通”更具体。关键路径不存在、状态与交接不一致、授权范围不足、必要事实无法核验时，接收者应停止相关写入，列出缺口和已经完成的只读检查，再把任务退回流程负责人。这样失败仍然会留下可继续处理的状态，而不是悄悄补猜测。
三、把当前写作链路写成标准交接
下面这份模板来自本项目 AGENTS.md 的交接契约，并补上了证据与失败返回。它是项目约定，不是 Codex 内置格式；其他仓库可以换字段名，但不应省掉同等信息。
1handoff:
2 objective: 当前阶段要完成的单一目标
3 workspace:
4 series_root: 系列根目录绝对路径
5 topic_file: topic.md 绝对路径
6 target_file: 目标产物绝对路径
7 target:
8 article_id: 文章编号
9 title: 标题
10 authorization:
11 confirmed_by_user: 用户已经确认的内容
12 allowed_actions: 本阶段允许执行的动作
13 excluded_actions: 未授权或不属于本阶段的动作
14 current_state:
15 declared_status: 上游交付时声明的状态
16 source_of_truth: 状态应从哪里复查
17 inputs:
18 materials: 输入材料或素材包
19 dependencies: 必须先读取的前置产物
20 evidence:
21 completed: 已完成产物及其路径
22 not_yet_proven: 不能由现有证据支持的结论
23 open_items:
24 risks: 已知风险
25 facts_to_verify: 待验证事实
26 decisions_pending: 未决事项
27 expected_output:
28 deliverable: 接收角色必须生成的产物
29 return_to: 完成后返回给谁
30 failure_return:
31 stop_when: 必须停止的条件
32 report: 失败时返回的缺口、检查结果和真实状态模板不是让主线程复制一份空表。每个值都应落到本次任务的实际对象。字段为空时，也要说明“无”或“尚未确认”，避免接收者分不清遗漏与确实不存在。
四、模拟一次从规划角色到写作角色的交接
下面以本文为目标，模拟写作启动前 topic_master 交给 article_master 的消息。路径和规划来自当前项目，planned 也是启动前应复查的状态；“需要完成的产物”是交接要求，不表示正文或质检已经成功。
1handoff:
2 objective: 按已确认规划撰写 03-03，并执行 jvs-write 的第二遍自审
3 workspace:
4 series_root: /Users/abm/AI-DEV/jvs/codex-advanced-usage
5 topic_file: /Users/abm/AI-DEV/jvs/codex-advanced-usage/topic.md
6 target_file: /Users/abm/AI-DEV/jvs/codex-advanced-usage/articles/03-03-build-reliable-codex-agent-handoffs.md
7 target:
8 article_id: 03-03
9 title: 交接不是一句“继续”：让上下文跨角色不丢失
10 authorization:
11 confirmed_by_user: 已确认全部章节规划，并授权按推荐顺序自动写作
12 allowed_actions: 创建目标正文、执行自审、回写 03-03 草稿状态
13 excluded_actions: 配图、发布、独立质检、修改其他文章规划
14 current_state:
15 declared_status: planned
16 source_of_truth: topic.md 中 03-03 的状态与目标路径
17 inputs:
18 materials:
19 - topic.md 中的系列边界、统一约定和 03-03 文章规划
20 - /Users/abm/AI-DEV/jvs/AGENTS.md 中的交接字段
21 - jvs-write 的风格、结构与自审规范
22 dependencies:
23 - articles/03-01-choose-between-codex-skills-and-agents.md
24 - articles/03-02-design-specialized-codex-agents.md
25 evidence:
26 completed:
27 - topic.md 已存在 03-03 的编号、标题、核心问题、内容要点和目标路径
28 - AGENTS.md 已定义三角色链路与交接契约
29 not_yet_proven:
30 - 03-03 正文通过独立质检
31 - 本系列贯穿任务已完成最终验收
32 open_items:
33 risks:
34 - 不要重复 03-02 的角色定义
35 - 不要侵入第 4 章的实现证据与最终验收
36 facts_to_verify:
37 - 涉及 Codex subagent 当前行为时核对官方文档
38 decisions_pending: 贯穿案例最终采用哪个真实代码仓库仍待后续确定
39 expected_output:
40 deliverable: 目标正文完整落盘，正文与 topic.md 状态均为 drafted
41 return_to: topic_master
42 failure_return:
43 stop_when: 路径或状态冲突、授权不足、关键事实无法核验
44 report: 返回冲突位置、已做检查、未完成项和磁盘真实状态接收方拿到这份消息后，第一步仍然是读文件。它要确认路径存在、topic.md 的文章条目与消息一致、前置文章已达到可用状态、目标文件是否已有内容，以及授权是否覆盖即将执行的写入。交接契约减少猜测，不取消校验责任。
写作完成后，同样的结构可以继续用于 article_master 返回 topic_master：把目标正文路径、磁盘状态、采用的核心判断、引用来源、仍待核事实和自审结果交回。随后流程负责人再把正文、素材包与重点核验项交给 article_reviewer。质检员会重新读取事实并形成独立报告，不能因为上游写了“自审通过”就直接放行。
五、交接失败时，退回缺口而不是补猜测
可靠交接不追求一次把所有信息写到完美。它更重要的能力，是让接收者知道什么时候不能继续。
假设交接写着“用户已确认，可以发布”，但消息里只有正文写作授权，磁盘上也没有发布目标。接收者应退回授权缺口，不能把“系列要自动推进”扩展成外部发布许可。另一个常见冲突是上游声明状态为 drafted，而正文文件仍不存在；接收者要报告两处事实不一致，不能先造一个文件来配合声明。
退回消息至少说明四件事：在哪个字段发现冲突，重新检查了哪些事实，目前能确认到什么状态，以及需要上游补充材料、修正状态还是重新取得用户确认。已经安全完成的只读检查可以保留，产生副作用的动作则停在授权边界前。
这套做法适合有明确阶段和文件产物的串行任务。短小、同一角色一次完成且没有授权分叉的工作，不需要为形式填一份长表；把关键目标、对象和边界说清即可。角色一旦切换，或任务涉及多份事实来源、写入和用户选择，结构化交接的成本通常比事后追查低。
一句“继续”把理解责任推给了下游。阶段契约则把现场放回可检查的对象上：目标是什么，文件在哪里，用户允许做到哪一步，上游留下了哪些证据，还有什么没有证明，接收者应产出什么，失败时退回什么。不同 Agent 可以保留各自的职责和上下文，又不会因此断开同一条任务事实链。
