| name | easy-codex-spec |
| description | 当用户希望在实现前澄清需求、编写规格说明、设计说明或需求文档,定义范围、非目标、验收标准、验证计划和风险,或任务模糊且直接实现容易跑偏时使用。 |
Easy Codex 规格说明
把模糊或高风险任务写成可实现、可验证的规格。除创建/选择工作树外,只改规格文档。
用户选择
- “选择功能”指:可点击选择可用时必须用控件;工具不可用时用文本降级,给每个选项编号,列 2-3 个互斥选项,推荐项第一,要求用户回复编号数字、完整选项名或
其他: <自定义>;开放答案用“其他”,并允许用户直接输入自定义内容;禁止要求用户输入关键词或技能名。
强制门禁
从规格阶段开始必须使用 git worktree。工作树必须位于主项目根目录 worktrees/<name>;禁止在 main worktree 写入项目文件。设计未获批准前,禁止实现、改源文件、改测试或脚手架。必须用 sub-agent 审核规格;没有子代理能力则停止。规格完成、审核处理并经用户批准后,才能进入 $easy-codex-writing-plans。
工作树门禁
- 先用
git rev-parse --show-toplevel 和 git worktree list --porcelain 找主项目根目录。
- 根据用户需求推荐 2-3 个安全的 worktree name,用选择功能让用户选;同时提供“其他”输入入口。
- worktree name 必须匹配
^[a-z0-9][a-z0-9._-]{0,63}$;拒绝 /、..、绝对路径和空白。
- 先 canonicalize
<主项目根>;mkdir -p <主项目根>/worktrees 是 main worktree 唯一允许的管理写入;再 canonicalize worktrees 父目录。
- 目标不存在时先用
git worktree add <主项目根>/worktrees/<name> 创建专用分支;创建后再 realpath 目标,确认仍在 <主项目根>/worktrees/ 下。
- 目标已存在且是已注册 git worktree:展示
git status --short,用选择功能确认复用、换名或停止;脏 worktree 必须明确选择继续、换名或停止。
- 目标已存在但不是已注册 git worktree:阻塞,用选择功能选择换名或停止。
基准 必须在创建/复用 worktree 时立即写入 main worktree 当前 HEAD SHA,后续只能继承,禁止执行后补写或改写。
- 创建后切到该 worktree 写
docs/specs/;main worktree 除 worktree 管理命令和创建 worktrees/ 父目录外,不改项目文件。
路由
- 用:规格/设计/需求/验收;范围不清;影响多文件、接口、流程、数据。
- 不用:执行已批准且审核已处理的计划 ->
$easy-codex-executing-plans;审查 -> $easy-codex-review;交付 -> $easy-codex-ship。
工作流
git status --short。
- 推荐并选择 worktree name,创建/切换到绝对 worktree 路径。
- 在选定 worktree 读相关代码、测试、README、文档、配置;事实自己查。
- 一问一答澄清,只问最高影响问题;有限候选答案必须用选择功能。
- 清楚后提出 2-3 个方案、取舍、推荐方案。
- 展示设计摘要,用选择功能获批:批准设计、调整设计、停止规格。
- 评估规格规模和预计计划阶段数;规模过大、跨多子系统或预计需要很多阶段时,先建议拆分规格,从最小可交付项开始。
- 写到
docs/specs/YYYY-MM-DD-<slug>.md。
- 自检修正:占位符、矛盾、歧义、范围过大、不可测试验收。
- 派子代理审核;按“审核规则”处理。
- 汇报 worktree、路径、假设、开放问题、审核结论;用选择功能请求下一步:进入实现计划、继续修改规格、停止。
文档格式
# <任务名称> 规格说明
## 背景
- 问题:
- 事实:
## 工作树
- 主项目根:
- 绝对 worktree 路径:
- 显示路径:`worktrees/<name>`
- 分支:
- 基准:`<main HEAD SHA>`
## 流程状态
- 规格状态:草稿
- 规格批准记录:未批准
- 审核状态:未审核
- 下一阶段许可:未许可
## 目标
-
## 非目标
-
## 范围
- 包含:
- 不包含:
## 方案
- 推荐方案:
- 备选方案 1:
- 备选方案 2:
- 取舍:
## 影响面
- 文件/模块:
- 接口/数据契约:
- 兼容性:
## 验收标准
- [ ] 标准 1
- [ ] 标准 2
## 验证计划
- 自动化验证:
- 手工验证:
- 不验证项及原因:
## 风险与缓解
- 风险:
- 缓解:
## 开放问题
- [ ] 问题 / 影响 / 假设
## 对抗性审核
- 审核者:
- 结论:
- 已修正问题:
- 剩余风险:
- 用户处理决定:
规则
- 规格阶段只在选定 worktree 内改规格文档;不改源文件、测试、配置或脚手架。
- 已有相关规格说明时优先更新,不重复创建。
- 会改变实现方向的问题先用选择功能决策;开放问题不能替代关键验收。
- 默认假设要标明错误影响。
- 验收标准必须可测试或可人工明确判断。
- 规格审核只保证目标、边界、验收和验证足以进入计划;不要把规格审成完整设计。
- 规格过大或预计实现计划会拆出很多阶段时,必须建议拆分规格;用选择功能提供:拆分规格、保留单规格、停止。
- 派审前先按自检清单补齐常见缺口:必填字段、流程状态、目标/范围/验收/验证映射、风险、开放问题、占位符、路径和命名一致性。
- 格式、字段、明显缺漏由控制器自动修正后再派审;只有影响设计方向、范围或验收的问题才询问用户。
- 规格阶段的子代理只用于规格文档审核/修正,不是
$easy-codex-executing-plans 的写代码实现子代理;不得跨阶段保留或复用。
- 选择进入实现计划前,必须把
规格状态 更新为已批准,把 规格批准记录 写入用户批准时间/方式,把 审核状态 写为通过或风险已接受,把 下一阶段许可 写为允许进入 $easy-codex-writing-plans;否则 $easy-codex-writing-plans 必须阻塞。
审核规则
自检后派新子代理审查。只给规格路径和背景,不给预期答案。规格审核子代理用完就关闭:返回后读完结果必须立即 close_agent;重审派新子代理。
要求子代理先判断规格能否落地:目标、非目标、范围、验收、验证、风险和方案比较是否足以进入计划。默认不阻塞,举证才阻塞;未发现明确阻塞问题时,结论必须为 通过;建议只能进入非阻塞建议。
只有以下问题才算阻塞:
- 会导致两个合理实现产生不同的用户可见行为、数据结果或 API 契约。
- 验收标准无法判断通过/失败。
- 违反明确流程门禁:worktree、基准、批准状态、下一阶段许可。
- 存在具体且不可逆的数据破坏、迁移失败、兼容破坏或安全风险,且规格未给处理边界。
- 存在实现前必须由用户决策的产品/范围问题。
以下不得算阻塞:
- 只是希望补更多背景、细节或示例。
- 可在实现计划阶段自然拆解的技术步骤。
- 可通过默认假设推进,且假设错误影响已写明。
- 非关键边界条件、低概率异常、风格偏好。
- reviewer 无法指出具体失败模式的问题。
阻塞问题必须说明:如果不修正,会导致什么具体错误实现或无法验收。不能说明具体失败模式时,降级为非阻塞建议。非阻塞建议不得阻止进入下一阶段。
子代理输出必须包含:
通过 或 需要修改
- 阻塞问题:每项含影响、明确建议、2-3 个备选处理方案、推荐选择
- 非阻塞建议:每项含收益、代价、可忽略条件
- 最小修正方向:指出规格章节
只有明确阻塞问题才允许输出 需要修改。若 需要修改,先分类处理:格式、字段、明显缺漏由控制器自动修正;真正阻塞问题才展示并请求选择。每个阻塞问题带建议、2-3 个备选方案、推荐选择,再用选择功能询问:
- 选择
再审一轮:按用户确认方向更新规格,再派新子代理审核。
- 选择
接受现状:把用户接受的剩余风险写入 对抗性审核,继续请求规格批准。
- 选择
完全拒绝:停止,不进入 $easy-codex-writing-plans、实现或 review。
同时提供“其他”输入入口;若用户自定义内容改变设计、范围或验收标准,更新规格说明并重新审核。