SDD 入门指南

适合对象：没听过 SDD，第一次接触 Spec-Kit 的同事

什么是 SDD？

SDD = Spec-Driven Development（规范驱动开发）

核心理念：先写规范，再写代码

传统开发：需求 → 直接写代码 → 后期补文档

SDD 开发：需求 → 宪法 → 规范 → 计划 → 任务 → 代码 → 文档

为什么需要 SDD？

保证 AI 产出的代码符合企业规范
让不同水平的开发者都能产出一致质量的代码
减少返工、降低沟通成本
知识可沉淀、可复用、可审计

SDD 四阶段

1. 宪法（Constitution）

核心问题：项目的核心原则和约束是什么？

通俗理解：定规矩（什么能做、什么不能做）

产出物：constitution.md

2. 规范（Specification）

核心问题：要做什么功能？用户场景是什么？

通俗理解：定目标（要做什么、为谁做）

产出物：spec.md

3. 计划（Plan）

核心问题：用什么技术？怎么实现？

通俗理解：定路线（用什么技术、怎么实现）

产出物：plan.md

4. 任务（Tasks）

核心问题：具体要做哪些事？先后顺序？

通俗理解：定步骤（先做什么、后做什么）

产出物：tasks.md

Spec-Kit 的作用

帮你生成这四个阶段的文档
自动检查产出是否符合规范
可以一键改善质量

小白的典型误区

"宪法就是随便写几条原则"

"规范就是把需求文档复制过来"

"计划就是列个技术栈"

"任务就是随便分几个步骤"

小白的正确做法

宪法要写具体可执行的原则

规范要写用户场景和验收标准

计划要写架构设计和数据模型

任务要写依赖关系和验收条件

范例对比：宪法

❌ 差的宪法

# 项目宪法

## 原则
- 代码要写得好
- 要注意安全
- 要高性能

太抽象，无法执行

"写得好"是什么标准？

"注意安全"具体指什么？

"高性能"的指标是多少？

✅ 好的宪法

# IP 查询服务宪法

## 核心原则

### 1. 代码规范
- 所有 Python 代码必须使用 FastAPI + Pydantic
- 数据库操作必须使用 SQLAlchemy ORM，禁止原生 SQL 拼接
- API 接口必须遵循 RESTful 规范，返回统一 JSON 格式
- 禁止硬编码配置，统一从环境变量读取

### 2. 安全要求
- 所有 API 必须实现 RBAC 权限控制
- 敏感数据（密码、token）必须加密存储
- 所有操作必须记录审计日志（who/when/what）
- 禁止在代码中暴露数据库密码或 API Key

### 3. 性能标准
- API 响应时间 < 200ms（P95）
- 数据库查询必须建立索引
- 大列表必须实现分页（默认 50 条/页）
- 缓存策略：Redis + 本地缓存双层

## 禁止行为
- ❌ 禁止使用 eval() 等危险函数
- ❌ 禁止在循环中执行数据库查询
- ❌ 禁止返回完整堆栈信息给前端
- ❌ 禁止使用未经验证的第三方库

每条原则都具体可执行

有明确的验收标准（如响应时间 < 200ms）

有禁止行为清单，避免常见错误

AI 可以直接根据这些约束生成合规代码