# Brainstorming ↔ Openspec 映射指南(B-2) > 编制:2026-09-28 · 配合 learnings §B-2 > 状态:host-side 文档;给"同时激活 brainstorming + openspec"的场景用 --- ## 1. 背景 两个 skill 看起来重叠: - **brainstorming**(superskills):设计阶段产出 `docs/superpowers/specs/YYYY-MM-DD--design.md` - **ai-collab-framework**(openspec):每个 chg 产出 proposal/spec/tasks/testcases/map.yaml 五件套 实际分工: | skill | 阶段 | 产出 | |---|---|---| | brainstorming | **变更前**(跨多个 chg 的整体设计) | `design.md`(一份) | | ai-collab-framework | **每个 chg**(具体行为的 openspec 工件) | 五件套(一份/每个 chg) | ## 2. 调用顺序(必须) ``` Phase 1: brainstorming 跑 → design.md 写好 → 用户 review ↓ 批准 Phase 2: design.md 拆解成 N 个 chg,每个写 openspec 五件套 ↓ Phase 3: 每个 chg 走 xstudio-sandbox-dispatch 派单 ``` **关键**:brainstorming 的 design doc 不替代 chg 工件;design doc 是"前置设计 spec",chg 工件是"具体执行的 contract"。 ## 3. design.md → chg 工件的映射表 | design.md 段落 | chg 工件字段 | 说明 | |---|---|---| | `# Spec: ` 标题行 | spec.md `# Spec:` 标题 + map.yaml `# spec: @` | capability 名必须一致,chg_id 必须对应目录 basename | | `## Requirement` EARS 句式 | spec.md `## Requirement` 段 | 复制保留 + 改写为 capability 级 EARS | | `## ADDED Scenarios` (`### S`) | spec.md `## ADDED Scenarios` | capability 级全局 S 编号,跨 chg 连续 | | `## MODIFIED Scenarios` | spec.md `## MODIFIED Scenarios` | **整块从 openspec/specs//spec.md 拷贝**再改(modality,modifies 是完整替换) | | `## REMOVED Scenarios` | spec.md `## REMOVED Scenarios` | 含 `**Reason**` + `**Migration**` 两行 | | `## Why` + `## Who` + `## Scope` + `## Non-Goals` + `## Acceptance` | proposal.md 同名段 | 改写为 chg 级(带 change_id frontmatter) | | `## Impact` | proposal.md `## Impact` | 影响 capability 名(应一致) | | 隐含的"任务列表"(脑图) | tasks.md `# Tasks (DAG)` | 把脑图转 YAML 节点(id / type / depends_on / output / verification) | | `## UX / Interaction` | spec.md 同名段 | UI 类变更才需要,非 UI 不写 | | 隐含的"每个 scenario 对应一个 case" | testcases.md `### C_` | one-to-many 也行(map.yaml 显式声明) | ## 4. 命名约定(避免冲突) ### 4.1 capability 级 S 编号 - capability 在 `openspec/specs//spec.md` 主 spec 已有 → 新 chg 接续最大号 - capability 是新的 → 从 S1 起 - **新 chg 用 delta 段**(`## ADDED/MODIFIED/REMOVED Scenarios`),非 delta 写法(`## Concrete Scenarios`)会有迁移提示 ### 4.2 chg_id 格式:`chg_NNNN__` - NNNN:四位数字,按 archive 一起扫(不重用) - capability-scope:与 capability 名一致 - change-slug:动词/名词短语(kebab-case) 例:`chg_0003_dispatch_helpers`、`chg_0004_experiment_platform_frontend` ### 4.3 capability 名 - 单一 capability:``(如 `experiment_platform`) - 跨 capability 复合 chg:拆成多个 chg,不要硬塞进一个 ## 5. testcases 命名约定 格式:`C<数字>_`(`C1_list_default`) - 每个 scenario 至少 1 条 case(map.yaml 显式声明) - one-to-many OK:`S4 → [C4_no_token_600, C7_perm_smoke_passes]` - 数字连续,从 1 起 - 跨 chg 不重用(避免追溯混淆) ## 6. 模板速查(chg 工件最小集) ### proposal.md 最小 frontmatter ```yaml --- change_id: chg_NNNN status: proposed owner: pm@team stakeholders: [pd, tm, qa, dev] priority: P1 target_release: v0.X created: YYYY-MM-DD skip_coverage: false # 纯 refactor 设 true --- ``` ### spec.md 最小结构 ```markdown # Spec: ## Requirement WHEN THE SYSTEM SHALL 。 ## ADDED Scenarios ### S <场景名> - **WHEN** <触发动作> - **AND** <前置条件> - **THEN** <可观测结果> ## UX / Interaction(UI 类才填) - 原型位置:... - 交互决策:... ``` ### tasks.md 最小结构 ```markdown # Tasks (DAG) - id: T1 type: architect | implementer | tester | qa depends_on: [] output: verification: ``` ### testcases.md 最小结构 ```markdown ### C_ - Scenario: S - Type: unit | integration | e2e | ux - Priority: P0 | P1 | P2 - Given: ... - When: ... - Then: ... - Automated: true | false - Bound Task: T # 必须在 tasks.md 真实存在 ``` ### testcases.map.yaml 最小结构 ```yaml # spec: @ scenarios: - id: S1 cases: [C1_, C2_] gate: blocking_gap_tolerance: 0 implementation_files: - src// test_files: - tests// ``` ## 7. 流程清单(chg 创建) ``` □ 1. 读 design.md,按"## ADDED Scenarios"分 chg(每 chg 一个 delta 段) □ 2. mkdir -p openspec/changes/chg__ □ 3. cp templates/{proposal,spec,tasks,testcases,testcases.map.yaml}.md chg__/ □ 4. 改 frontmatter: - change_id: chg_ - skip_coverage: true(纯基础设施/无行为变更) □ 5. 写 spec.md:# Spec: + delta 段 □ 6. 写 tasks.md:T1=architect, T2=implementer, T3=tester (T 编号 capability 内唯一) □ 7. 写 testcases.md:Bound Task 必须真实存在 □ 8. 写 testcases.map.yaml:scenario ↔ case 绑定 □ 9. 写 proposal.md:why/scope/acceptance □ 10. 跑门禁:PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh - PASS → 可 dispatch - FAIL → 修工件 ``` ## 8. 与 superskills `using-superpowers` 的冲突解决 brainstorming skill 要求"设计 doc 写好后等用户批准才能 writing-plans"。 openspec 的 chg 工件是 ai-collab-framework 自带的 deliverable,不经过 superskills writing-plans。 **冲突解决**(已写在 learnings §B-3): - 同时激活 brainstorming + openspec → 以 **openspec 工件** 为权威 approval artifact - brainstorming 的 design doc 作为前置 spec 即可(用户批准 design.md 即视为批准 openspec chg) - 不需要 writing-plans skill ## 9. 验证 checklist - [x] design.md 写好 → commit `3f5f32f` - [x] chg_0003/0004/0005 用本流程走通 - [x] check_spec_coverage.sh gap=0 - [ ] dispatch skill 文档同步更新(待 user 决策) ## 10. 相关文件 - `docs/superpowers/learnings/2026-09-28-dispatch-session.md` §B-2 / §B-3 - `docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md`(design doc 范例) - `openspec/scripts/check_spec_coverage.sh` — 门禁脚本 - `~/.claude/skills/ai-collab-framework/SKILL.md` §5/§6/§7/§8 — 6 条门禁硬约定