第五章：设计文档解析
本章深入解析 Superpowers 的设计思想，帮助你理解其背后的设计理念。
设计文档的价值
Superpowers 的每个功能都经过深思熟虑的设计。阅读设计文档可以：
- 理解设计决策 - 为什么这样设计
- 学习架构思想 - 如何构建可扩展系统
- 指导自定义开发 - 如何扩展和定制
文档审查系统设计
背景
在开发过程中，经常会遇到：
- 规格文档不完整
- 实施计划与规格不符
- 缺少错误处理考虑
- 过度设计或设计不足
为了解决这些问题，Superpowers 引入了文档审查系统。
核心设计
在 Superpowers 工作流中增加两个审查阶段：
- 规格文档审查 - 在 brainstorming 之后，writing-plans 之前
- 计划文档审查 - 在 writing-plans 之后，实施之前
两者都使用迭代循环模式，类似于代码审查。
规格文档审查器
目的: 验证规格是否完整、一致、可实施。
检查内容：
| 类别 | 检查项 |
|---|---|
| 完整性 | TODO、占位符、"TBD"、不完整章节 |
| 覆盖度 | 缺失的错误处理、边界情况、集成点 |
| 一致性 | 内部矛盾、冲突的需求 |
| 清晰度 | 模糊的需求描述 |
| YAGNI | 未请求的功能、过度设计 |
输出格式：
## 规格审查
**状态:** 通过 | 发现问题
**问题（如有）**:
- [章节 X]: [问题] - [为什么重要]
**建议（参考）**:
- [不阻止通过的建议]审查循环: 发现问题 → 修复 → 重新审查 → 重复直到通过。
计划文档审查器
目的: 验证计划是否完整、符合规格、任务分解合理。
检查内容：
| 类别 | 检查项 |
|---|---|
| 完整性 | TODO、占位符、不完整任务 |
| 规格对齐 | 计划覆盖规格需求、无范围蔓延 |
| 任务分解 | 任务原子性、边界清晰 |
| 任务语法 | 任务和步骤的复选框语法 |
| 块大小 | 每块不超过 1000 行 |
块定义: 块是计划文档中的逻辑任务组，由 ## 块 N: <名称> 标题分隔。writing-plans 技能根据逻辑阶段（如"基础"、"核心功能"、"集成"）创建这些边界。每个块应该足够独立，可以单独审查。
规格对齐验证: 审查器接收：
- 计划文档（或当前块）
- 规格文档路径供参考
审查器读取两者并比较需求覆盖度。
审查过程（逐块进行）：
- writing-plans 创建块 N
- 控制器分发计划文档审查器处理块 N 内容和规格路径
- 审查器读取块和规格，返回结论
- 如有问题: writing-plans 修复块 N，转到步骤 2
- 如通过: 继续块 N+1
- 重复直到所有块通过
更新后的工作流
brainstorming → 规格 → 规格审查循环 → writing-plans → 计划 → 计划审查循环 → 实施规格审查循环：
- 规格完成
- 分发审查器
- 如有问题: 修复 → 转到 2
- 如通过: 继续
计划审查循环：
- 块 N 完成
- 分发审查器处理块 N
- 如有问题: 修复 → 转到 2
- 如通过: 下一块或实施
Markdown 任务语法
计划文档使用标准化的 Markdown 任务语法：
markdown
## 任务 1: 实现用户认证
**文件**: `src/auth.ts`
**操作**:
- [ ] 创建 User 接口
- [ ] 实现登录函数
- [ ] 添加错误处理
**验证**:
- [ ] 单元测试通过
- [ ] 类型检查通过
**代码**:
```typescript
interface User {
id: string
email: string
}时间: 预计 30 分钟
这种标准化语法确保：
- 任务可以自动解析
- 审查器可以验证语法
- 执行器可以跟踪进度
## 设计原则
### 1. 渐进式验证
不要等到最后才验证。在每个关键阶段都进行审查：设计 → 审查 → 计划 → 审查 → 实施 → 审查
这确保问题及早发现，修复成本更低。
### 2. 自动化审查
使用 AI 审查器，而非完全依赖人工：
- **一致性**: 标准化的审查标准
- **速度**: 即时反馈
- **可扩展**: 可以审查大量文档
### 3. 迭代改进
审查不是一次性的：审查 → 问题 → 修复 → 审查 → ...
持续迭代直到质量达标。
## 其他设计文档
Superpowers 还有其他重要的设计文档：
### 可视化头脑风暴重构
重构了可视化头脑风暴功能，改进了浏览器显示和终端命令。
主要改进：
- 零依赖服务器
- 更好的跨平台支持
- 改进的图形渲染
### Codex 应用兼容性
确保 Superpowers 在 Codex 应用中正常工作，特别是 worktree 和 finishing 技能的适配。
关键考虑：
- 不同的工具 API
- 平台特定行为
- 向后兼容性
## 设计模式总结
从这些设计文档中，我们可以学到：
1. **问题驱动设计** - 先识别痛点，再设计解决方案
2. **渐进增强** - 从简单开始，逐步增加复杂度
3. **自动化优先** - 能自动化的不要手动
4. **验证循环** - 不断验证，持续改进
5. **文档化思考** - 设计决策都要记录理由
## 下一步
在下一章中，我们将看到这些设计思想的实际应用，通过真实的实施计划示例来学习。
---
**参考资源**：
- [文档审查系统设计](https://github.com/obra/superpowers/blob/main/docs/superpowers/specs/2026-01-22-document-review-system-design.md)
- [可视化头脑风暴重构设计](https://github.com/obra/superpowers/blob/main/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md)
- [Codex 兼容性设计](https://github.com/obra/superpowers/blob/main/docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md)