第 10 章 | 用 `/opsx:propose` 提出变更 — 用 Claude Code + OpenSpec + 多角色 Agent 开发软件项目

第 10 章：用 `/opsx:propose` 提出变更

学习目标

跑一次 /opsx:propose，得到完整的 4 件套：proposal / design / specs / tasks。

命令背后发生什么

sequenceDiagram
    participant You
    participant MC as main Claude
    participant CLI as openspec CLI
    participant FS as 文件系统

    You->>MC: /opsx:propose 我要做 doc2video
    MC->>You: AskUserQuestion: 描述清楚一点？
    You->>MC: ...详细描述...
    MC->>CLI: openspec new change add-doc2video
    CLI->>FS: 建空骨架 changes/add-doc2video/
    MC->>CLI: openspec status --json
    CLI->>MC: 列出待生成工件 + 依赖
    loop 按依赖顺序
        MC->>CLI: openspec instructions 
        CLI->>MC: 模板 + 规则
        MC->>FS: 写 proposal.md / design.md / spec.md / tasks.md
    end
    MC->>You: 4 件套就绪

实战：跑一次

# 在 Claude Code 里
/opsx:propose 把 markdown 教学文档编译成视频，含配音、字幕、真实终端操作

main Claude 会问你 1~2 个澄清问题，然后开始批量生成。最终目录长这样：

openspec/changes/add-doc2video/
├── proposal.md           ~30 行：why + what + capabilities + impact
├── design.md             ~120 行：9 条决策 + risks
├── specs/
│   └── doc2video/
│       └── spec.md       ~150 行：11 个 Requirement + 30+ Scenario
└── tasks.md              ~80 行：13 个组、61 条 task

4 个工件的依赖

flowchart LR
    P[proposal.md] --> D[design.md]
    P --> S[specs/]
    D --> T[tasks.md]
    S --> T

    style P fill:#bbdefb
    style D fill:#c5e1a5
    style S fill:#ffe0b2
    style T fill:#f8bbd0

为什么这个顺序：

proposal 先：决定"做什么 + 为什么"
design 和 specs 并列：design 写"怎么做"，specs 写"做完是什么样"
tasks 最后：依赖前面三个才能拆出准确任务

proposal.md 解剖

打开看看：

## Why
（一句话痛点 + 为什么现在做）

## What Changes
- 新增什么
- 修改什么
- 删除什么（标 BREAKING）

## Capabilities
### New Capabilities
- `doc2video`: 一句话描述这个能力

### Modified Capabilities
（无 / 列出来）

## Impact
（影响哪些代码、依赖、外部系统）

→ 1~2 页就够。不写"如何"——那是 design 的事。

命令的关键 flag

flag	含义
`openspec new change <name>`	只建空骨架（不生成内容）
`openspec status --change <name> --json`	看哪些工件该生成、依赖关系
`openspec instructions <id> --change <name>`	拿模板和规则

main Claude 跑 /opsx:propose 时按顺序调这三个，你不需要直接调。

检查产出

跑 /opsx:propose 后立即跑：

openspec status --change add-doc2video

期望看到：

Progress: 4/4 artifacts complete

[x] proposal
[x] design
[x] specs
[x] tasks

All artifacts complete!

如果是 3/4 或更少，说明某个工件没生成成功——查 main Claude 的输出。

一个常见的"翻车"现场

你: /opsx:propose 加搜索功能
   ↓
main Claude 写了 proposal "Add search functionality"
   ↓
design.md 才发现你说的"搜索"是全文检索还是数据库 LIKE？
   ↓
spec 写得似是而非

→ 要么先 explore 澄清，要么 propose 时把意图说全。propose 可以提示不清楚的地方让你补充，但它不会替你想清楚。

不要做的事

✗ 跑完 propose 后立刻 /opsx:apply
   先读一遍 4 个文件，确认意图被准确捕捉了

✗ 跳过 design.md
   只有 proposal + spec + tasks，决策无处记录，半年后没人记得为什么这么做

✗ 把 implementation 细节塞进 proposal.md
   proposal 是 why，不是 how

你现在能做什么

跑出完整的 4 件套
读懂每个文件的角色
在跑之前判断"该 explore 还是该 propose"

flowchart LR
    Start["第 1 章
开始"] --> Setup["第 4~6 章
环境就绪"]
    Setup --> Mental["第 1~3 章
心智模型"]
    Mental --> First["第 7~10 章
第一个 change"]

    First --> You["✓ 跑出完整 4 件套
✓ 看懂每个文件
✓ 知道下一步是什么"]

    style You fill:#c8e6c9

核心检查点：现在你应该已经在自己机器上跑出了一份你自己想做的项目的 openspec/changes/<your-name>/，里面 4 个文件齐全。

如果还没——回到第 8 章重做一次，这是后续所有章节的基础。

第 10 章 | 用 `/opsx:propose` 提出变更

第 10 章：用 /opsx:propose 提出变更