Spec-First

Plan 详细指南 ​

Claude Code 使用 /spec:plan，Codex 使用 $spec-plan。契约见 spec-plan。

Plan 把需求文档变成 可执行计划。它回答的不是“做什么”，而是“准备怎么做、改哪里、怎么验证”。

输入与输出 ​

  • 输入：需求文档，或已经足够清晰的目标
  • 输出：docs/plans/*.md

一份合格的计划，通常应包含：

  • 文件范围
  • 风险与边界
  • Implementation Units
  • 验证方式
  • 可能延后到实施阶段解决的问题

Plan 不负责什么 ​

  • 不在这里写代码
  • 不把运行时试错当作规划
  • 不把实现细节提前塞进需求文档

如果某个问题只能通过改代码和跑测试来确定，它就属于 Work。

使用方式 ​

Claude Code：

bash
/spec:plan docs/brainstorms/2026-04-20-example-requirements.md

Codex：

bash
$spec-plan docs/brainstorms/2026-04-20-example-requirements.md

执行逻辑图 ​

text
用户运行 /spec:plan 或 $spec-plan
  |
  v
读取 requirements、repo facts、graph status、confirmed standards、相关源码路径
  |
  v
确认 scope boundaries、非目标、目标 repo / module
  |
  v
拆分 Implementation Units 和依赖顺序
  |
  v
标注风险、测试场景、验证方式、deferred unknowns
  |
  v
输出 docs/plans/*-plan.md
  |
  +-- 计划较大
  |     |
  |     v
  |   交给 spec-write-tasks 编译 task pack
  |
  +-- 计划足够小
        |
        v
      直接交给 spec-work 执行

计划应该解决哪些问题 ​

一份有价值的 Plan 至少应让后续 Work 能回答：

  • 改动边界在哪里
  • 哪些文件属于当前任务
  • 哪些是非目标
  • 先做什么，后做什么
  • 如何验证完成

与 Work 的边界 ​

Plan ​

  • 决策
  • 拆解
  • 风险识别
  • 验证设计

Work ​

  • 真实改动代码
  • 真实跑验证
  • 在边界内完成交付

当前更准确的理解 ​

Plan 不是“写得越长越好”的设计文档。

它更接近一个执行前决策工件，用来降低：

  • 范围蔓延
  • 中途返工
  • 计划与实现脱节

下一步 ​