💡阅读指南

SPEC、Plan 和实施报告模板都已经准备完成,现在可以把完整实现交给 Codex。这一节给出实际使用的 /goal 提示词,同时说明执行过程中应该观察什么,以及什么时候才能判定开发完成。

9.1 这一步强烈建议使用 /goal

胶囊系统的实现不是一个几分钟就能结束的小计划。Codex 需要阅读多份设计文档,再完成 Python 模块、CLI、Skill、飞书适配和多层测试。测试失败以后,它还要回到代码继续修正。这种任务有明确的最终交付物,中间却需要多轮规划、实现和验证,正适合使用 /goal 模式。

之前 Hermes 里讨论过 /goal 模式,Codex 里也有,而且原理一摸一样。

虽然普通的 Prompt 也可以执行这个开发任务,但 Agent 有可能在完成一部分模块、跑完一组测试或给出一份中期总结以后就停下来。/goal 会把“完成 P1、P2 全部实现”保持为当前目标,继续推进,直到完成标准已经满足,或者遇到确实需要用户或外部环境处理的阻塞。

/goal 并不会让一条含糊的提示词自动变好。目标里仍然要写明执行范围、硬约束和完成标准,验收条件尤其不能只写“把项目做完”。Codex 可以自己决定具体的开发顺序,但不能自己改变 SPEC 和 Plan 已经确定的边界。

9.2 交给 Codex 的最终提示词

在 Codex 中打开胶囊系统项目目录,建立一个新会话,然后输入下面这条目标。Codex 必须阅读这些文件,而不是依赖提示词里的二次摘要。

Text
/goal 完成胶囊系统 001-capsule-main-flow 的 P1、P2 全部实现。

依据:
- 读取当前项目中适用的 AGENTS.md。
- 读取 specs/001-capsule-main-flow/spec.md。
- 读取该功能目录中的全部 Plan 产物,包括 plan.md、research.md、data-model.md、contracts/ 和 quickstart.md。
- 读取 specs/001-capsule-main-flow/implementation-report-template.md。

执行要求:
1. 开始编码前先检查现有代码和工作区,保留用户已有修改,不得擅自还原或删除。
2. 在进入自动开发以前,根据 quickstart.md 和飞书存储契约完成外部环境预检:检查 `lark-cli` 配置和登录状态、飞书应用权限、目标资源权限,以及专用验收空间是否已经准备。验收只能使用专用测试资源,不得操作用户的正式数据。
3. 如果缺少飞书配置、登录授权或必要的资源标识,主动执行安全的初始化或登录命令。当授权流程必须由用户在浏览器或飞书中完成时,暂停当前步骤,向用户说明正在等待的具体操作。用户完成后重新验证,然后继续同一个 Goal,不得因为这次正常交互就结束任务。不得要求用户在对话中直接粘贴访问令牌或客户端密钥,应使用飞书正式授权流程或安全的凭证存储。
4. 飞书环境预检通过后,自行制定并持续更新执行计划,可以根据代码和测试结果调整顺序;本项目不生成 tasks.md。
5. 按照 SPEC 完成 P1、P2,并遵守 Plan 已经确定的架构、数据边界和模块契约。不实现 SPEC 和 Plan 明确排除的功能,不把发布打包扩大到本轮开发中。
6. 根据 SPEC 的功能需求、边界情况、验收场景和成功标准,以及 Plan 中的测试策略,创建或更新必要的单元测试、契约测试、集成测试和端到端验收测试。不能只运行已有测试。
7. 实现过程中持续运行与当前修改相关的测试;实现完成后运行全部自动化测试,包括使用专用飞书空间的实时端到端验收测试,并根据失败结果继续修正。不得伪造测试通过或外部系统验收结果。
8. 实际执行逐项核对:每一条用户故事、验收场景、边界情况、功能需求和成功标准,都必须能指向实现文件、测试文件或其他可检查的验证方式。
9. 完成后按 implementation-report-template.md 生成 specs/001-capsule-main-flow/implementation-report.md。报告必须填写真实的实现位置、测试命令、结果数量、Plan 偏离、未完成项和最终判断,不得保留模板占位内容。

完成标准:
- P1、P2 的代码和必要测试已经完成,SPEC 各条要求都有可核对的实现或验证依据。
- 飞书配置、授权、资源权限和专用验收空间已经通过实际检查。
- 全部自动化测试和实时飞书端到端验收测试已经实际运行,没有被隐藏或未解释的失败。
- implementation-report.md 已经完整生成,所有结论与真实代码和测试结果一致。
- 最终回复需要概括实际完成的功能、测试结果、尚未解决的问题,并给出实施报告的路径。

阻塞处理:
- 需要用户完成飞书登录、授权或选择专用验收资源时,这属于 Goal 内的正常交互,不属于任务失败。明确告诉用户应该完成的操作,等待用户处理,验证成功后继续执行。
- 只有当用户明确拒绝或无法提供必要授权、无法准备专用验收资源,或飞书平台经过合理检查后仍然不可用时,才能将 Goal 标记为阻塞。此时必须在实施报告中写明已完成的部分、缺少的条件和恢复后应执行的命令,不得宣布目标完成。
- 遇到问题时先尝试在现有 SPEC 和 Plan 范围内解决。只有在缺少用户决定或外部条件,并且已经无法继续完成其他有意义的工作时,才报告阻塞。

不得因为已经生成项目骨架、完成部分模块、通过部分测试或写出总结,就宣布目标完成。

运行截图:

启动这个任务后先不要走开,可能需要你通过交互来授权飞书:

随后才可以无人值守的自行运行。这个任务估计很长,十几个小时是需要的。

💡提示

这里还要说明,由于每个人的环境不一样,所以中间可能会遇到一些问题,而这些问题具有个体差异性,我无法一一复现。但是,有任何问题你都可以和你的Agent 交流,委托他去解决。如果实在解决不了,可以去教材提问区提问。

最终完成对话:

可以看到历时 1小时 34 分,消耗180 万tokens。

9.3 从实施报告判断是否完成

/goal 显示完成,不能直接等同于项目通过验收。最终还是要打开 implementation-report.md,核对实际实现范围、测试命令和 SPEC 逐项对照表。飞书授权完成以后,Codex 应该自动继续实时验收;如果这一部分最终没有运行,Goal 只能记为阻塞,不能宣布完成,也不能凭借 Mock 测试把它等同为真实飞书验收已经通过。

到这里,我们已经把一条需求从需求简报、SPEC、Plan 一直推进到代码、测试和实施报告。

9.4 这就算完成了项目吗?

分两个层面讨论这个问题。

第一,目前代码执行生成完成不等于已经把产品交给最终用户。安装、环境检查、版本升级和卸载属于后续的发布阶段。目前,你确实在开发阶段完成了一个初版,可以直接在你的 Codex 上进行人工测试了。

第二,为了演示一种更普遍的、更适合教学的场景,我在第一轮代码生成中并没有把每个需求都考虑的很完善。这样做有的原因有二: 1. 纯粹的“思想实验”不可能一步到位做出分毫不差的产品。我们总是要有一个可以实际操作的产品 MVP来一边操作,一边思考还有哪些缺点。然后再逐步完善。 2. 从软件工程的角度来讲,产品迭代是一种常态。教材必须要向同学讲述至少一次的产品迭代过程,才能满足教学要求。

当你跑完这一轮后,即使报告 100%通过了测试,但一定会有很多你用着不舒服的地方。我自己试用就发现了不少不满意的点。比如:

  1. 在第一次接受知识 URL 时并没有检查或者提示用户新建飞书知识库,而是要求用户自己去手动创建。
  2. 微信公众号的风控有时候会导致文章抓取失败。
  3. 演化层的演化效果不够理想
  4. 由于是运行在 Codex 里进行的人工测试,所以 Codex 居然一边测试一边修改代码。这个行为很危险,这也是现在 Agent 产品独有的问题,以前传统时代一个测试人员是不可能去修改你的代码的。

有同学会想,一边运行一边修改代码有什么问题?这不是挺好的吗?确实,你一个人用那没关系,而且非常爽。但如果我们要开发的是一个企业级的产品这样做会带来很多隐患。关于这一点我们后面再讨论。

所以胶囊系统第一阶段的目标只是带着大家学会整个 SDD 的流程,没有过度追求功能的效果与完善。从功能的角度来讲,这一版是不合格的。我们要做的是有用的、好用的,而不只是个 Demo。

所以准备开启胶囊系统的 Part2,我们继续迭代完善胶囊的功能。