Codex 新人上手：从需求到上线的完整工作流是什么？
拿到 Codex 代码权限后，mentor 往往直接扔过来一个需求，比如“给 TUI 的 composer 增加粘贴 burst 模式”。面对 docs/、codex-rs/、.codex/skills/ 等众多目录，新人常常不知道从哪里开始。本文基于 Codex 仓库的典型开发流程，整理出一套从需求接收到功能上线的完整工作流。
第一步：判断是否需要写设计文档
Codex 没有强制所有功能都必须写设计文档。判断标准很简单：这个子系统的交互复杂度是否超出了代码本身能清晰表达的范围。
以“粘贴 burst 模式”为例，它涉及键盘事件处理顺序、composer 状态机、paste 检测逻辑，还存在非 ASCII 字符与 ASCII 字符的边界条件差异，同时会影响现有 Enter 键提交行为。这种情况就属于需要写设计文档的场景。
如果需求只是给某个配置项新增一个选项，直接写代码并加上 rustdoc 注释即可。
判断流程可以简化为：
接到需求 → 是否涉及多模块协调、复杂状态机或边界条件？ → 是则写设计文档，否则直接编码。
第二步：撰写设计文档并定义行为测试
Codex 的设计文档有固定结构，通常包含以下部分：
- 问题定义：用户一次性粘贴多行文本时，Enter 被误判为提交。
- 设计目标：区分“paste burst”和正常打字行为。
- 非目标：明确不支持超过 1000 字符的 burst。
- 实现方案：说明事件处理顺序和状态机调整。
- Tests that pin behavior：列出需要固定的关键测试用例。
写完设计文档后，先在 docs/ 目录下创建对应的 *-design.md 文件，并把测试用例作为验收标准固定下来。这样后续实现时就不会偏离方向。
第三步：使用轻量规格梳理任务
在正式动手前，建议先按 OpenSpec 或类似方式整理一份轻量规格，内容包括：
- 背景
- 目标
- 范围
- 不做什么
- 任务拆解
- 验收标准
把这些内容整理成文档放在 openspec/changes/ 对应目录下，能让后续每一步推进都有据可依。任务越清晰，Codex 执行时越稳定；任务越模糊，越容易出现方向偏差。
第四步：小步实现，每次只推进一件事
有了设计文档和规格后，进入实现阶段。新人最容易犯的错误是一次性要求 Codex 完成全部工作，比如“把后端、前端、测试、文档一起做完”。这样改动范围过大，一旦出错很难定位问题。
推荐做法是每次只让 Codex 推进一件事，例如先处理事件监听逻辑，再调整状态机，最后添加测试。每次改动后及时 review diff，确认行为符合预期后再进入下一步。
第五步：验证与上线
实现完成后，通过本地运行和测试用例验证功能。重点检查粘贴多行时的 Enter 键行为、非 ASCII 字符处理，以及是否影响原有提交逻辑。
确认无误后，提交代码并发起 PR。Codex 的工作流到此基本完成，整个过程从需求判断到上线通常只需按步骤推进即可。
掌握这套流程后，新人就能在 Codex 项目中快速定位任务、减少返工，实现从需求到上线的稳定交付。