A-2 prep-sandbox-space.sh: - 修 A-1 mount 断链:拷贝 workspace 当前状态到 /tmp/xstudio-sandbox/<hash>/space/ - +force 选项覆盖已有空间 - 推断 workspaceRoot 走 last_workspace 文件兜底 A-2 dispatch-preflight.sh: - 4 项自检:docker / 容器 up / space 可写 / .claude/skills 拷到位 - + bonus: workspaceRoot ai-config - 自动调 prep-sandbox-space / prep-sandbox-skills / auto-setup-xstudio-ai - 实测:ccc workspace 全部 ✅ B-2 brainstorming-openspec-mapping.md: - design.md → chg 工件字段映射表 - naming 约定 (capability / chg_id / S 编号 / C 编号) - chg 创建 10 步 checklist - 与 superskills using-superpowers 冲突解决 E-2 prompt-template.md: - 6 段 prompt 结构 (Header / Cache / Don't / 工件 / 步骤 / 汇报) - 完整 chg_0005 实例 - 模板生成脚本占位(待下次写) Co-Authored-By: Claude Opus 4.8 <[email protected]>
188 lines
6.7 KiB
Markdown
188 lines
6.7 KiB
Markdown
# Brainstorming ↔ Openspec 映射指南(B-2)
|
||
|
||
> 编制:2026-09-28 · 配合 learnings §B-2
|
||
> 状态:host-side 文档;给"同时激活 brainstorming + openspec"的场景用
|
||
|
||
---
|
||
|
||
## 1. 背景
|
||
|
||
两个 skill 看起来重叠:
|
||
- **brainstorming**(superskills):设计阶段产出 `docs/superpowers/specs/YYYY-MM-DD-<topic>-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: <capability>` 标题行 | spec.md `# Spec:` 标题 + map.yaml `# spec: <capability>@<chg_id>` | capability 名必须一致,chg_id 必须对应目录 basename |
|
||
| `## Requirement` EARS 句式 | spec.md `## Requirement` 段 | 复制保留 + 改写为 capability 级 EARS |
|
||
| `## ADDED Scenarios` (`### S<n>`) | spec.md `## ADDED Scenarios` | capability 级全局 S 编号,跨 chg 连续 |
|
||
| `## MODIFIED Scenarios` | spec.md `## MODIFIED Scenarios` | **整块从 openspec/specs/<cap>/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<n>_<slug>` | one-to-many 也行(map.yaml 显式声明) |
|
||
|
||
## 4. 命名约定(避免冲突)
|
||
|
||
### 4.1 capability 级 S 编号
|
||
- capability 在 `openspec/specs/<cap>/spec.md` 主 spec 已有 → 新 chg 接续最大号
|
||
- capability 是新的 → 从 S1 起
|
||
- **新 chg 用 delta 段**(`## ADDED/MODIFIED/REMOVED Scenarios`),非 delta 写法(`## Concrete Scenarios`)会有迁移提示
|
||
|
||
### 4.2 chg_id
|
||
格式:`chg_NNNN_<capability-scope>_<change-slug>`
|
||
- NNNN:四位数字,按 archive 一起扫(不重用)
|
||
- capability-scope:与 capability 名一致
|
||
- change-slug:动词/名词短语(kebab-case)
|
||
|
||
例:`chg_0003_dispatch_helpers`、`chg_0004_experiment_platform_frontend`
|
||
|
||
### 4.3 capability 名
|
||
- 单一 capability:`<scope>`(如 `experiment_platform`)
|
||
- 跨 capability 复合 chg:拆成多个 chg,不要硬塞进一个
|
||
|
||
## 5. testcases 命名约定
|
||
|
||
格式:`C<数字>_<slug>`(`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: <capability 名称>
|
||
|
||
## Requirement
|
||
WHEN <trigger> THE SYSTEM SHALL <response>。
|
||
|
||
## ADDED Scenarios
|
||
|
||
### S<n> <场景名>
|
||
- **WHEN** <触发动作>
|
||
- **AND** <前置条件>
|
||
- **THEN** <可观测结果>
|
||
|
||
## UX / Interaction(UI 类才填)
|
||
- 原型位置:...
|
||
- 交互决策:...
|
||
```
|
||
|
||
### tasks.md 最小结构
|
||
```markdown
|
||
# Tasks (DAG)
|
||
- id: T1
|
||
type: architect | implementer | tester | qa
|
||
depends_on: []
|
||
output: <path>
|
||
verification: <check>
|
||
```
|
||
|
||
### testcases.md 最小结构
|
||
```markdown
|
||
### C<n>_<slug>
|
||
- Scenario: S<n>
|
||
- Type: unit | integration | e2e | ux
|
||
- Priority: P0 | P1 | P2
|
||
- Given: ...
|
||
- When: ...
|
||
- Then: ...
|
||
- Automated: true | false
|
||
- Bound Task: T<n> # 必须在 tasks.md 真实存在
|
||
```
|
||
|
||
### testcases.map.yaml 最小结构
|
||
```yaml
|
||
# spec: <capability>@<chg_NNNN>
|
||
scenarios:
|
||
- id: S1
|
||
cases: [C1_<slug>, C2_<slug>]
|
||
gate:
|
||
blocking_gap_tolerance: 0
|
||
implementation_files:
|
||
- src/<module>/
|
||
test_files:
|
||
- tests/<module>/
|
||
```
|
||
|
||
## 7. 流程清单(chg 创建)
|
||
|
||
```
|
||
□ 1. 读 design.md,按"## ADDED Scenarios"分 chg(每 chg 一个 delta 段)
|
||
□ 2. mkdir -p openspec/changes/chg_<NNNN>_<slug>
|
||
□ 3. cp templates/{proposal,spec,tasks,testcases,testcases.map.yaml}.md chg_<NNNN>_<slug>/
|
||
□ 4. 改 frontmatter:
|
||
- change_id: chg_<NNNN>
|
||
- skip_coverage: true(纯基础设施/无行为变更)
|
||
□ 5. 写 spec.md:# Spec: <capability> + 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 条门禁硬约定 |