Codex 软件开发人类使用手册与最佳实践

你不是提示词操作者，而是产品 Owner、设计裁判和验收人。Codex 负责文档、代码、测试和交付证据，你负责目标、场景、取舍和真实体验判断。

基本原则

不从代码开始 先明确目标、用户、范围、非目标和完成标准，再进入设计和实现。

不依赖人类记忆 Codex 必须在软件开发任务开始时提醒你进入 SOP，涉及前端时进入 Frontend Design Gate。

前端是使用习惯 好前端不只是漂亮，还要顺手、可恢复、可维护、状态完整。

你每次要提供什么

每次启动项目或任务，尽量提供六点：

我要做什么。
给谁用。
用户最重要的操作路径。
参考什么产品或网站。
不要什么风格或功能。
我如何判断完成。

请按 AI Coding SOP 执行。

我要做：[任务]
给谁用：[用户]
最重要的操作路径是：[步骤]
参考：[产品/网站]
不要：[反例]
完成标准：[验收]

先判断任务等级和裁剪范围。
涉及前端时先执行 Frontend Design Gate。
完成后给测试结果、截图 QA 和交付总结。

协作流程

阶段	你看什么	Codex 做什么
任务启动	目标、用户、边界是否清楚	判断 L0-L4、裁剪范围、必需文档
PRD	场景、范围、验收标准是否正确	写 PRD 和非目标
系统设计	是否过度复杂，边界是否清楚	写模块、数据、接口、风险
前端设计	页面类型、用户路径、信息层级是否合理	执行 Frontend Design Gate
实现	方向是否被执行	写代码、复用组件、运行测试
交付	证据是否足够，体验是否通过	给测试结果、截图 QA、风险总结

前端检查

后台 / 管理工具 / SaaS

优先任务效率、信息密度、状态完整和长期维护。不要大 hero、渐变装饰、卡片套卡片。

推荐说法：这是后台 / SaaS 页面。优先表格、筛选、详情抽屉、状态标签和清晰反馈。

官网 / Landing Page / 品牌展示

优先第一屏信任、品牌信号、真实视觉资产、CTA、叙事节奏和信任证据。

推荐说法：这是高视觉要求页面。请先判断是否需要 Design-Agent + Codex。

工具型应用

优先操作路径短、默认状态清楚、错误可恢复、高频功能易触达。

什么时候使用 Design Agent

默认仍然采用 Codex-only。但官网、Landing Page、品牌展示、产品发布页，或视觉风格影响转化和信任时，应让 Codex 判断是否切换。

Design Agent 交付设计方案，Codex 负责生产代码、测试、截图 QA 和交付。

这是高视觉要求页面。
请先判断是否需要 Design-Agent + Codex。
如果需要，请列出设计 Agent 必须交付的内容，不要直接写代码。

验收方式

不要只接受“已完成”。你应该要求 Codex 给出证据：

改了什么。
为什么这样改。
运行了哪些测试。
哪些测试没跑，原因是什么。
如果涉及前端，桌面和移动端截图 QA 结果是什么。
还有哪些风险。

构建通过不代表前端完成。涉及 UI 的任务必须看截图和 visual-qa-report。

常见错误和纠偏

错误说法 / 现象	更好的纠偏
做得高级一点	参考 Linear / Stripe Dashboard，信息密度高一点，主操作清楚，不要大面积装饰。
Codex 直接写代码	停止实现，回到 SOP，先补任务等级、裁剪决策和开发计划。
后台页面像官网	这是管理工具，减少 hero、卡片和装饰，改成表格、筛选、详情抽屉和状态标签。
官网页面像模板	重新定义首屏：产品名、价值主张、真实视觉资产、主 CTA 和信任证据。

每次软件开发任务提醒

Codex 在识别到软件开发任务时，必须先提醒：

这是软件开发任务。我会先按 AI Coding SOP 判断任务等级、裁剪范围和必需文档，不会直接写代码。

如果涉及前端，必须继续提醒：

这涉及前端。我会先执行 Frontend Design Gate，明确页面类型、用户路径、信息层级、组件状态、响应式规则、禁止风格和截图 QA 标准。

这类提醒不适合做成定时任务。最稳的方式是写进项目 AGENTS.md 和 SOP 启动检查。

最小使用方式

请按 AI Coding SOP 执行。
我要做：[任务]
给谁用：[用户]
最重要的操作路径是：[步骤]
参考：[产品/网站]
不要：[反例]
完成标准：[验收]

先判断任务等级和裁剪范围。
涉及前端时先执行 Frontend Design Gate。
完成后给测试结果、截图 QA 和交付总结。