项目说明书
把商业想法变成 Codex 可理解的项目地基。
包含字段
- 项目目标
- 用户与场景
- 核心流程
- 非目标
- 商业指标
- 技术约束
- 第一版范围
例子
我们要做一个团队任务板，第一版只支持团队内创建任务、分配负责人、按状态流转，不做聊天和移动 App。
Templates
模板库
模板把抽象能力落成可执行文档，让小白也能给 Codex 清楚的施工图。
Codex 任务卡
把一个可执行任务交给 Codex。
包含字段
- 背景
- 目标
- 涉及文件
- 非目标
- 风险概念
- 执行步骤
- 验收标准
- 测试命令
例子
只实现任务状态流转，不改登录系统；必须检查非法状态转换和权限。
完成定义模板
开始实现前锁定什么叫完成。
包含字段
- 用户可见结果
- 正常路径
- 异常路径
- 权限路径
- 性能要求
- 测试证据
- 未覆盖风险
例子
普通成员只能修改自己负责的任务；管理员可修改所有任务；非法跳转返回错误提示。
技术风险清单
商业功能实现前，提醒 Codex 检查深层工程风险。
包含字段
- 幂等
- 事务
- 并发
- 状态机
- 权限
- 回滚
- 监控
- 性能预算
- 数据迁移
例子
退款请求必须幂等，支付状态更新必须有事务保护，重复回调不能重复退款。
工具接口设计模板
给 AI 或系统设计可调用工具。
包含字段
- 工具用途
- 参数 schema
- 权限
- 副作用
- 幂等键
- 错误码
- 审计日志
- 禁止事项
例子
createRefundRequest 只能创建退款申请，不能直接改余额；重复 idempotencyKey 返回原记录。
状态机设计模板
对象有多个状态和流转规则时。
包含字段
- 状态列表
- 触发事件
- 合法转换
- 非法转换
- 权限
- 审计
- 失败回退
例子
Task: todo -> doing -> review -> done；done 不能回到 todo，除非管理员 reopen。
Bug 复现报告
让 Codex 有足够上下文修 Bug。
包含字段
- 现象
- 期望
- 复现步骤
- 环境
- 日志/截图
- 最近变更
- 影响范围
例子
普通用户刷新任务详情后出现 403；创建者本人也无法访问；日志显示 ownerId 为空。
Trace / Replay 记录模板
AI workflow 或复杂接口需要可解释、可回放。
包含字段
- 请求 ID
- 输入
- 模型/版本
- 上下文
- 工具调用
- 状态变化
- 输出
- 验收结果
例子
保存本次检索到的文档片段、工具返回和最终判断，便于回放错误结果。
发布与回滚检查表
上线商业功能前。
包含字段
- 发布内容
- 迁移
- 备份
- 监控
- 告警
- 回滚命令
- 验证步骤
- 负责人
例子
发布任务状态机前先备份任务表；错误率超过阈值时回滚旧 Worker 版本。