Appearance
OpenSpec 负责想清楚，Superpowers 负责做扎实。别混用，这是关键。
为什么需要这套组合
最早接触 OpenSpec 时，直观感受是：这东西对老项目特别有用，尤其是那种"没人说得清现在到底是什么状态"的项目。
后来又陆续接触了 Superpowers、gstack，以及 Spec Kit。这一套东西都在解决同一类问题——把"想清楚"和"写对代码"这两件事拆开。
但真正用了一圈下来，最终选择很简单：
留下 OpenSpec + Superpowers，gstack 和 Spec Kit 基本都弃用了。
原因不复杂：它们在个人使用场景里功能有些重叠，最终没有带来额外增益，反而增加了工具切换成本。
四工具对比
| 工具 | 核心定位 | 最终选择 | 原因 |
|---|---|---|---|
| OpenSpec | 需求梳理、提案编写 | ✅ 保留 | 想清楚阶段的核心工具 |
| Superpowers | 代码质量、执行落地 | ✅ 保留 | 做扎实阶段的核心工具 |
| gstack | 多代理协作 | ❌ 弃用 | 场景复杂，切换成本高 |
| Spec Kit | 规范生成 | ❌ 弃用 | 与 OpenSpec 功能重叠 |
一句话结论
OpenSpec 负责想清楚，Superpowers 负责做扎实。
别混用，这是关键。
三步最小流程
┌─────────────────────────────────────────────────────────────┐
│ OpenSpec + Superpowers │
├─────────────────────────────────────────────────────────────┤
│ │
│ ① OpenSpec：写清楚 │
│ └── proposal：做什么/为什么/怎么做 │
│ ↓ │
│ ② Superpowers：做扎实 │
│ └── write-plan + TDD + 代码检查 │
│ ↓ │
│ ③ OpenSpec：留记录 │
│ └── 更新 spec 或 archive │
│ │
└─────────────────────────────────────────────────────────────┘步骤详解
① 用 OpenSpec 写清楚（但别写多）
现在只用 OpenSpec 做一件事：写一个很轻的 proposal
内容就三点：
| 内容 | 说明 |
|---|---|
| 要做什么 | 核心目标 |
| 为什么做 | 动机和价值 |
| 大概怎么做 | 初步方案 |
重点是：写完一定要自己改一遍。
因为 AI 写的东西，很容易"看起来合理，但其实没想清楚"。这一步如果偷懒，后面基本都会返工。
OpenSpec 使用技巧
# 推荐的 proposal 模板
## 要做什么
[一句话描述核心需求]
## 为什么做
- 解决什么问题
- 带来什么价值
## 大概怎么做
- 初步方案
- 可能的难点② 切到 Superpowers，把事情做对
等方向确定，才会打开 Superpowers，而且只在这个阶段用。
一般就做三件事：
| 任务 | 说明 |
|---|---|
| 用 write-plan 拆任务 | 把大目标拆成可执行的小任务 |
| 简单走 TDD | 至少关键逻辑有测试 |
| 把"写代码"和"检查代码"分开 | 独立的审查环节 |
不需要搞很重的多代理体系，但至少要有一个"挑错"的过程。
这一阶段的目标很简单：别把代码写烂。
Superpowers 使用技巧
bash
# 1. 用 write-plan 拆任务
/superpowers write-plan
# 2. 关键逻辑走 TDD
/superpowers tdd --target=core_logic
# 3. 代码检查
/superpowers review③ 做完回 OpenSpec 留个记录
这一步以前几乎不做，现在觉得很值。
简单更新一下 spec 或 archive：
| 操作 | 说明 |
|---|---|
| 更新 spec | 记录最终方案 |
| 创建 archive | 保存决策过程 |
| 标记状态 | 已完成/已放弃 |
为什么重要：下次回头看，能快速理解当时的决策逻辑。
两个踩过的坑
坑一：混用工具
| 错误做法 | 正确做法 |
|---|---|
| OpenSpec 写代码 | OpenSpec 只做提案 |
| Superpowers 改需求 | 需求回 OpenSpec 处理 |
| 边想边做 | 先想清楚，再动手 |
症状：两个工具里内容打架，不知道哪个是最新状态。
解法：阶段分离，工具各司其职。
坑二：OpenSpec 写太多
| 错误做法 | 正确做法 |
|---|---|
| 写详细设计文档 | 只写轻量 proposal |
| 过度规划 | 保持灵活性 |
| AI 生成后直接用 | 一定要自己改一遍 |
症状：写了半天文档，但代码没动。文档越来越复杂，实际价值越来越低。
解法：严格控制 proposal 长度，三点够了。
判断方法：什么时候该做什么
| 场景 | 应该做什么 |
|---|---|
| 需求不清晰 | 回 OpenSpec，想清楚再说 |
| 方向已确定 | 切 Superpowers，动手做 |
| 做到一半发现方向错了 | 回 OpenSpec，重新想 |
| 代码质量不稳定 | 用 Superpowers 加强审查 |
| 项目状态混乱 | 用 OpenSpec 梳理现状 |
实际案例
案例：添加一个新的 API 端点
Step 1：OpenSpec 写 proposal
markdown
## 要做什么
为用户模块添加获取用户信息的 API 端点
## 为什么做
- 前端需要展示用户信息
- 现有接口数据格式不统一
## 大概怎么做
- GET /api/users/:id
- 返回用户基本信息Step 2：Superpowers 实现
bash
# 拆任务
/superpowers write-plan "实现 GET /api/users/:id"
/*
TDD 测试：
1. 测试获取存在的用户 -> 返回用户信息
2. 测试获取不存在的用户 -> 返回 404
*/
# 写代码 + 审查
/superpowers reviewStep 3：OpenSpec 留记录
markdown
## 已完成
- [x] GET /api/users/:id
- [x] 包含字段：id, name, email, avatar
- [x] 错误处理：用户不存在返回 404
## 决策记录
- 初期只返回基本信息，详情后续扩展一句话总结
OpenSpec + Superpowers = 想清楚 + 做扎实。
三步流程：OpenSpec 写 proposal → Superpowers 落地 → OpenSpec 留记录。
避坑指南：别混用，别写多，别跳过记录。
