规范结构
理解 LeanSpec 规范的结构：前置元数据、必需部分、子规范文件，以及如何构建人类和 AI 都能理解的规范。
规范结构
每个规范包含：
- 前置元数据（YAML 元数据）
- 标题和状态徽章（自动生成）
- 核心部分（问题、解决方案、成功标准）
- 可选子规范文件（用于复杂规范）
前置元数据
必需字段
---
status: planned # 当前状态
created: '2025-11-08' # 创建日期（YYYY-MM-DD）
created_at: '2025-11-08T10:30:00Z' # ISO 时间戳（自动管理）
updated_at: '2025-11-08T14:45:00Z' # ISO 时间戳（自动管理）
---
重要：这些是系统管理的。使用 lean-spec update 修改，永远不要手动编辑。
可选字段
---
status: in-progress
created: '2025-11-08'
tags: # 分类
- api
- backend
- security
priority: high # high, medium, low
assignee: alice # 谁在做这个
depends_on: # 硬依赖（阻塞）
- spec-041
- spec-039
related: # 软关系（信息性）
- spec-043
- spec-044
created_at: '2025-11-08T10:30:00Z'
updated_at: '2025-11-08T14:45:00Z'
completed_at: '2025-11-09T16:20:00Z' # 标记为完成的时间
transitions: # 状态变更历史
- status: in-progress
at: '2025-11-08T11:00:00Z'
- status: complete
at: '2025-11-09T16:20:00Z'
---
手动编辑：只有 depends_on 和 related 必须手动编辑（尚无 CLI 命令）。所有其他字段使用 lean-spec update。
另见：前置元数据参考
状态徽章
在前置元数据后自动生成：
> **状态**：⏳ 进行中 · **优先级**：高 · **创建**：2025-11-08 · **标签**：api, backend
这由 CLI 渲染，不应手动编辑。
核心部分
最小结构
每个规范至少应有：
## 问题
[我们要解决什么问题？为什么重要？]
## 解决方案
[我们要构建什么？它如何解决问题？]
## 成功标准
- [ ] [我们如何知道完成了？]
- [ ] [成功是什么样子？]
推荐结构
对于更复杂的规范：
## 概述
[功能/变更的 1-2 段摘要]
## 问题
[详细问题描述]
### 为什么重要
[影响、紧迫性、业务背景]
### 当前状态
[今天存在但不够的是什么]
## 解决方案
[提出的方法]
### 设计决策
[做出的关键选择及原因]
### 权衡
[我们放弃了什么，考虑的替代方案]
## 实现
[高级实现方法]
### 阶段（如果是多阶段）
1. 阶段 1：[描述]
2. 阶段 2：[描述]
## 成功标准
- [ ] [具体、可衡量的结果]
- [ ] [验收标准]
- [ ] [性能目标]
## 超出范围
- [我们明确不做的事情]
- [未来考虑事项]
可选部分
仅在需要时添加：
## 研究
[探索/尝试的发现]
## 依赖
[外部依赖、被阻塞的工作]
## 测试策略
[如何验证解决方案]
## 发布计划
[部署方法、迁移步骤]
## 风险
[潜在问题和缓解措施]
子规范文件
当规范超过 400 行或有多个不同关注点时，拆分为子规范：
常见子规范
specs/042-my-feature/
├── README.md # 主规范（必需）
├── DESIGN.md # 详细设计和架构
├── IMPLEMENTATION.md # 带阶段的实现计划
├── TESTING.md # 测试策略和测试用例
├── CONFIGURATION.md # 配置示例和模式
└── API.md # API 设计（如适用）
README.md（主规范）
应包含：
- 前置元数据（元数据）
- 高级概述
- 问题陈述
- 解决方案方法
- 成功标准
- 指向子规范的详细链接
目标：<300 行
DESIGN.md
详细设计决策：
- 架构图
- 数据模型
- 组件交互
- 技术选择和理由
目标：<400 行
IMPLEMENTATION.md
执行计划：
- 阶段分解
- 任务列表
- 操作顺序
- 集成点
目标：<400 行
TESTING.md
测试策略：
- 测试用例
- 边缘情况
- 性能测试
- 集成测试
目标：<400 行
示例
简单规范（单文件）
---
status: planned
created: '2025-11-08'
tags:
- bug-fix
priority: medium
---
# 修复身份验证超时
> **状态**：📋 计划中 · **优先级**：中
## 问题
用户在 15 分钟不活动后被登出，即使正在积极使用应用。会话超时太激进。
## 解决方案
为活跃用户延长会话超时至 8 小时：
- 对真正不活跃的用户保持 15 分钟超时
- 在任何 API 调用时刷新会话
- 添加"记住我"选项以获得 30 天令牌
## 实现
1. 更新 JWT 令牌 TTL 配置
2. 添加中间件以在 API 调用时刷新令牌
3. 在登录表单添加"记住我"复选框
4. 更新文档
## 成功标准
- [ ] 用户在 8 小时的活跃使用期间保持登录
- [ ] 不活跃用户（无 API 调用）在 15 分钟后超时
- [ ] "记住我"令牌持续 30 天
- [ ] 零客户投诉关于过早登出
## 超出范围
- SSO 集成（未来工作）
- 多设备会话管理
行数：约 45 行 ✅
复杂规范（多文件）
README.md（概述）：
---
status: in-progress
created: '2025-11-08'
tags:
- api
- breaking-change
priority: high
depends_on:
- spec-041
---
# API v2 重新设计
> **状态**：⏳ 进行中 · **优先级**：高
## 概述
完全重新设计 REST API 以符合 RESTful 原则、一致的错误处理和改进的性能。
## 问题
当前 API（v1）有：
- 不一致的端点命名
- 混合 HTTP 方法（某些资源使用 POST 进行读取）
- 无标准错误格式
- 性能差（N+1 查询常见）
详见 [DESIGN.md](./DESIGN.md) 进行详细分析。
## 解决方案
构建 API v2，包含：
- RESTful 资源设计
- 一致的错误响应
- GraphQL 用于复杂查询
- <200ms p95 响应时间
参见：
- [DESIGN.md](./DESIGN.md) - 架构和设计决策
- [IMPLEMENTATION.md](./IMPLEMENTATION.md) - 阶段分解
- [TESTING.md](./TESTING.md) - 测试策略
## 成功标准
- [ ] 所有 v1 端点都有 v2 等效项
- [ ] p95 响应时间 <200ms
- [ ] 100% API 测试覆盖率
- [ ] 发布迁移指南
- [ ] v2 启动后 3 个月内零破坏性变化
## 超出范围
- GraphQL 订阅（v2.1）
- 批量操作（v2.2）
DESIGN.md（详细设计 - 350 行） IMPLEMENTATION.md（执行计划 - 280 行） TESTING.md（测试策略 - 190 行）
总计：约 820 行，跨 4 个文件 ✅ 最大文件：350 行 ✅
结构最佳实践
要做：
- ✅ 从问题、解决方案、成功标准开始（最小可行）
- ✅ 根据需要逐步添加部分
- ✅ 当 >400 行时拆分为子规范
- ✅ 在子规范之间链接以便导航
- ✅ 将 README.md 保持为入口点/概述
不要：
- ❌ 预先添加所有可能的部分
- ❌ 让任何单个文件超过 400 行
- ❌ 埋藏问题陈述
- ❌ 跳过成功标准
- ❌ 在一个规范中混合多个不相关的关注点
AI 友好结构
为了最大化 AI 代理理解：
1. 使用清晰的标题
## 问题
## 解决方案
## 成功标准
而非："问题所在"、"我们的解决方案"、"我们如何知道有效"
2. 包含示例
## 解决方案
使用 Redis 进行缓存：
\`\`\`json
\{
"key": "user:123",
"value": \{"name": "Alice", "email": "alice@example.com"\},
"ttl": 300
\}
\`\`\`
3. 明确边界
## 超出范围
- 移动应用对等（未来）
- Google 以外的 OAuth 提供商（不需要）
4. 定量定义成功
## 成功标准
- [ ] API 响应时间 <100ms（p95）
- [ ] 缓存命中率 >80%
- [ ] 2 周内零假阳性
而非："快速 API"、"良好缓存"、"运行良好"
另见：编写 AI 可执行的规范
下一步
参考：CLI 文档 获取命令详情