Codex Playbook 05：不会用 /goal，就还没真正用懂 Codex

摘要

Codex 的关键不是多写代码，而是把模糊任务变成可验证、可迭代、可复用的目标合约。

这篇 Playbook 适合 AI 产品经理、独立开发者、技术团队负责人、AI Native Builder，以及非工程背景但想用 Codex 推进项目的人。

01. 先给结论：Codex 的正确工作流是 Plan → Goal → Execute → Review → Skill

不会用 /goal，不是因为你不会写提示词，而是你还没有把 Codex 当成一个目标驱动的执行系统。

真正高效的 Codex 工作流不是：

Prompt → 等结果

而是：

Plan → Goal → Execute → Review → Skill

也就是：

阶段	作用
Plan	先让 Codex 理解任务、拆解路径、识别风险
Goal	把任务变成可验证、可约束、可停止的目标合约
Execute	让 Codex 执行、测试、修复、记录
Review	检查 diff、结果、风险和未覆盖项
Skill	把高频流程沉淀成可复用方法

这套流程的关键不是“让 Codex 多写代码”，而是让 Codex 每一步都有目标、有边界、有证据、有复盘。

Codex 的正确工作流是 Plan → Goal → Execute → Review → Skill。

Codex 的正确工作流是 Plan → Goal → Execute → Review → Skill。

所以，/goal 不是一个更长的 Prompt。

/goal 是 Codex 从“代码助手”变成“执行系统”的关键开关。

02. 为什么 Codex 不能只靠 Prompt？

过去我们用 AI 编程工具，习惯是这样提需求：

帮我优化首页。
帮我修一下 bug。
帮我补一下测试。
帮我重构这段代码。

这些提示当然能用，但问题是：它们没有完成标准。

Codex 不知道：

修到什么程度算完成；
需要跑哪些测试；
哪些文件不能动；
能不能引入新依赖；
是否允许重构；
如果运行环境失败要不要继续；
是否需要列出未覆盖部分；
最后要不要沉淀成文档或 Skill。

所以，普通 Prompt 很容易导致三个问题：

第一，任务越做越散。第二，改动范围失控。第三，Codex 自己宣布完成，但你没有证据验证。

/goal 解决的正是这个问题。

它不是“更长的提示词”，而是一个目标合约。

03. 五步方法论：Plan → Goal → Execute → Review → Skill

第一步：Plan，先计划，不要急着执行

复杂任务不要一上来就让 Codex 写代码。

你可以先让 Codex 输出：

请先不要写代码。

先分析这个任务，并输出：
1. Plan：你准备怎么做
2. Risk：可能有什么风险
3. Files likely to change：可能会改哪些文件
4. Verification strategy：如何验证完成
5. Questions / assumptions：有哪些假设或疑问
6. Uncovered risk：哪些部分可能无法覆盖

Plan 的价值是让 Codex 先理解局面，避免一上来就动手乱改。

第二步：Goal，把任务变成目标合约

一个好的 /goal 必须回答七个问题：

模块	要回答的问题
Outcome	最终要达成什么结果？
Verification	用什么证据证明完成？
Constraints	哪些东西不能被破坏？
Boundaries	允许改哪里？不允许改哪里？
Iteration Policy	每轮失败后如何继续尝试？
Blocked Condition	什么情况下必须停止并报告阻塞？
Uncovered Items Check	哪些地方没覆盖，为什么没覆盖？

很多人写 Goal，只写“我要什么”，但没有写“不能做什么”和“什么时候停”。

这会导致 Codex 过度发挥。

真正强的 Goal，不只是推动执行，还能约束执行。

一个好的 /goal 至少包含 Outcome、Verification、Constraints、Boundaries、Iteration Policy、Blocked Condition 和 Uncovered Items Check。

一个好的 /goal，既要定义目标，也要定义边界、验证和停止条件。

第三步：Execute，执行时必须记录证据

执行不是让 Codex 闷头改。

你应该要求它每轮都记录：

1. 本轮做了什么
2. 为什么这么做
3. 验证结果是什么
4. 下一步最可能有效的尝试是什么

这样你看到的不是一个模糊总结，而是一条可检查的执行轨迹。

第四步：Review，交付前必须审查

Codex 完成后，不要只看它的总结。

你要检查：

1. diff 是否合理
2. 是否超出边界
3. 测试是否真的跑了
4. 是否有失败项
5. 是否列出未覆盖项
6. 是否引入新依赖
7. 是否存在潜在回归风险

Codex 的总结只能作为线索，不能替代 Review。

第五步：Skill，把高频流程沉淀下来

如果一个任务未来还会重复，就不要每次重写 Prompt。

应该沉淀成 Skill。

例如：

产品说明文档生成 Skill；
Design System 抽象 Skill；
可访问性检查 Skill；
安全审查 Skill；
单元测试生成 Skill；
GEO 内容优化 Skill；
官网文案三轮审校 Skill。

Goal 是一次任务的目标合约。 Skill 是一类任务的复用流程。

这就是从“会用 Codex”到“能让 Codex 越用越稳定”的关键。

04. 最小可用 /goal 模板

下面是一个可以直接复制的通用模板：

/goal <最终要达成的状态>，
通过 <具体验证方式> 证明完成，
同时保持 <不能破坏的约束>。

只允许修改 <允许修改的文件、目录、模块或能力范围>。
不得修改 <禁止修改的文件、目录、模块或能力范围>。

每轮迭代后记录：
1. 做了什么改动
2. 验证结果是什么
3. 下一步最可能有效的尝试是什么

如果无法继续推进，停止并报告：
1. 已尝试的方法
2. 看到的证据
3. 当前阻塞点
4. 下一步需要我提供什么

最后必须列出：
1. 已覆盖的功能 / 页面 / 文件
2. 未覆盖的功能 / 页面 / 文件
3. 未覆盖原因
4. 后续建议

这里最重要的是最后一组：未覆盖项反向检查。

很多复杂任务里，Codex 可能会跳过难跑、难截图、难验证的部分，然后告诉你“已完成”。

所以你要强制它列出：

哪些覆盖了？
哪些没覆盖？
为什么没覆盖？
下一步怎么补？

这会显著提升 Codex 的交付可信度。

05. 最适合 /goal 的任务类型

不是所有任务都适合 /goal。

如果只是解释一段代码、改一个变量、写一小段函数，普通 Prompt 更快。

但如果任务具备以下特征，就非常适合 /goal：

需要多轮执行；
需要运行环境；
需要测试验证；
需要截图检查；
需要持续更新；
需要保持约束；
需要沉淀成流程；
需要输出一份可交付文档；
需要明确列出未完成部分。

可以这样判断：

一次性回答，用 Prompt。持续推进，用 Goal。高频复用，沉淀成 Skill。长期稳定，设计 Eval。

最适合 /goal 的任务，是需要持续推进、反复验证、保持约束的任务。

最适合 /goal 的任务，不是小改动，而是需要持续推进、反复验证、保持约束的复杂任务。

06. 高价值 /goal 场景一：产品说明文档

很多产品的问题不是没有功能，而是功能做出来以后：

用户不知道怎么用；
团队没有持续更新文档；
新功能上线后没人补说明；
页面和按钮越来越多，但没有统一的用户手册。

这类任务可以让 Codex 基于当前 commit，运行真实 App，检查页面，截图，梳理功能，再生成面向普通用户的产品说明文档。

可直接复制的 Goal

/goal 基于当前 commit 的产品功能，运行真实 App / 模拟器 / 浏览器调试环境，检查主要页面、按钮、操作路径和点击后的行为，产出一份面向普通用户的产品说明文档。

文档需要用简洁清晰的语言解释：
1. 每个主要页面是做什么的
2. 每个主要按钮和入口有什么作用
3. 用户应该如何完成核心操作
4. 点击之后会发生什么
5. 这些功能为什么有用

文档应作为后续功能更新的持续记录基础，而不是一次性说明。

验收标准：
1. 成功启动本地运行环境、虚拟机、模拟器或真实 App。
2. 使用浏览器调试能力、CDP 或截图工具获取关键页面截图。
3. 覆盖当前 commit 中已有的主要功能、页面和交互。
4. 逐项说明按钮、入口、状态变化和点击后的结果。
5. 文案面向普通用户，避免技术实现细节。
6. 表达简洁清楚，可直接作为用户帮助文档初稿。
7. 文档结构支持后续持续追加功能更新。

反向检查：
1. 列出哪些页面、功能或交互没有被覆盖。
2. 说明未覆盖原因，例如无法启动、需要登录、缺少数据、截图失败、路径不明确。
3. 给出下一步补齐这些未覆盖项的建议。

最后总结并沉淀为一个可复用 Skill，包含：
1. 运行项目
2. 页面检查
3. 截图采集
4. 功能梳理
5. 用户说明撰写
6. 后续更新文档的标准流程

这个场景的价值在于，它让 Codex 不只是写代码，而是参与产品资产沉淀。

适合生成：

产品说明文档；
用户使用手册；
帮助中心初稿；
Onboarding 文案；
Release note；
内部培训材料。

07. 高价值 /goal 场景二：Design System 抽象

很多产品越做越乱，不是因为功能复杂，而是因为 UI 组件、样式和交互模式没有统一。

常见问题包括：

同一个按钮有三种样式；
同一个卡片有多个实现；
表单交互不一致；
页面间距不统一；
颜色、字号、圆角到处漂移；
后续每次改版都很痛苦。

这类问题非常适合用 /goal 做系统性治理。

可直接复制的 Goal

/goal 将当前项目中分散的 UI 组件、样式规范和交互模式抽象为统一的 Design System，沉淀为可复用、可维护的组件库。

目标是让所有业务页面优先使用组件库提供的标准组件，逐步移除独立手写组件，避免重复实现、视觉不一致和交互错误。

验收标准：
1. 梳理当前项目中已有的主要 UI 组件、样式模式和交互模式。
2. 识别重复实现、命名混乱、视觉不一致和交互不一致的问题。
3. 设计一套最小可用的 Design System 结构，包括按钮、输入框、卡片、弹窗、导航、布局容器、状态提示等基础组件。
4. 尽量复用现有代码，不做不必要的大规模重写。
5. 将高频重复组件优先抽象为标准组件。
6. 至少选择 1-2 个典型页面完成组件替换示范。
7. 保持现有业务逻辑不变。
8. 保持现有配色系统不变，除非明确获得许可。
9. 本地 build、lint、typecheck 通过，或解释无法运行的原因。

反向检查：
1. 列出哪些组件已经完成标准化。
2. 列出哪些组件仍然是手写或分散状态。
3. 说明未标准化的原因。
4. 给出下一轮 Design System 收敛建议。

最后输出：
1. Design System 目录结构建议
2. 已抽象组件清单
3. 待抽象组件清单
4. 迁移优先级
5. 后续组件开发规范

第一阶段做产品，可以追求速度。第二阶段做产品，必须开始收敛。

Design System 抽象，就是把“能跑的产品”变成“可维护的产品”。

08. 高价值 /goal 场景三：可访问性与多端适配

很多 AI 应用、SaaS 工具、独立产品都容易忽视一个问题：

产品在不同设备、不同屏幕、不同使用场景下，是否真的可用？

常见问题包括：

移动端按钮太小；
小屏幕横向溢出；
弹窗无法关闭；
表单错误提示不清楚；
低视力用户看不清；
键盘无法完成操作；
重要信息只靠颜色区分；
加载、空状态、禁用状态没有明确提示。

这些问题不一定影响 demo，但会影响真实用户体验。

可直接复制的 Goal

/goal 检查并优化当前产品在不同设备、屏幕尺寸和辅助使用场景下的体验，确保普通用户、低视力用户、键盘用户以及使用不同设备的用户都能稳定、清晰、顺畅地完成核心操作。

验收标准：
1. 检查桌面端、平板端和移动端的主要页面布局。
2. 检查核心流程是否存在横向溢出、遮挡、按钮过小、文字过密等问题。
3. 检查主要交互是否支持键盘操作。
4. 检查按钮、表单、链接、弹窗是否有清晰的可访问性语义。
5. 检查表单错误、加载状态、空状态、禁用状态是否清楚。
6. 检查颜色对比度是否影响阅读。
7. 检查重要信息是否只依赖颜色表达。
8. 在不改变产品视觉风格的前提下，完成必要优化。
9. 本地 build、lint、typecheck 通过，或解释无法运行的原因。

反向检查：
1. 列出已检查的页面、设备尺寸和交互路径。
2. 列出未检查的页面或设备场景。
3. 说明未覆盖原因。
4. 给出后续可访问性优化清单。

最后输出：
1. 已修复问题
2. 未修复但建议处理的问题
3. 对用户体验影响最大的三个风险
4. 后续多端适配规范

这类 Goal 的价值在于：它让产品从“能跑”变成“能被更多人稳定使用”。

09. 高价值 /goal 场景四：网络安全代码审查

如果项目要真实上线，安全审查不能只靠感觉。

尤其是涉及：

用户账号；
登录注册；
支付；
权限管理；
API；
数据库；
文件上传；
第三方依赖；
环境变量；
管理后台。

都应该做一轮安全代码审查。

但注意：安全类任务不要一上来就让 Codex “自动修复所有问题”。

更合理的方式是：

先审查，出报告；再分级，定优先级；最后人工确认是否修改。

可直接复制的 Goal

/goal 对当前项目进行一次面向真实上线风险的网络安全代码审查。

基于当前 commit 的代码、依赖、配置、接口和运行环境，系统性检查可能影响用户数据、账号安全、权限边界、服务稳定性和供应链安全的问题。

审查范围包括：
1. 认证与鉴权
2. 会话管理
3. 输入校验
4. 权限控制
5. 敏感信息处理
6. 数据库访问
7. 文件上传与下载
8. API 暴露
9. 环境变量和密钥管理
10. 第三方依赖和供应链风险
11. 错误日志和异常暴露
12. 管理后台与内部接口

验收标准：
1. 梳理项目中与安全相关的关键文件、接口和配置。
2. 标记高风险、中风险、低风险问题。
3. 每个问题需要说明风险原因、可能影响和触发条件。
4. 不要直接进行大规模修复，除非问题非常明确且修改范围很小。
5. 对每个问题给出建议修复方式。
6. 区分真实风险、潜在风险和需要人工确认的风险。
7. 不夸大风险，不编造不存在的接口或配置。

反向检查：
1. 列出已审查的模块、接口和配置。
2. 列出未审查的部分。
3. 说明未审查原因，例如缺少环境、缺少权限、依赖未安装、无法运行项目。
4. 给出下一轮深度安全审查建议。

最后输出一份安全审查报告，包括：
1. 总体风险评级
2. 高优先级问题
3. 中低优先级问题
4. 建议立即修复项
5. 建议上线前确认项
6. 后续安全治理建议

AI 可以加速开发，也会加速风险积累。

越是 AI 快速生成的项目，越应该做安全审查。

10. 高价值 /goal 场景五：生成单元测试

社区里最常见、也最实用的 Codex / Goal 用法之一，就是生成单元测试。

但这里有一个坑：

不要只说“帮我补测试”。

否则 Codex 可能会生成很多看起来有测试、但其实没有覆盖关键逻辑的低价值用例。

更好的方式是要求它先分析风险路径，再补测试。

可直接复制的 Goal

/goal 为当前模块补充高价值单元测试，优先覆盖核心逻辑、边界条件、异常路径和历史易错点。

不要为了提高测试数量而生成低价值测试。
不要只测试实现细节，要优先测试对外行为和关键业务规则。

验收标准：
1. 先阅读目标模块代码，梳理核心行为和风险路径。
2. 列出当前已有测试覆盖了什么。
3. 找出缺失的关键测试场景。
4. 为高优先级场景补充单元测试。
5. 测试应包含正常路径、边界条件、异常输入和权限/状态变化。
6. 不得为了通过测试而修改业务逻辑，除非发现明确 bug。
7. 运行相关测试并记录结果。
8. 如果测试环境无法运行，说明原因并给出人工运行命令。

反向检查：
1. 列出已覆盖的测试场景。
2. 列出尚未覆盖的测试场景。
3. 说明未覆盖原因。
4. 给出下一步测试补齐建议。

最后输出：
1. 新增测试文件和用例清单
2. 覆盖的业务风险
3. 未覆盖风险
4. 测试运行结果

单元测试类 Goal 的关键，不是“多写测试”，而是让测试覆盖真实风险。

11. 高价值 /goal 场景六：GEO 内容优化

GEO，全称 Generative Engine Optimization，可以理解为“面向 AI 搜索与生成式答案的内容优化”。

传统 SEO 关注的是：

人能不能在搜索引擎里搜到你。

GEO 关注的是：

AI 能不能正确理解、引用、推荐和复述你。

对于 ReelOS.ai 这样的知识型网站，GEO 非常重要。

因为你写的 Playbook、Signals、案例、模板，不只是给人读，也会被 AI 搜索系统读。

未来用户可能不会只在 Google 里搜：

Codex Goal 最佳实践

他们可能会直接问 AI：

Codex /goal 怎么用？
AGENTS.md 怎么写？
AI Agent 产品怎么设计？
普通人怎么用 Codex 做产品？
AI Native Builder 应该怎么开始？

这时，如果你的内容结构清晰、定义明确、有步骤、有对比、有模板、有证据、有 FAQ、有更新记录，就更容易被 AI 理解和引用。

可直接复制的 Goal

/goal 对当前文章 / 页面 / 文档进行一次 GEO 优化，让它更容易被 ChatGPT、Perplexity、Gemini、Google AI Overviews 等生成式搜索系统理解、引用和推荐。

优化目标不是堆关键词，而是提升内容的：
1. 实体清晰度
2. 定义准确性
3. 结构可解析性
4. 问答覆盖度
5. 引用可信度
6. 可摘录性
7. 更新可追踪性

验收标准：
1. 明确文章的核心主题、目标读者和核心问题。
2. 在开头给出一句话定义，说明本文解决什么问题。
3. 补充关键概念定义，例如 Codex、Goal、AGENTS.md、Skill、Eval、GEO。
4. 将长段落拆成清晰的小标题、列表、表格和步骤。
5. 增加 FAQ 模块，覆盖用户最可能搜索或追问的问题。
6. 增加“可直接复制的模板”或“操作清单”，提高内容可复用性。
7. 增加对比表，例如 SEO vs GEO、Prompt vs Goal、Goal vs Skill。
8. 检查是否有模糊、夸张、无法验证的表述，并改成具体表达。
9. 补充必要的参考链接、来源或证据。
10. 增加最后更新时间或版本说明，方便后续持续更新。
11. 保持原有观点和风格，不要为了 GEO 把文章改成低质量关键词堆砌。

反向检查：
1. 列出已经优化的部分。
2. 列出仍然不适合被 AI 引用的部分。
3. 说明原因，例如缺少定义、缺少证据、结构太散、没有 FAQ、没有可摘录结论。
4. 给出下一轮 GEO 优化建议。

最后输出：
1. GEO 优化后的文章结构
2. 新增或修改的小标题
3. 新增 FAQ
4. 新增定义区
5. 新增对比表
6. 新增可引用摘要
7. 修改前后主要差异

SEO vs GEO 对比

维度	SEO	GEO
面向对象	搜索引擎排名系统	AI 搜索与生成式回答系统
核心目标	获得搜索排名和点击	被 AI 理解、引用、推荐
优化重点	关键词、外链、页面体验、权威性	定义、结构、证据、问答、可摘录性
内容形态	标题、正文、内链、元信息	摘要、FAQ、表格、步骤、引用源
成功指标	排名、点击率、流量	被引用、被吸收、品牌提及准确性
主要风险	关键词堆砌、低质内容	被 AI 误读、错引、不引用
最佳实践	高质量内容 + 技术 SEO	高质量内容 + 结构化表达 + 明确证据

ReelOS.ai 的 GEO 内容结构建议

每篇 Playbook 都可以固定保留五个模块：

1. 一句话结论
2. 核心概念定义
3. 使用场景
4. 可直接复制的模板
5. FAQ

这不是为了堆格式，而是为了让内容更容易被人读懂，也更容易被 AI 正确解析。

12. 高价值 /goal 场景七：官网 UI 多轮优化

适合产品官网、落地页、SaaS 首页、多轮视觉迭代。

尤其适合这类需求：

希望优化视觉层级；
希望提升字体和排版；
希望改进移动端体验；
但不希望乱改配色；
不希望改业务逻辑；
不希望引入新依赖。

可直接复制的 Goal

/goal 在不改变现有配色系统的前提下，提升 ReelOS.ai 官网的视觉层级、排版节奏、字体一致性和移动端可读性。

通过以下方式验证：
1. 本地 build 成功
2. 关键页面无明显布局错误
3. 移动端和桌面端主要页面可读性提升
4. 没有新增 lint/type 错误

只允许修改 UI、布局、文案和样式相关文件。
不得修改业务逻辑、数据结构、路由机制和现有配色系统。

每轮迭代后记录：
1. 修改了哪些文件
2. 视觉收益是什么
3. 可能带来的风险
4. 下一步还能优化哪里

如果发现设计约束冲突，停止并说明冲突点、可选方案和推荐路径。

最后列出：
1. 已优化页面
2. 未优化页面
3. 未优化原因
4. 下一轮建议

这类 Goal 的关键是提前写死边界：

不得改变现有配色系统。
不得修改业务逻辑。
不得引入新依赖。

边界越清楚，Codex 越稳定。

13. 高价值 /goal 场景八：Bug 修复

Bug 修复非常适合 /goal，但前提是你要要求 Codex 先复现，再修复。

不要一上来就让它改代码。

可直接复制的 Goal

/goal 修复当前 failing test 对应的问题，并通过相关测试验证。

优先复现 bug，再定位根因，再做最小修改。
不得绕过测试，不得删除失败用例，除非能证明测试本身错误。

只修改与该 bug 直接相关的代码和测试。
不要顺手重构无关模块。

每次修改后运行相关测试，并记录：
1. 失败日志
2. 根因判断
3. 修改内容
4. 测试结果

如果无法复现、依赖缺失或测试环境不可用，停止并报告阻塞原因和下一步需要的信息。

最后列出：
1. 已验证通过的测试
2. 未能验证的测试
3. 未验证原因
4. 潜在回归风险

这个模板能防止 Codex 为了“通过测试”而做危险动作，比如：

删除测试；
跳过断言；
修改测试而不是修 bug；
扩大修改范围；
顺手重构无关模块。

14. 高价值 /goal 场景九：性能优化

性能优化非常适合 /goal，因为它天然需要多轮实验。

每一轮都要有：

假设；
修改；
benchmark；
对比；
下一步实验。

可直接复制的 Goal

/goal 将 checkout benchmark 的 p95 延迟降低到 120ms 以下。

通过 checkout benchmark 验证，同时保持 correctness test suite 全部通过。

只允许修改 checkout service、benchmark fixtures 和相关测试。
不得修改公共 API，不得降低数据正确性，不得移除已有错误处理逻辑。

每轮迭代后记录：
1. 本轮假设
2. 修改内容
3. benchmark 结果
4. correctness test 结果
5. 下一轮最可能有效的实验

如果连续三轮没有有效改善，停止并报告已尝试路径、证据、可能瓶颈和建议的人类决策。

最后列出：
1. 已尝试优化路径
2. 有效优化路径
3. 无效优化路径
4. 剩余性能瓶颈

性能优化不要只说“让它更快”。

要写清楚：

哪个指标？
目标是多少？
用什么 benchmark？
不能牺牲什么？
失败几轮后停止？

15. 高价值 /goal 场景十：文案三轮 Review

/goal 不只适合代码任务，也适合文案、产品定位、官网表达、内容审校。

尤其是你希望 Codex 多轮审校，而不是一次性润色时。

可直接复制的 Goal

/goal 对当前官网文案完成三轮审校：清晰度、转化力、专业可信度。

最终输出一版可直接替换的文案，并保留每处关键修改理由。

不得改变 ReelOS.ai 的定位：AI Native Builder Lab。
不得引入夸张、空泛、不可验证的宣传语。
不得把个人实验室写成大公司口吻。

每轮审校聚焦一个维度：
第一轮：用户是否能看懂
第二轮：是否有行动吸引力
第三轮：是否足够专业可信

如果信息不足，列出缺失信息，不要编造案例、数据或客户背书。

最后输出：
1. 原文主要问题
2. 三轮修改逻辑
3. 最终可发布版本
4. 不建议使用的表达
5. 后续可 A/B 测试的方向

这个模板适合：

官网文案；
产品介绍；
博客标题；
Playbook 草稿；
About 页面；
投资人材料；
用户邮件；
发布说明。

16. AGENTS.md：把重复规则沉淀成项目记忆

如果说 /goal 是一次任务的目标合约，那么 AGENTS.md 就是一个项目的长期工作规则。

它适合写：

项目结构；
运行命令；
测试方式；
代码规范；
PR 要求；
禁止事项；
完成标准；
产品定位；
文案风格；
设计限制。

一个最小可用版本如下：

# AGENTS.md

## Project Overview
This is a Next.js + Supabase project for ReelOS.ai, an AI Native Builder Lab.

## Key Directories
- app/: routes and pages
- components/: reusable UI components
- lib/: shared utilities
- content/: articles, playbooks, signals
- supabase/: database and edge functions

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Type check: pnpm typecheck
- Lint: pnpm lint
- Test: pnpm test
- Build: pnpm build

## Rules
- Do not change the existing color system unless explicitly requested.
- Do not introduce new dependencies without explaining why.
- Keep changes minimal and reviewable.
- Prefer existing components before creating new ones.
- Preserve the positioning of ReelOS.ai as “AI Native Builder Lab”.
- Avoid exaggerated marketing claims.
- For documentation tasks, write for ordinary users, not developers.
- For UI tasks, always check desktop and mobile layouts.
- For review tasks, always list uncovered areas and reasons.
- For GEO tasks, add definitions, FAQ, tables, templates, and references.

## Done Means
Before finishing:
1. Run relevant tests or explain why they cannot run.
2. Run lint/typecheck when code changes.
3. Summarize changed files.
4. Mention risks or follow-up work.
5. If visual changes are made, describe what changed in layout, typography, spacing, or hierarchy.
6. If documentation is produced, list covered and uncovered features.
7. If content is optimized, list what changed for readability, structure, and GEO.

AGENTS.md 不需要一开始写得很长。

更好的方式是：

先跑任务，观察 Codex 重复犯什么错，再把稳定规则写进去。

不要把 AGENTS.md 写成愿望清单。

要写成 Codex 能执行的规则。

AGENTS.md 是项目长期规则，把重复提醒沉淀成 Codex 能执行的项目记忆。

AGENTS.md 不是愿望清单，而是项目长期规则。

17. 什么任务适合 /goal？什么任务不适合？

任务类型	是否适合 /goal	原因
产品说明文档	非常适合	需要运行、截图、梳理、持续更新
Design System 抽象	非常适合	需要盘点、归类、迁移、验证
可访问性与多端适配	非常适合	需要多页面、多设备、多状态检查
安全代码审查	适合	需要系统性检查和风险分级
单元测试生成	非常适合	需要覆盖核心逻辑和边界条件
GEO 内容优化	非常适合	需要结构化、定义、FAQ、引用、可摘录性
Bug 复现与修复	适合	需要复现、定位、验证
性能优化	非常适合	需要 benchmark 和多轮实验
Flaky test 排查	非常适合	依赖日志和迭代判断
官网多轮优化	适合	需要保持设计约束
文案多轮审校	适合	需要分轮评估和保留定位
依赖升级	适合	容易出现连锁问题
大型重构	适合，但必须收紧边界	否则容易扩散
一行代码修改	不适合	普通 Prompt 更快
简单解释问题	不适合	不需要持续执行
“帮我做得更好”	不适合	没有完成标准

判断标准很简单：

如果任务需要持续推进、反复验证、保持约束，就适合 Goal。如果任务只是一次性回答或小改动，就用普通 Prompt。

18. Codex / Goal 使用中的 9 条原则

原则一：不要只写任务，要写完成状态

弱提示：

帮我优化首页。

强 Goal：

/goal 提升首页首屏的信息清晰度和转化效率，通过桌面端和移动端截图检查、build 成功、无新增 lint/type 错误来验证。不得改变现有配色系统。

AI 最怕的不是任务难，而是“不知道什么算完成”。

原则二：不要只说“改好”，要给验证证据

好的验证方式包括：

场景	验证证据
代码修改	test / lint / typecheck / build
性能优化	benchmark / p95 / p99
UI 优化	截图 / 响应式检查 / 视觉说明
文案优化	修改理由 / 对比版本 / 目标用户解释
产品文档	页面截图 / 功能清单 / 用户路径
Bug 修复	复现步骤 / 失败日志 / 修复后结果
重构	测试通过 / API 不变 / diff summary
安全审查	风险等级 / 影响范围 / 修复建议
GEO 优化	定义 / FAQ / 表格 / 模板 / 参考链接

没有验证证据，Codex 就容易“自我宣布完成”。

原则三：边界比目标更重要

很多 Codex 任务失败，不是因为它不会做，而是因为它做得太多。

所以每个 Goal 都要写清楚：

只允许修改……
不得修改……
不要引入……
不要重构……
不要改变……

尤其是产品官网、业务系统、支付逻辑、权限系统、数据库结构，必须明确边界。

原则四：必须要求“未覆盖项反向检查”

在每个复杂 Goal 结尾加上：

最后必须列出：
1. 已覆盖的页面 / 功能 / 文件
2. 未覆盖的页面 / 功能 / 文件
3. 未覆盖原因
4. 后续补齐建议

这个要求可以防止 Codex 跳过难处理部分。

例如：

需要登录的页面；
跑不起来的模拟器；
截图失败的路径；
缺少测试数据的页面；
缺少权限的接口；
没有运行环境的功能。

它们都应该被明确列出来，而不是被默认忽略。

原则五：失败后要继续实验，但不能无限乱试

Goal 应该允许迭代，但也要有停止条件。

例如：

如果连续三轮没有改善，停止并报告：
1. 已尝试路径
2. 观察到的证据
3. 可能原因
4. 需要人类决策的点

这比让 Codex 无限尝试更安全。

原则六：重复性规则进 AGENTS.md，不要每次手写

例如你经常提醒 Codex：

不要改配色。
不要引入新依赖。
不要把文案写得太营销。
修改后要跑 build。
文档要面向普通用户。
必须列出未覆盖项。

这些不应该每次重复，而应该进入 AGENTS.md。

原则七：复杂任务先 Plan，不要直接 Execute

对于大任务，推荐先让 Codex 输出：

Plan
Risk
Files likely to change
Verification strategy
Questions / assumptions
Uncovered risk

再决定是否执行。

这一步能显著减少跑偏。

原则八：高频流程最后沉淀成 Skill

真正高价值的不是完成一次任务，而是把任务流程沉淀下来。

例如：

产品说明文档生成 Skill；
Design System 抽象 Skill；
可访问性检查 Skill；
安全审查 Skill；
单元测试生成 Skill；
GEO 内容优化 Skill；
官网文案三轮审校 Skill。

这样下一次不是重新写 Prompt，而是复用一套经过验证的流程。

原则九：用 Eval 检查长期稳定性

Goal 解决的是“这一次任务怎么完成”。

Eval 解决的是“长期看，它是否稳定”。

例如：

Codex 每次生成产品说明文档，是否都覆盖主要页面？
每次安全审查，是否都能识别高风险模块？
每次 GEO 优化，是否都补充定义、FAQ、模板和来源？
每次 UI 优化，是否都遵守“不改配色”的规则？
每次补单元测试，是否都覆盖边界条件和异常路径？

如果一个流程要反复使用，就应该为它设计 Eval。

19. 团队内部 Codex 使用 MVP 规范

可以直接作为团队制度使用：

环节	MVP 要求
任务输入	复杂任务必须写清目标、边界、验证方式
Goal 生成	先让 Codex 生成 `/goal` 草案，再人工确认
执行边界	明确可改文件、不可改文件、禁止事项
验证要求	每个任务必须有测试、build、截图、benchmark 或修改报告
反向检查	每个复杂任务必须列出未覆盖项和原因
规则沉淀	重复提醒超过两次，写入 `AGENTS.md`
交付检查	必须检查 diff、测试结果和风险说明
失败处理	Codex 必须报告尝试路径、证据和阻塞点
长期复盘	高频任务沉淀成 Playbook / Skill / Template
稳定评估	高频流程设计 Eval，定期检查输出稳定性

20. Codex / Goal / AGENTS.md / Skill / Eval 的关系

可以这样理解：

Prompt = 启动一次沟通
Goal = 当前任务的目标合约
AGENTS.md = 项目的长期规则
Skill = 可复用的操作方法
Eval = 长期质量评估机制
Review = 交付前的人工或自动检查

它们不是互相替代，而是分层协作。

Prompt、Goal、AGENTS.md、Skill、Eval 和 Review 是分层协作关系。

Prompt 启动沟通，Goal 定义任务，AGENTS.md 保存规则，Skill 复用流程，Eval 检查长期稳定性。

层级	解决什么问题
Prompt	启动一次沟通
Goal	这次任务要达成什么
AGENTS.md	这个项目长期遵守什么规则
Skill	这类任务以后怎么复用
Eval	长期效果是否稳定
Review	本次交付是否可信

这也是 AI Agent 产品设计里的核心趋势：

不是单纯让模型更聪明，而是给模型更清晰的目标、上下文、工具、边界和验证机制。

21. FAQ

Q1：/goal 和普通 Prompt 最大区别是什么？

普通 Prompt 更像一次性请求。 /goal 更像任务合约。

普通 Prompt 适合简单问题。 /goal 适合需要持续推进、验证、记录和收敛的复杂任务。

Q2：是不是所有任务都应该用 /goal？

不是。

小任务用 Prompt 更快。

例如：

解释一段代码；
改一个文案；
写一个小函数；
查询一个命令；
做一次简单判断。

复杂任务才适合 /goal。

Q3：一个好的 Goal 最重要的部分是什么？

不是“目标写得多宏大”，而是“完成标准写得清楚”。

一个强 Goal 必须写清楚：

什么算完成；
怎么验证完成；
不能破坏什么；
允许改哪里；
什么时候停止；
未覆盖项怎么报告。

Q4：AGENTS.md 应该一开始就写很长吗？

不应该。

AGENTS.md 最好从 20-50 行开始，只写最关键的项目规则。

然后根据 Codex 实际犯错情况慢慢补充。

原则是：

重复提醒两次以上的规则，才值得写进 AGENTS.md。

Q5：Skill 和 Goal 有什么区别？

Goal 是一次任务的目标合约。

Skill 是一类任务的复用流程。

例如：

这一次你让 Codex 生成产品说明文档，这是 Goal。你把“运行项目、截图、梳理功能、撰写文档、列出未覆盖项”沉淀成固定流程，这就是 Skill。

Q6：GEO 为什么要放进 Codex / Goal Playbook？

因为内容站未来不只是写给人看，也会被 AI 搜索、摘要和推荐系统读取。

对 ReelOS.ai 这样的知识型网站来说，文章需要同时满足两类读者：

人类读者：希望快速理解、直接使用；
AI 系统：需要清晰结构、定义、引用、FAQ、模板和证据。

所以 GEO 很适合用 /goal 来做。

Q7：使用 Codex 最大的风险是什么？

不是它不会做，而是它做过头。

常见风险包括：

改动范围扩大；
删除测试；
绕过错误；
引入不必要依赖；
修改无关模块；
自己宣布完成；
跳过难验证的页面或功能。

解决方法就是：

写清目标、边界、验证、停止条件和未覆盖项检查。

22. 最后：真正会用 Codex 的人，不是会写 Prompt 的人

未来使用 Codex 的关键能力，不是“会不会写神级 Prompt”。

而是这四种能力：

第一，能把模糊需求转成明确目标。第二，能定义什么叫完成。第三，能设置边界，防止 AI 过度发挥。第四，能用证据验证结果，而不是相信总结。

一句话总结：

Prompt 是沟通，Goal 是合约，AGENTS.md 是规则，Skill 是复用，Eval 是长期稳定性。

Codex / Goal 的真正价值，不是让 AI 帮你写几行代码，而是让 AI 围绕一个可验证目标持续推进工作。

这才是 AI 编程从“工具”走向“执行系统”的关键一步。

参考资料

OpenAI Cookbook：Using Goals in Codex
OpenAI Codex Use Cases：Follow a goal
OpenAI Codex Docs：Custom instructions with AGENTS.md
OpenAI Codex Docs：Best practices
OpenAI Codex Docs：Agent Skills
GEO: Generative Engine Optimization
AgenticGEO: A Self-Evolving Agentic System for GEO
From Experience to Skill: Multi-Agent Generative Engine Optimization via Reusable Strategy Learning