设计理念
SuperSpec 的设计基于几个核心理念，这些理念源自对 AI 辅助开发实践的深入观察。
规格先行 (Spec-First)
理念
在 AI 时代，规格文档比代码更重要。
代码可以由 AI 快速生成，但正确的规格才能保证生成正确的代码。
实践
传统：需求 → 代码 → 文档（经常跳过）
SuperSpec：需求 → 规格 → 代码（文档已包含）为什么有效
- 减少歧义 - 结构化规格消除理解偏差
- 可验证 - 验收标准明确，便于检查
- 可追溯 - 从需求到代码的完整链路
上下文经济 (Context Economy)
理念
AI 的上下文窗口是稀缺资源，必须高效利用。
实践
| 约束 | 规则 | 原因 |
|---|---|---|
| 文件大小 | ≤ 300 行 | 适配上下文窗口 |
| 文件数量 | 最小化 | 减少切换开销 |
| 内容密度 | 高信息量 | 避免冗余 |
300 行限制的由来
典型 AI 上下文窗口：8K-128K tokens
单个文件最佳大小：300 行 ≈ 1.5K tokens
留出空间用于：对话历史 + 代码生成 + 工具输出双模式工作流 (Dual-Mode Workflow)
理念
不同任务需要不同程度的规格化。
实践
标准模式 - 快速迭代
- 适合：Bug 修复、小功能、原型开发
- 产物：proposal.md + tasks.md
- 时间：分钟级
增强模式 - 完整规格
- 适合：复杂功能、需要评审、多人协作
- 产物：+ spec.md + design.md + checklist.md
- 时间：小时级
选择指南
功能复杂度
│
├─ 低 ──→ 标准模式
│
├─ 中 ──→ 标准模式 + 手动补充
│
└─ 高 ──→ 增强模式渐进式采用 (Progressive Adoption)
理念
工具应该适应团队，而非团队适应工具。
实践
Level 0：仅 proposal
bash
superspec create myFeature
# 只使用 proposal.md 记录想法Level 1：+ tasks
bash
/ss-tasks
# 添加任务追踪Level 2：完整流程
bash
superspec create myFeature -b
# 使用增强模式，完整流程Level 3：团队协作
bash
# 配置团队模板
# 集成 CI/CD
# 自动化检查上下文恢复
理念
跨会话的上下文连续性是 AI 开发的关键。
问题
会话 1：实现了用户认证
会话 2：AI 不知道会话 1 做了什么
会话 3：重复解释需求...解决
bash
# 会话结束前
superspec sync # 保存 git 变更到 context.md
# 新会话开始
/ss-resume # AI 读取 context.md 恢复上下文原理
context.md = git diff + git status + 当前任务状态AI 通过读取 context.md，可以快速了解：
- 项目当前状态
- 已完成的工作
- 待处理的任务
本地优先 (Local-First)
理念
所有数据应该存储在项目中，随代码一起版本控制。
实践
project/
├── .superspec/ # 所有 SuperSpec 数据
│ ├── changes/ # 变更记录
│ └── archive/ # 历史归档
├── src/ # 源代码
└── .git/ # 版本控制优势
- 隐私 - 数据不离开本地
- 版本控制 - 与代码同步管理
- 可移植 - 项目即包含所有信息
- 离线可用 - 无需网络连接
总结
SuperSpec 的设计理念可以概括为：
规格先行 + 上下文经济 + 双模式 + 渐进采用 + 上下文恢复 + 本地优先这些理念共同构成了一个为 AI 辅助开发优化的工具集。