Plan

/plan — 从 Spec 自动生成 plan.json

语言: English | 简体中文

用法

/plan <spec-file.md>              # Spec 模式（自有格式 / SpecKit）
/plan <openspec-change-dir/>      # OpenSpec 模式
/plan "需求描述文本"               # 需求模式
/plan                             # 交互模式（自动检测）

执行流程

Step 1：输入识别与格式检测

根据参数类型判断使用模式：

参数是 .md 文件：

1. 读取文件内容
2. 检测格式：
   • 含 ## Requirements 且 ## Technical Design → 自有格式（SPEC-NNN-*.md）
   • 含 ## Summary 且 ## Detailed Design → SpecKit 格式
   • 其他 .md → 尝试解析为通用 Spec（按自有格式处理，缺少的字段由 AI 补充）

参数是目录：

1. 检查是否含 proposal.md + tasks.md → OpenSpec 格式
2. 否则报错：「此目录不符合 OpenSpec 结构」

参数是字符串描述（非文件路径）： → 需求模式

无参数： → 交互模式

1. 检测 openspec/ 目录存在？ → 列出 changes 让用户选择
2. 检测 specs/*.md 存在？ → 列出可用 Spec 让用户选择
3. 都没有 → 进入需求模式问答

Step 2：项目 Context 收集

读取目标项目的关键信息：

1. CLAUDE.md / AGENTS.md — 语言、框架、测试工具、开发规范
2. package.json / pyproject.toml — 可用 scripts（build, test, lint）

从 Context 推断：

• 主要语言（TypeScript / Python / 其他）
• 默认 verify_command（如 pnpm build && pnpm test、pytest -x）
• 默认 lint_command（如 pnpm lint、ruff check .）

Step 3：Spec 解析

依检测到的格式，解析 Spec 内容：

自有格式（SPEC-NNN-*.md）

提取以下区段：

• Summary / Motivation → 理解背景与需求动机
• Requirements (REQ-NNN) → 功能需求列表
• Acceptance Criteria (AC-N) → Given/When/Then 验收条件
• Technical Design → Phase 分层、每个 Phase 的实现项目
• Test Plan → 测试清单
• Risks → 风险评估

OpenSpec（change 目录）

读取以下文件：

• proposal.md → Why（动机）、What Changes（变更项目）、Impact
• tasks.md → - [ ] checklist 项目
• design.md（若存在）→ 技术决策
• specs/*/spec.md（若存在）→ Requirements（SHALL / MUST 语句）、Scenarios

SpecKit（SPEC-ID.md）

提取以下区段：

• Summary / Motivation → 背景
• Detailed Design → 技术实现步骤
• Acceptance Criteria → checkbox 验收条件
• Dependencies → 外部依赖
• Risks → 风险

Step 4：Task 切分

依格式套用不同映射规则：

自有格式映射规则

OpenSpec 映射规则

Step 5：依赖推断

为 tasks 建立 depends_on 关系：

1. Phase / Stage 顺序：后面的 Phase 的第一个 task depends_on 前面 Phase 的最后一个 task
2. 同 Phase 内顺序：类型定义 → 实现 → 集成 → 测试
3. 文件依赖：A 创建的文件被 B import → B depends_on A
4. 无依赖的 tasks：depends_on: []（可并行）

Step 6：verify_command 推断

依以下优先顺序推断：

1. Test Plan / Scenarios 有明确测试项 → 对应测试命令
2. TypeScript 项目 → pnpm build && pnpm test
3. Python 项目 → pytest -x
4. 其他 → 使用 Step 2 收集的项目 scripts
5. 无法推断 → 不设（后续质量警告会提醒）

Step 7：质量设置

• 默认 quality: "standard"
• 用户可在交互确认时调整

Step 8：组装 plan.json

{
  "project": "<项目名称>",
  "quality": "standard",
  "defaults": {
    "max_turns": 30,
    "max_budget_usd": 2.0,
    "verify_command": "<推断的默认验证命令>"
  },
  "tasks": [
    {
      "id": "T-001",
      "title": "<task 标题>",
      "spec": "<详细的 task 规格说明>",
      "depends_on": [],
      "verify_command": "<task 层级验证命令（可选）>",
      "acceptance_criteria": ["<验收条件 1>"],
      "user_intent": "<用户意图>"
    }
  ]
}

注意事项：

• Task ID 格式：T-NNN（如 T-001, T-002）
• spec 字段应详尽——它是 agent 执行任务的唯一规格输入
• acceptance_criteria 每条都必须是可观察、可验证的

Step 9：验证（Claude-native）

Claude 对 plan.json 执行以下验证（无需外部引擎）：

1. 结构验证：tasks 数组存在且非空、每个 task 含必填字段（id, title, spec）
2. DAG 合法性：depends_on 中的所有 ID 均存在、无循环依赖
3. 安全扫描：task.spec 不含危险命令（rm -rf /、DROP DATABASE、git push --force）
4. 质量警告：task 缺少 verify_command、spec 过短（< 20 字）等

若发现问题，在呈现前先自动修正（若可修正）或标示警告。

Step 10：呈现与确认

向用户呈现生成结果：

1. 摘要表格：

   | Task ID | 标题 | 依赖 | 验证命令 |
   |---------|------|------|----------|
   | T-001   | ...  | -    | ...      |
   | T-002   | ...  | T-001| ...      |
   

2. DAG 拓扑：

   Layer 0: T-001, T-002（并行）
   Layer 1: T-003（依赖 T-001）
   Layer 2: T-004（依赖 T-002, T-003）
   

3. 质量设置：quality: standard

4. 质量警告（若有）

5. 询问用户：确认或修改？确认后写入文件（默认路径：plans/<spec-name>.plan.json）

版本历程