Codex 长任务和大项目：计划文件、Goals、会话管理、并行、云端与额度

2026年10月30日 更新：2026年10月30日 · 作者 Taylor Yang · #工作流程 #项目管理 #智能体开发

大任务一做就乱、对话越长越糊涂？用计划文件和 Goals 管长任务，用会话指令管上下文，再按需并行、上云、控制额度。

💡 **这篇解决什么问题：**任务一大、对话一长，Codex 就容易忘掉前面的约束，你得一遍遍说“继续”；几个任务一起跑又互相覆盖；额度也烧得快。这篇讲长任务怎么拆、怎么用计划文件和 Goals 让它持续推进到有证据的完成、会话怎么管、什么时候并行和交给云端，以及模型和额度怎么选。

更多 Codex 文章：省点力 · Codex 小类

大家卡在哪里

Part A：把大任务拆开

分阶段执行，每一段都要证据

用 plans.md 管大型任务

用 plans.md 提供一份规划模板，在 AGENTS.md 里指向它，告诉 Codex 面对步骤多的项目该怎样一步步制定计划。

把复杂任务拆成专门文档，再让 Codex 按计划逐步更新，通常比一条很长的提示词更稳。

给仓库搭一套可以持续维护的 harness

以一个待办清单应用为例，可以把目标、计划、执行提示词和验收记录分别存进仓库，让开发过程有据可查。AGENTS.md 是 Codex 认识的可选文件，下面其他文件属于项目自己的工作约定，按实际规模取舍。这套结构也可对照 OpenAI Cookbook 的工作流示例 调整。

完成后的目录结构（context/ 里的文件在每个开发阶段生成，记录该阶段的上下文）：

.
├── .gitignore
├── AGENTS.md
├── GOALS.md
├── PLANS.md
├── PROMPTS.md
├── README.md
└── harness
    ├── build
    │   ├── phase-00-repository-foundation.md
    │   ├── phase-01-create-list.md
    │   ├── phase-02-update-complete-delete.md
    │   └── phase-03-demo-verification.md
    ├── build-log.md
    ├── code_review
    │   └── .gitkeep
    └── context
        └── README.md

各文件管什么：

文件负责的内容
AGENTS.md长期有效的仓库说明和工作约定
PLANS.md计划的目的、项目路线图、阶段顺序（真相源）
GOALS.md期望结果、成功条件、范围、非目标
PROMPTS.md启动和推进工作的可复用提示词
harness/build/阶段.md某一阶段已批准的范围和计划
harness/context/阶段.md某一阶段的关键发现、决定、约束和未决问题
harness/build-log.md实际进度和观察到的验证证据
harness/code_review/需要时存放详细的审查结论

**第 1 步：写 AGENTS.md。**新项目最好从这里开始，Codex 干活前会把它当作长期的仓库指导。一般包括：仓库目标和整体摘要、编码规范、测试标准、相关的 context 文件、项目特有的行为、范围和边界。可以用 /init 生成初稿，它会根据目录内容尝试填写。这里也很适合存团队的经验知识。

**第 2 步：写 PLANS.md。**作为计划执行的真相源，除了计划目的，还要有项目路线图，之后可以据此生成每个阶段的文件。喜欢长时间任务的团队，可以把 PLANS.md 写得更大，包含重大决定和验收标准的细节；拆成小的阶段文件，可读性更好，也方便人工把关代码质量和其他产出。

**第 3 步：生成 GOALS.md 和 PROMPTS.md。**可以手写，也可以让 Codex 根据 AGENTS.md 和 PLANS.md 生成。

生成 GOALS.md / PROMPTS.md 的提示词要点

- 先读仓库根目录起所有适用的 `AGENTS.md`，有 `PLANS.md` 也一起读；只创建或保守更新 `GOALS.md` 和 `PROMPTS.md` 两个文件。
- 动笔前先简要说明：找到了哪些来源文件；推断出的项目结果和约束；因信息缺失或模糊而做的假设。
- `GOALS.md` 写项目要达成什么：项目目的、期望结果、成功条件、范围、非目标、技术和运维约束、来源支持时写安全/可靠性/恢复的预期、仍需人来决定的未知事项。以结果为导向，不要抄实现步骤、可复用提示词或进度更新；不要声称来源里没有的能力、期限、保证或要求。
- `PROMPTS.md` 提供启动和推进工作的可复用提示词：仓库导览、规划或阶段准备、执行一个已批准阶段、验证和收集证据、审查或修复、阶段完成和交接。
- 每条提示词都要：告诉 Codex 读哪些文件；引用相关目标或计划而不是复制；写清当前范围和明确的非目标；实现前先做只读预检；写入仓库前先给出待批准的摘要；适当时采用红-绿-重构-验证；要求真实观察到的测试和验证证据；提交、推送、部署、凭证和外部写入都要单独明确批准；完成所选阶段后停下，不自动开始下一阶段。
- 没有 `PLANS.md` 时：只根据 `AGENTS.md` 推出高层目标；不要编造路线图、阶段、架构或产品需求；需要规划输入的地方用明确标注的占位符；让提示词在实现前先要求明确的计划或阶段。
- 保留仓库已有的术语和文件名大小写，两份文件都写简洁，不重复 `AGENTS.md`、`PLANS.md` 已有的信息。不要改应用代码、测试、依赖、配置、现有规划文件或其他任何文件。
- 写完后：检查两份文件有没有矛盾、职责重复；确认每条实质内容都能在 `AGENTS.md` 或 `PLANS.md` 找到依据，否则标为假设；运行 `git diff --check`；报告改了哪些文件、做了哪些假设、还有哪些未决问题。

**第 4 步：把每个阶段拆成单独的 build 文件。**每个文件写清：这一步的目的、需要额外参考的文件、验收标准、边界。建议手动建一个 harness/build/ 文件夹，文件名用 <阶段编号>-<阶段标题>.md 格式。每个阶段开始时，把对应文件和 harness 里的提示词、目标一起交给 Codex，能防止 agent 跑偏（drift），再配合版本控制，就形成一份清楚、由人把关的开发历史，以后排查问题时是很好读的审计轨迹。

生成阶段文件的提示词要点

- 先做一次只读的仓库探查：读 `AGENTS.md`，以及存在时的 `PLANS.md`、`GOALS.md`、`PROMPTS.md`、`harness/build-log.md`、`harness/build/` 下已有文件、相关的应用清单、测试和验证命令。以当前仓库为准，不套用其他项目的假设。
- 写之前先列出：找到的来源文件；仓库的目的和现状；计划的阶段及依赖关系；准备创建的具体文件；缺失、模糊或矛盾的需求；这次规划任务本身的验收标准。来源文件定不出清楚的阶段顺序时，停下来提一个阶段划分方案给人审，没有批准不要自己编路线图写进去。创建前先展示范围和具体路径，等明确确认。
- 每个 build 文件描述一个有边界的实现阶段，它是计划，**不代表工作已经完成**。沿用仓库已有的阶段编号、名称、顺序、术语和模板。
- 每个阶段文件包含：阶段编号和标题；状态（初始为 `Not started`）；来源输入；目标；范围内的工作；明确的非目标；依赖和前置条件；预计影响的文件或组件；需要人来决定的事项；审批闸门；红-绿-重构-验证计划；聚焦的和更大范围的验证命令；与本阶段相关时的安全、隐私、可靠性、可观测性和恢复考虑；验收标准；阶段完成前必须记录的证据；交接或停止条件。
- 10 条规划要求：① 范围小到能独立实现和验证；② 保持依赖顺序，不把后面的工作挪到前面；③ 验收标准要可观察，不写主观的“完成”；④ 红阶段写最小的、有意义的失败测试或检查；⑤ 绿阶段写最少的实现；⑥ 只有保持已批准行为和范围时才允许重构；⑦ 能从仓库确定的，写出真实的验证命令；⑧ 不知道的命令或需求标为未决，不要编；⑨ 标出需要单独授权的凭证、外部系统、基础设施变更、部署、提交和推送；⑩ 除非在单独批准的实现阶段真的跑过，否则不要声称测试、恢复流程或集成已经通过。
- 范围限制：只创建或更新 `harness/build/` 下已批准的文件；不碰应用代码、测试、依赖、包清单、基础设施和部署配置、`AGENTS.md`、`PLANS.md`、`GOALS.md`、`PROMPTS.md`、context 文件、执行或构建日志、代码审查产物、README、Git 分支/提交/远程状态；不开始实现任何阶段；已存在的 build 文件先检查并说明打算怎么改，保留有用内容，不覆盖已记录的决定和证据。
- 写完后：确认只改了已批准的 `harness/build/` 文件；每个阶段都能追溯到仓库的来源文档；检查范围有无重复、遗漏或顺序错误；每个阶段都有审批闸门、验收标准和验证计划；运行 `git diff --check`；报告创建或更新的文件、阶段顺序、做过的验证、假设和未决问题、开始第一阶段前需要的批准。

**第 5 步：记录每个阶段的关键上下文。**把每个阶段里对项目有实质影响的决定记下来，存成 harness/context/phase-<NN>-<phase-slug>-context.md。在 AGENTS.md 里加一段说明，Codex 就会自动维护。

阶段 context 文件的规则要点

- 每个已批准的实现阶段只维护一份 context 文件；阶段开始并获得所需批准后才创建；记录前先读适用的仓库说明、目标、提示词、build 文件、之前的 context 和 build-log 证据。
- **重要性测试**：只有“不记下来可能会”改变已批准的范围或实现方式、让后续阶段重复探查或做出不同决定、影响接口/依赖/不变量/归属边界、改变验收标准或所需验证、影响安全/隐私/可靠性/可观测性/回滚/恢复、掩盖阻塞/未决假设/已接受的限制/必要的后续工作时，才记录。不影响后续工作、验证、运维或决策的，不写。
- **要记录**：用户的决定和澄清；范围变化和明确的非目标；影响实现的假设；架构或实现决定及理由；相关组件、接口、依赖和归属边界；必须保留的现有行为或不变量；安全、隐私、运维和恢复约束；验证的局限或拿不到的证据；阻塞和未决问题；后续阶段必须知道的发现；被取代的决定（换成了什么、为什么）。每条都附上足够的出处，能找回当时的推理：相关文件、命令、测试结果、issue、审查结论或用户决定。
- **不要记录**：context 文件不是对话记录、草稿本或进度日志。排除日常命令输出、逐步叙述、没有长期影响的临时死路、已经归其他正式文件管的事实、计划/提示词/测试输出/源码的完整副本、日常进度或完成状态、当成事实写的猜测、凭证/token/密钥/敏感值。链接到正式来源，不要复制内容。
- **真相源边界**：阶段 build 文件管已批准的范围、非目标、验收标准和计划的验证；阶段 context 文件管后续工作需要的关键发现、决定、约束和未决事项；`harness/build-log.md` 管实现进度和观察到的验证证据；代码审查产物管审查结论和签核状态。除非解释某个重要决定需要一段简短摘要，否则不在这些文件之间互相复制。
- **更新和交接**：出现重要决定或发现时就更新，阶段结束前复查。交接前：删掉非关键的叙述和重复信息；确认重要决定都有理由和出处；明确标出假设和未决问题；证据用链接，不空口声称；写下对后续阶段的影响；不要因为 context 文件写完了就把阶段标为完成。

第 6 步：用 build-log.md 记录真实进度。harness/build-log.md 是项目进度的真相源，人能读懂，但主要给 Codex 用，也可以拿来生成面向用户的更新日志和文档。在 AGENTS.md 里加一段说明，让它每个阶段结束、提交之前都更新一次。日志必须写实际发生了什么，不能写计划预计会发生什么。

build-log 的规则要点

- **写之前先汇总**：选中的阶段、当前记录的状态、检查过的来源和证据、准备追加的条目或状态变化、任何冲突/缺失/未验证的信息。仓库要求文档写入需批准时，等明确确认再写。
- **初始化**：日志不存在时，创建一段简短的目的说明、一张阶段汇总表、一个只追加的活动记录区。汇总表根据 `harness/build/` 下已批准的文件生成，除非仓库证据支持其他状态，一律初始化为 `Not started`。
- **状态只用四种**（仓库另有定义除外）：`Not started`、`In progress`、`Blocked`、`Complete`。不能因为代码存在、某个聚焦测试通过、或之前的对话就推断完成。
- **汇总表字段**：阶段、状态、分支、开始时间、完成时间、证据、阻塞。表只是当前摘要，详细历史放在追加的活动记录里。
- **只有同时满足这些才能标** **`Complete`**：已批准的验收标准都满足；要求的测试和验证真的跑过且通过；要求的审查结论已解决或明确接受；适用时运维、安全、恢复和清理要求都满足；剩余限制已记录；仓库特有的完成要求都满足。任何一项缺证据，就保持 `In progress` 或 `Blocked`。
- **什么时候追加条目**：阶段获得授权；开始工作；红阶段的测试或检查按预期失败；实现后聚焦检查通过；做了重要重构或明确决定不重构；更大范围的验证；重要的范围变化；出现阻塞；审查结论或修复；接受或拒绝某个限制；阶段完成。
- **条目结构**：标题是“时间戳 — Phase 编号：事件”，下面依次写状态变化（旧 → 新）、观察到的分支、授权范围（摘要或链接）、改动（重要的文件、组件或行为）、红（具体检查和观察到的预期失败，或“不适用”及理由）、绿（具体聚焦检查和结果）、重构（重要重构和重复的检查，或不需要重构的理由）、验证（真正跑过的命令或流程及结果）、审查（结论、修复、签核状态）、运维证据（安全、可观测性、回滚、恢复或清理相关证据）、限制（未测试的部分、接受的风险、不完整的证据）、阻塞（当前阻塞或“无”）、下一步（下一个已批准的动作，不隐含授权）、证据引用（context 文件、审查产物、日志、提交等路径）。时间戳要带时区，不能有歧义。
- **证据要求**：记录具体命令和简洁的通过/失败结果；区分亲眼观察的证据和转述的、历史的证据；没真正运行并观察到结果，绝不声称测试、集成、恢复流程或外部检查通过；不能把 build 文件里计划的命令当成通过的证据；跳过的和无法执行的检查要明确写出原因；大段输出用链接，不复制进日志；不写凭证、token、密钥、敏感值或不必要的个人信息；不复制完整的 context 文件、计划、diff 或命令输出；证据互相冲突时两边都保留，阶段标为 `Blocked`，直到冲突解决。
- **历史和更正**：条目只追加。不要悄悄改写之前的证据或删掉失败的尝试。之前的条目写错了，就追加一条更正，指出更正的是哪条、改了什么，再更新汇总表。不改变意思的错别字可以原地改。
- **范围限制**：写日志时不改应用代码、测试或配置，不创建阶段 context，不改 build 文件或执行计划，不切 Git 分支，不提交不推送，不开始下一阶段，证据不足不标完成。证据显示别的文件需要更新，就作为后续事项报告，不顺手改。
- **写完后检查**：确认只改了 `harness/build-log.md`，并保留了工作区里已有的实现、测试等改动；每次状态变化都有证据；计划中的工作没有被写成已完成；失败、跳过的检查和限制都还看得见；运行 `git diff --check`；报告记录的阶段和状态、追加的条目、用到的证据、剩余阻塞或限制、下一步需要的单独批准。

**第 7 步：把这套流程做成 skill。**每条提示词都这么长、文件这么多，纯手工操作很快会变得笨重、容易出错、结果不稳定。Cookbook 的做法是用 $skill-creator 创建一个可复用的 $harness-author skill，用来创建、审查和改进一套大小合适的仓库工程 harness，用户没有明确要求并单独批准时，不开始实现。

创建 harness-author skill 的要点

- **安装位置**：默认 `${CODEX_HOME:-$HOME/.codex}/skills/harness-author`。位置不明确或已有同名 skill 时，报告具体路径，问是更新还是换名字；没有明确批准不覆盖。
- **只读探查**：读适用的 `AGENTS.md`；查看当前仓库已有的 harness 示例和约定；有的话读 `PLANS.md`、`GOALS.md`、`PROMPTS.md`；只看不改 `harness/` 下的文件；找出哪些请求应该触发、哪些不应该；判断哪些行为放 `SKILL.md`、参考文件、脚本和测试；完整读 `$skill-creator` 的说明和必需参考。不要以为某个仓库的 harness 结构是所有项目的标配。
- **写之前展示**：拟定的 skill 路径、触发描述、要创建的文件和资源、行为范围、明确的非目标、验证器和测试计划、验收标准，等确认再写。
- **触发场景**：创建或审查仓库工程 harness；创建长期的仓库说明；把目标或计划转成分阶段的 build 文件；定义验收标准和审批闸门；创建或精简执行日志和构建日志；建立测试驱动的阶段计划；把规划、实现、上下文和证据分开；观察到工作流失败后改进现有 harness。描述里还要写明：“harness-only”“planning-only”“just the build files”“only these files”这类说法，**不能授权实现应用代码**。
- **核心行为 14 条**：设计前先读仓库说明、查看当前仓库；找出目标、计划、实现约定、阶段状态、上下文、审查结论和验证证据各自的权威来源；判断仓库形态和变更风险；推荐够用的最小 harness；保留现有架构、命名、归属和运维保护措施；写之前冻结用户批准的具体产物清单；改仓库前先展示范围、受影响文件、测试、验收标准、风险和审批闸门；规划和实现分别授权；实现计划里适当时使用红-绿-重构-验证检查点；定义可观察的验收标准和证据要求；未知事项标为未决，不编需求或证据；同一事实不在多个 harness 文件里重复；保留现有应用文件；凭证、外部系统、基础设施、切分支、提交、推送和部署都要单独批准。
- **产物归属**：分清 `AGENTS.md`、`PLANS.md`、`GOALS.md`、`PROMPTS.md`、`harness/build/`、`harness/context/`、`harness/build-log.md`、`harness/code_review/` 各管什么（见上表）。它们都是可选约定，skill 要在仓库已有约定上扩展，不要默认把所有产物都建一遍。
- **只做规划时的边界**：只建明确批准的文件；不建应用代码、应用测试；不加依赖或清单；不建 Docker、基础设施或部署文件；除非明确批准，不建 README 或审查产物；对应阶段开始前不建阶段 context 文件（用户明确要求除外）；不改 Git 状态、不提交、不推送、不访问外部系统；未来的实现和测试只在计划里描述；验证并报告 harness 产物后停下。
- **按项目大小调整**：极小的项目，优先用已有文档、测试和一份简洁的验收清单；应用项目，只在有用时才加分阶段规划和恢复指导；多服务项目，写清归属、接口约定、依赖边界、降级行为和集成验证；monorepo，根目录说明加上适用的包级说明；高风险变更，不管仓库多大，都要覆盖安全、授权、回滚、恢复、失败模式和独立验证。仓库和风险用不着时，不要强加企业流程、强制审查人或额外文档。
- **skill 结构**：用 `$skill-creator` 的初始化脚本建骨架，只建真正有用的资源。大致是 `SKILL.md`、`agents/openai.yaml`、`references/` 下四份参考（项目类型与模板、真相源与模板、TDD 与验证、可靠性与取舍）、`scripts/` 下的 `validate_harness.py` 和 `test_validate_harness.py`。不建 README、更新日志、安装指南等辅助文档。`SKILL.md` 写得简洁、偏操作步骤，详细的模板、矩阵、示例放进直接链接的参考文件，两边不重复。`agents/openai.yaml` 用 `$skill-creator` 工具生成，先读它的参考说明，生成 `display_name`、`short_description`、`default_prompt`，用户没提供就不加品牌类可选字段。
- **确定性验证器**：只用标准库，能检查仓库、验证拟定的 harness，不改文件、不打印源码。支持仓库路径和可选目标路径、项目形态和风险评估、harness-only 意图、可重复的拟定路径参数和允许路径参数、JSON 输出、遇到阻塞问题即失败的严格模式。要拒绝：绝对路径；路径穿越；harness-only 请求里夹带应用脚手架；批准产物集合之外的文件；没明确批准的 context、审查或实现产物；需要时缺少审批、验收或验证段落；没有证据却声称验证已完成。对不用这套结构的仓库只给建议；不联网、不读凭证、不改 Git 状态、不改仓库文件。
- **至少 12 个测试**：合法的最小 harness-only 请求；明确批准的自定义 Markdown 产物；拒绝规划请求里的应用代码；拒绝依赖、清单、Docker 和基础设施文件；拒绝未批准的 context 和审查产物；相对路径的安全规范化；拒绝绝对路径和穿越；保留文件名大小写；小仓库不应拿到过大的 harness；高风险项目必须覆盖安全和恢复；JSON 输出和严格模式；已有仓库的约定要保留。脚本和测试直接运行，报告观察到的结果。
- **实现后验证**：跑验证器的测试；跑 `$skill-creator` 的 `quick_validate.py`；确认 YAML 头部只有 `name` 和 `description`；skill 名是小写连字符形式；`agents/openai.yaml` 和 `SKILL.md` 一致；检查最终文件列表里有没有多余文件；检查 diff 里有没有改到目标位置以外。需要前向测试时，先提出真实的测试提示，经批准再启动子智能体或修改外部仓库。
- **验收标准**：能被仓库 harness 编写和审查类请求触发；按仓库和风险调整 harness 大小；保留本地约定和真相源；harness-only 请求不会悄悄生成实现产物；阶段 context 只在会话中创建（除非单独批准）；计划里有像样的验收和验证要求；验证器和测试通过；通过 `quick_validate.py`；没改批准位置以外的文件；所有限制和未测试行为都已报告。最后报告 skill 位置、建了或改了哪些文件、触发描述、验证器行为、测试和验证结果、没做的前向测试、剩余假设或限制。

**什么样的事值得做成 skill？**几乎什么都能做成 skill，但好 skill 通常是高频使用的。Cookbook 举了三个日常例子：

**skill 刚建好不一定听话，要调。**比如让 $harness-author 创建 harness context 和阶段文件时，它提议的清单漏了 PLANS.md 和 harness/build-log.md，还多了 context 文件。这时在批准任何改动前先纠正范围：

Revise the proposed harness-only scope before writing.
Include these missing artifacts:
- PLANS.md: the ordered phase execution plan.
- harness/build-log.md: observed implementation progress and verification evidence.
Do not create a phase-specific context file until that phase begins and has
received the required approval. Include harness/context/README.md only if it
is explicitly approved as an exception to the standard harness-only allowlist.
Check the proposed artifact list for both missing required files and
unapproved additional files. Present the revised exact file list, explain
the ownership of each artifact, and wait for approval before writing.

纠正后，它就会提议正确的文件：PLANS.md、harness/build-log.md 和各阶段 build 文件。

**第 8 步：做完一轮，复盘。**按 AGENTS.md 里的标准完成项目、提交进版本控制之后，用 Codex 回头看这一轮学到了什么，为下一轮改进。这套结构只是起点。

复盘（postmortem）提示词要点

- **目标**：弄清什么有效、什么造成了摩擦；改进现有的 harness-author skill；找出缺少的可复用 skill，但不要造成 skill 泛滥；改进仓库说明、harness 产物、验证器和流程；把已验证的工作流失败转成回归测试或可执行的保护措施。初次复盘阶段不修改任何仓库、harness 或 skill 文件。
- **只读探查**：全局和仓库的 `AGENTS.md`；存在时的 `PLANS.md`、`GOALS.md`、`PROMPTS.md`；`harness/build-log.md`；适用的 `harness/build/`、`harness/context/` 文件；代码审查和复盘产物；相关实现 diff；测试和验证结果；当前 Git 分支和工作区状态；用户的更正、审批决定和接受的限制；已安装的 harness-author skill；流程中调用的其他 skill 及其脚本、参考、元数据和测试；可能已经能承担某项流程的现有 skill。以当前文件和观察到的证据为准，计划、预期行为、之前的对话、未验证的报告都不能当成发生过的证明。未经单独授权，不访问凭证、生产系统、外部服务或远程 Git 状态。
- **重建预期流程**：阶段顺序；每个 harness 产物归谁管；预期的审批闸门；计划的红-绿-重构-验证检查点；预期的审查和交接流程；哪些 skill 应该被触发、各自负责什么；围绕上下文、证据、提交、推送、部署、凭证和外部写入的预期边界。区分仓库必需的行为和可选的工作流约定。
- **重建实际发生的事**：完成的工作；真正跑过的命令和检查；遵守、遗漏或模糊的审批闸门；范围变化；重复探查或重复劳动；错误假设；agent 跑偏或过度建设；上下文缺失或过多；误导性的状态或没有依据的完成声明；人工干预；审查结论和修复；失败、跳过或无法执行的验证；恢复或回滚问题；用户更正；因为 harness 或 skill 而成功的工作；尽管流程有缺口仍然成功的工作。证据只支持症状或相关性时，不要硬造根因。
- **逐个分析重要事件**，每条记录：事件、预期行为、观察到的证据、影响（对范围、质量、安全、时间或信心）、促成条件、当时的保护措施、保护措施的结果（有效、失效、缺失、模糊或被绕过）、可推广性（一次性、仓库特有或可复用）、建议归属、拟定的验证方式。采用不追责的视角，关注流程设计、信息缺失、归属不清和验证不足，不追究个人。
- **重要性测试**：只纳入实际影响或可能影响已批准范围、实现正确性、验证信心、安全或隐私、可靠性/可观测性/回滚/恢复、人工审批或审查、后续阶段决策、重复劳动、复现或审计能力的事件。无害的错别字、日常命令失败、没有长期影响的临时探索不写。
- **改进归属**（每条建议只归一个主要位置）：仓库说明 `AGENTS.md`（长期的仓库约定、约束、命令或审批规则）；项目 harness（只适用于本项目或本阶段）；现有 skill 的说明（可复用流程、触发条件、安全边界或决策规则）；现有 skill 的参考文件（详细指导、示例、矩阵或变体）；现有 skill 的脚本或验证器（能机械检查、漏了代价高或容易反复出错）；回归测试（失败可复现、预期行为能可靠断言）；新 skill；不改流程（不重要、已妥善处理，或太特殊不值得增加复杂度）。
- **只有全部满足这 7 条才建新 skill**：有独特的用户意图和触发词；是可复用的多步骤流程；会在多个仓库或阶段反复出现；有清楚的归属和有边界的职责；现有 skill 无法干净地承担；建了能降低复杂度，而不是把重复挪个地方；成功与否能独立验证。单条规则、某个仓库的约定、一次性事件、已有 skill 负责的功能，都不建新 skill。
- **评估现有 skill 质量**：描述有没有被正确的请求触发？该触发时有没有漏？触发范围是不是太宽？`SKILL.md` 是否只有必要的操作指导？详细说明是否放进了正确的参考文件？适用的参考文件是否真的被加载？脚本是否保护了脆弱或安全关键的行为？脚本失败是否被安全处理？审批边界是否明确？是否保留了仓库特有约定？是否创建了仓库不需要的文件或流程？是否把计划和观察到的证据混为一谈？是否过度贴合之前的项目？UI 元数据和行为是否一致？是否需要新的回归测试？归属已经清楚时，优先收紧现有 skill，不另建新的。
- **评估整个流程**：仓库导览、真相源归属、harness 生成、阶段选择、上下文记录、审批材料、红-绿-重构-验证、证据记录、独立审查、修复、阶段完成、提交和推送审批、合并后的分支准备、跨阶段交接、复盘时机。每个流程改动都要说明：解决什么问题、归谁、是建议性的还是机械强制的、成本或增加的流程负担、最小的有用改动、怎么验证它确实改进了流程。不要为了让 harness 看起来全面而加流程。
- **输出一份只读复盘**：执行摘要（流程效果的简要评估和最重要的改进机会）；有效的做法（值得保留的、有证据支持的做法和保护措施）；造成摩擦的问题（重要问题、影响和证据）；现有 skill 的改进（skill 名称和路径、影响的触发/说明/参考/脚本/元数据/测试、支持证据、拟定行为、过度拟合风险、需要的验证）；新 skill 候选（小写连字符名称、独特的触发请求、职责和非目标、为什么现有 skill 不能承担、可能的文件或资源、具体示例请求、验证和前向测试计划、优先级：现在/以后/否决；被否决的候选也要列出，并说明由哪个现有归属吸收）；harness 和仓库改进；按优先级排列的改进清单：**P0** 不安全或实质错误的工作流行为，**P1** 反复失败、审批缺口或误导性证据，**P2** 有意义的效率或清晰度改进，**P3** 可选的打磨，每项写工作量、预期价值、归属和验证；未决问题（证据缺口或需要人来决定的事）。
- **审批闸门**：交出复盘后停下。不改现有 skill、不建新 skill、不改仓库说明、不改 harness 文件、不加脚本或测试、不启动前向测试、不提交不推送。以下各自单独申请批准：仓库或 harness 改动；每个现有 skill 的改动；每个新 skill 的创建；前向测试；提交或推送。
- **实施批准的改进**：只有明确批准后，才用 `$skill-creator` 改 skill。每个批准的 skill 改动：确认具体路径和受影响文件；行为能机械测试时先加一个失败的回归测试；做能解决有证据问题的最小改动；`SKILL.md` 保持简洁，细节移到直接链接的参考文件；只在确有必要强制执行时才改脚本；跑相关脚本测试；跑 `quick_validate.py`；只有接口元数据过时时才重新生成 `agents/openai.yaml`；检查最终 diff 有无无关改动；报告观察到的结果和剩余限制。每个批准的新 skill：确认独特的触发和归属边界；确认安装位置；用 `$skill-creator` 的 `init_skill.py` 初始化；只建必要资源；添加并运行相关测试；跑 `quick_validate.py`；确认不与现有 skill 重复或冲突。
- **前向测试**（批准后）：用全新的、独立的上下文；给真实的请求和原始材料；不透露预期答案或怀疑的缺陷；正反两种触发情况都测；检查范围扩张和不安全的写入；每次运行之间清除或隔离生成的测试产物；用明确的验收标准对比观察到的行为；把已验证的失败反馈进说明、验证器或回归测试。不能只因为 skill 通过了结构验证就宣布工作流改进了，要有真实使用的证据。
- **完成标准**：重要事件都有证据支持；改进都有明确归属；优先用现有 skill，避免不必要的新 skill；批准的改动在可行时有回归覆盖；skill 和脚本验证通过；做了前向测试就记录结果；仓库特有的经验留在仓库里；可复用的经验写进合适的 skill；剩余限制和被否决的建议都有记录；没有改动未批准的文件、外部系统，没有未批准的提交或推送。

Cookbook 的结论：项目和阶段的结果没法预测，所以它没有给“改进后的目录结构”。起步时只记录会实质影响决策、验证和后续工作的上下文；熟悉流程后，可以安排更长的任务，借助前几轮开发的积累，在批准的边界内产出更一致、更可靠的结果。

Part B：用 Goals 让它一直做到有证据的完成

Goal 是什么

Goal 是 Codex 里的持久目标，让一个对话线程跨多轮持续朝着明确的结果推进。它给 Codex 一个完成条件：什么应该成立、怎么检查成功、哪些约束必须保持不变。

前提条件：Codex 版本支持 Goals（从 0.128.0 开始）；任务有清楚的终点和可检查的证据来源，比如测试、基准测试或最终产物；仓库或研究上下文足够，让 Codex 能真正验证进度，而不是只是讲述进度。

开始使用

先更新并确认版本：

# npm
npm install -g @openai/codex@latest
codex --version

# Homebrew
brew update
brew upgrade --cask codex
codex --version

然后用 /goal 加上想要的结果：

/goal Reduce p95 latency below 120 ms without regressing correctness tests

管理生命周期：

/goal          查看当前 Goal
/goal pause    暂停进行中的 Goal
/goal resume   恢复已暂停的 Goal
/goal clear    删除当前 Goal

Goal 激活后，Codex 可以查看代码、运行相关命令、修改、测试，然后继续，直到遇到停止条件：成功、暂停、清除、被打断、预算上限，或者遇到需要你输入的阻塞。

如果你每轮都在说这些话，就该用 Goal 了：

Keep going.
Try the next likely fix.
Run the benchmark again.
Now check the tests.
Continue until this is actually done.

Goal 和普通提示词的区别

Prompt:  ask -> work -> result -> wait
Goal:    work -> check -> continue or complete

例如：

/goal Reduce p95 checkout latency below 120 ms on the checkout benchmark while keeping the correctness suite green

这条不只是要求“性能更好”，它给了一个可衡量的结果、一个验证面和一个约束。Codex 可以跑基准、看热点路径、做针对性修改、重跑基准、跑正确性测试，结果还不够好就继续。Goal 给了终点，但工作仍然要用证据审计。

怎么写一个好 Goal

好 Goal 是一份紧凑的契约，最好写清 6 件事：

  1. 结果：做完时什么应该成立；
  2. 验证面：用什么证明，比如测试、基准、报告、产物、命令输出或原始资料；
  3. 约束：工作过程中什么不能退化；
  4. 边界：可以用哪些文件、工具、数据、仓库或资源；
  5. 迭代策略：每次尝试后怎么决定下一步试什么；
  6. 阻塞时的停止条件：在当前限制下没有可行路径时，什么时候停下并报告。

通用模板：

/goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed inputs, tools, or boundaries>. Between iterations, <how Codex should choose the next best action>. If blocked or no valid paths remain, <what Codex should report and what would unlock progress>.

从弱到强：

# 能用，但比较单薄
/goal Reduce p95 checkout latency below 120 ms without regressing correctness tests

# 更强：一份完整的操作契约
/goal Reduce p95 checkout latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green. Use only the checkout service, benchmark fixtures, and related tests. Between iterations, record what changed, what the benchmark showed, and the next best experiment to try. If the benchmark cannot run or no valid paths remain, stop with the attempted paths, the evidence gathered, the blocker, and the next input needed.

强版本也告诉了 Codex 什么时候不能停：p95 从 180 ms 降到 135 ms，没完成；延迟低于 120 ms 但正确性测试失败，没完成；基准跑不起来，必须报告这个阻塞，不能宣布成功。

研究类任务同理，开工前先定义证据标准，尤其是可能拿不到精确证明时：

/goal Produce the strongest evidence-backed reproduction of the paper using the available materials and local resources. Attempt the headline results where feasible, verify outputs where possible, and end with a report that separates confirmed findings, approximate reconstructions, blocked claims, and remaining uncertainty.

这类 Goal 给了 Codex 调查的空间，又让最终结果保持诚实，它定义了“完成”“阻塞”“仍不确定”分别是什么意思。

**不会写？让 Codex 帮你写。**两步：先用大白话描述工作，让 Codex 起草一个 Goal；再审阅草稿，收紧成功条件、验证面、约束和阻塞停止条件，然后再激活。

Help me turn this into a strong `/goal`: I want Codex to keep working on this flaky checkout test until we either fix it with evidence or can clearly explain what is blocking progress.

Codex 会提出一个更完整的 Goal，只在确实缺少关键信息时才追问。

范围要“窄到能审计，宽到能探索”

/goal Produce a docs page for Goals that explains the lifecycle, command surface, and two examples. Verify that the page builds locally and that all referenced commands match the current CLI behavior.

第二个给了 Codex 可以检查的东西：一个页面、一条构建命令、命令的实际行为。

Goal 激活后会发生什么

  1. 目标一直在。测试失败了，原目标还在；基准有改善但没达标，可以继续；研究路径缺数据，可以调整证据计划，不丢研究标准。
  2. 空闲时可以自动继续。有其他轮次在进行、有用户输入在排队、有其他线程工作未完成时，它不会继续；只有线程空闲、Goal 处于激活状态且预算未用完时才继续。
  3. 完成必须靠证据。不能因为模型觉得“差不多做完了”就标记完成，要对照相关文件、测试、日志、基准输出、生成的产物等具体证据检查后才算完成。

Codex 里的 Goal 是怎么设计的

设计重点：让目标一直存在，直到证据表明工作已完成，而不是让 Codex 无限循环。

一个研究案例：复现 Deep Hedging 论文

案例是 Buehler、Gonon、Teichmann 和 Wood 的论文 Deep Hedging：神经网络交易策略能否在不同风险偏好、交易成本和更高维市场设定下复现基于模型的对冲。正确的 Goal 不是抽象地“复现论文”，而是尝试论文的主要数值结论，把精确机制和近似训练替代品分开，并明确说明哪些无法用现有材料精确重放。

# 弱：没说哪部分重要、什么算复现、拿不到训练状态怎么办、怎么区分接近的数值匹配和精确重放
/goal Reproduce Buehler et al., "Deep Hedging"

# 更好：写明证据标准和最终产物
/goal Produce the strongest evidence-backed reproduction of Buehler et al., "Deep Hedging," using the available paper materials and local resources. Attempt every headline result, verify the outputs, and end with a report that separates reproduced mechanics, approximate trained results, blocked exact replay, and remaining uncertainty.

Codex 的做法：把主要论点和支持性论点分开；把论点对应到可用证据；重建能在本地测试的部分；标出无法精确复现的论点。

最终报告要保留不同程度的支持，不要压成一句“成功”。一条台账可以这样写：

Claim: Deep hedging approximates complete-market Heston hedge without transaction costs.
Route: Rebuilt model mechanics, reference hedge comparison, and trained neural policy.
Evidence surface: Price checks, histograms, and hedge surfaces.
Status: Close approximate reproduction.
Remaining uncertainty: Original training paths, seeds, and checkpoints are unavailable.

训练出的替代品可以支持一个论点，接近的数值匹配可以提高信心，重建的图可以验证部分结果，但都不应被描述成精确还原了原始实验。Goal 让 Codex 在模糊中继续推进，同时防止一个看似合理的产物变成夸大的结论。

什么时候不用 Goal

Goal 最适合同时具备三个特点的任务：持久的目标、以证据为准的终点、可能需要多轮调查的路径。用户给目标，Codex 跟着证据走，Goal 把两者连在一起，直到工作完成或诚实地报告阻塞。

新模型停得太早怎么办

OpenAI 2026 年 9 月的文章提到：习惯了 GPT-5.6 Sol 接到请求就连续干很久的人，会觉得 GPT-6 Astra 在“什么时候停”上更谨慎，它可能做出第一版实现就回来等你审，其实还有活没干完。

Part C：管好会话，别让上下文混乱

一个会话只干一件事

上下文管理会直接影响结果。一个会话里已经有项目背景、相关文件、做过的修改和当前任务。可以把一个会话当成一个小项目容器：写测试专门开一个会话，做某个前端功能另开一个会话。职责清楚，Codex 也不容易把不同任务的信息混在一起。

接着昨天的继续

对话太长：/compact

聊久了对话越来越长，每次回答都带着前面的历史一起思考，越聊越慢、越聊越贵。这时用 /compact，它会把前面的对话压缩成摘要，然后继续当前任务。

/compact 保留登录模块的结论、已修改文件、剩余 bug 和测试失败信息。

换话题：/new 和 /clear

/new 是开新对话；/clear 是清空终端显示并开始新对话。新手不用纠结：任务没结束用 /compact，任务结束要换新话题用 /new 或 /clear。

临时问一句 vs 另开一条路线：/side 和 /fork

记一句：/side 是临时问一句，****/fork 是开一条新路线。

/side 这个方案有没有明显风险？

问完回到主线继续。适合临时问一个判断、检查方案风险、问一句概念解释、不想污染主线。不适合复杂的多轮讨论、认真尝试另一套实现、长期保存实验路线。

Part D：多任务并行

什么能并行，什么不能

不用等一个任务结束再开下一个，几个互不影响的任务可以同时推进，比如一个项目修 README，另一个项目做测试失败分析，第三个项目检查前端页面，第四个项目整理 issue。

关键不在“开很多个”，在于拆得足够独立。和管团队一样，你不能让 5 个人同时改同一个函数，还指望结果自动变好。同时开多个任务改同一批文件，会互相覆盖（坑第 5 条）。

别人的实测

并行前，给每个任务准备独立的分支或工作目录，写清交付范围，避免同时修改同一批文件。能省多少时间取决于任务之间的依赖和最后的合并成本，不能按同时运行的数量推算速度。

Part E：交给云端、手机和其他设备

Cloud 适合什么

Codex Cloud 在自己的云端环境里后台运行任务，支持并行，电脑合上盖子也能继续，人在外面还能用手机发起任务。代码审查这类不需要一直盯着屏幕的异步任务很适合交给云端。连接 GitHub 后，它基于仓库工作并产出 PR。

第一次连上云端

本地 Codex 在你电脑上干活，云端 Codex 连到你的 GitHub 仓库里干活。已有 GitHub 仓库可以跳到第 3 步。

1. 初始化 Git 仓库

cd d:\test\
git init

执行后 App 上会多出一个“提交”按钮，点击、填写提交说明、继续，修改记录就保存了。提交说明好好写，别全写 update。

2. 创建 GitHub 远程仓库并推送（在 GitHub 新建一个名为 test 的仓库，把地址换成你自己的）

git remote add origin https://github.com/ailot/test.git
git branch -M main
git push -u origin main

git remote add 之后，App 上的推送按钮会变成可点；执行 git push 时会提示你登录 GitHub，成功后终端和 GitHub 仓库都能看到推送的文件。

3. 连接 Codex 到 GitHub

  1. 打开 https://chatgpt.com/codex/cloud，点击“连接到 GitHub”；
  2. 点击继续，选择 Authorize 授权；
  3. 进入云端 Codex 后配置远端代码仓库，选择刚创建的 test 仓库，点击 Install & Authorize，输入密码授权；
  4. 刷新页面，test 仓库就出现在 Codex 里了。

第一条任务先问“这是个什么项目”，测试它有没有看懂仓库。发送后它会在下面创建一个任务，点进去看执行结果。

在 VS Code 里用云端

本地和云端之间来回交接

一次要几个方案

手机、多设备和 SSH

三个概念别混：

  1. 让手机控制这台 Mac：想在手机上看进度、发新任务、审批操作，就把手机和桌面端打通。流程：桌面端开始设置 → 手机扫码 → 手机授权 → 桌面端确认允许 → 手机端选择项目发任务。
  2. 让这台 Mac 控制其他设备：有多台 Mac（比如 MacBook 和 Mac mini）时用。最容易踩的坑：被控的那台 Mac 要先打开“允许其他设备连接”，主控 Mac 才能添加设备。添加后，新任务里就能选远程项目。
  3. 通过 SSH 连接远程项目：服务器、devbox、AI 编程机用这个。

一句话：设备连接解决“哪台电脑干活”，SSH 解决“哪个远程目录干活”，手机解决“人不在电脑前怎么调度”。三者叠起来，Codex 就从本机工具变成了随时随地的工作调度系统。

Part F：自动化和团队接入

Automations：第二阶段再玩

先把普通任务、diff、测试跑明白，再用自动化。适合“重复发生、规则清楚、结果可检查”的事，比如：每天检查某个项目有没有失败的测试；每周整理一次依赖更新风险；定期扫描文档里的过期链接；每天给某个仓库的 issue 分类；每周生成一次项目变更摘要。

最关键的是把任务写清楚。别写“每天帮我看看项目有没有问题”，太虚。改成：

每天上午 10 点检查这个仓库：
1. 拉取最新主分支
2. 运行 npm run lint
3. 运行 npm test
4. 如果失败，汇总失败命令、错误摘要、疑似相关文件
5. 不要自动修改代码，只给报告

无界面模式 + 结构化输出

Codex CLI 也可以通过程序调用，接进自动化流程，或在容器里独立运行。

用 Agents SDK 搭多步骤、多角色流程

团队里的其他接法

Part G：模型和额度

模型怎么选

额度和成本

附：用 Codex 覆盖软件开发全流程

OpenAI 发布过一份指南，讲怎么打造以 AI 为核心的工程团队，把软件开发拆成七个阶段，从前期规划和设计一直到文档编写与后续维护。可以想想 Codex 在每个环节能帮什么：

继续学习的资源

按需查阅的官方文档

相关阅读