第一性原理

SuperSpec 基于五条第一性原理设计，这些原则指导着工具的设计和用户的使用方式。

原则一：上下文经济

每个 artifact 控制在 300 行以内，硬限 400 行

为什么？

AI 的上下文窗口是宝贵且有限的资源。过大的文档会：

• 消耗更多 token
• 降低 AI 的理解精度
• 增加响应时间

实践

• 使用 superspec lint 检查大小
• 使用 /ss-specs 拆分过大的 spec
• 优先记录决策信息，而非背景介绍

---

原则二：信噪比

每个句子必须提供决策信息

为什么？

AI 的注意力和你的时间都是有限的。冗余信息会：

• 分散 AI 的注意力
• 增加阅读负担
• 模糊关键信息

实践

• 删除"显而易见"的描述
• 避免重复表达同一观点
• 用列表代替段落

差的写法:

用户认证是一个非常重要的功能，它可以帮助我们确保只有
授权用户才能访问系统。在当今的互联网环境中，安全性
变得越来越重要...

好的写法:

## 问题
- 当前系统无认证机制
- 所有 API 可被匿名访问

## 方案
- 实现 JWT 认证
- 添加角色权限控制

---

原则三：意图优于实现

关注为什么和什么，不关注怎么做

为什么？

规格文档的目的是指导 AI 和开发者，而不是替代代码：

• AI 擅长实现细节
• 人类擅长定义意图
• 过早的实现细节会限制方案

实践

• proposal 描述"为什么需要"
• spec 描述"要做什么"
• 让 AI 决定"怎么做"

差的写法:

创建 src/auth/middleware.ts 文件，导出一个 authMiddleware
函数，接受 Request 对象，从 header 提取 Authorization...

好的写法:

## 需求
- API 路由需要认证保护
- 支持 JWT token 验证
- 未认证请求返回 401

---

原则四：渐进式披露

从最小开始，仅在需要时扩展

为什么？

不是所有变更都需要完整的规格文档：

• 简单 bug 修复不需要设计文档
• 小功能不需要用户故事
• 只在复杂度增加时增加文档

实践

• 默认使用标准模式
• 只在需要时启用增强模式 (-b)
• 按需添加 clarify

工作流选择:

简单修复 → 标准模式
常规功能 → 标准模式
复杂功能 → 增强模式
架构变更 → 增强模式 + 创造模式

---

原则五：必备内容

元数据、问题、方案、成功标准、权衡

为什么？

这五个要素构成了完整的决策上下文：

• 元数据: 追踪和管理
• 问题: 为什么要做
• 方案: 打算怎么做
• 成功标准: 怎么算完成
• 权衡: 做了什么取舍

实践

每个 proposal 至少包含：

---
name: xxx
date: xxx
status: draft
---

# 问题
[为什么需要这个变更]

# 方案
[提议的解决方案]

# 成功标准
- [ ] 可衡量的目标

# 权衡
[方案的优缺点]

---

总结

原则	核心问题	实践方法
上下文经济	文档太大了吗？	lint, 拆分
信噪比	每句话都有用吗？	删减, 列表
意图优于实现	在描述意图还是实现？	关注 why/what
渐进式披露	真的需要这么多吗？	按需扩展
必备内容	五要素齐全吗？	检查清单