easy-codex-spec

# 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`。 ## 工作流 1. `git status --short`。 2. 推荐并选择 worktree name，创建/切换到绝对 worktree 路径。 3. 在选定 worktree 读相关代码、测试、README、文档、配置；事实自己查。 4. 一问一答澄清，只问最高影响问题；有限候选答案必须用选择功能。 5. 清楚后提出 2-3 个方案、取舍、推荐方案。 6. 展示设计摘要，用选择功能获批：批准设计、调整设计、停止规格。 7. 评估规格规模和预计计划阶段数；规模过大、跨多子系统或预计需要很多阶段时，先建议拆分规格，从最小可交付项开始。 8. 写到 `docs/specs/YYYY-MM-DD-<slug>.md`。 9. 自检修正：占位符、矛盾、歧义、范围过大、不可测试验收。 10. 派子代理审核；按“审核规则”处理。 11. 汇报 worktree、路径、假设、开放问题、审核结论；用选择功能请求下一步：进入实现计划、继续修改规格、停止。 ## 文档格式 ```markdown # <任务名称> 规格说明 ## 背景 - 问题： - 事实： ## 工作树 - 主项目根： - 绝对 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。 同时提供“其他”输入入口；若用户自定义内容改变设计、范围或验收标准，更新规格说明并重新审核。