- 传统开发：代码是唯一可信源，文档后置、容易过时
- AI-Native SDD：规约（spec，一般放在仓库里
spec.md）才是唯一可信源，代码只是规约的产物；人和 AI 共同遵守这份规约契约 - 规约不只是给人看的文档，是AI 可执行、可校验的结构化意图描述：业务目标、边界约束、验收标准、异常场景、架构规则
标准 4 步工作流
- Specify 定义规约：业务 + 架构一起输出结构化 spec，明确功能、非功能、边界 case、安全约束
- Plan 拆解方案：AI 基于 spec 拆解技术方案、任务清单
- Implement 执行实现：AI Agent 生成代码、接口、注释
- Validate 规约校验：从 spec 自动生成测试，验证实现是否匹配规约；不满足则自动修复，直到通过
和传统 / 普通 AI 编码的区别
表格
| 模式 | 起点 | 可信源 | 风险 |
|---|---|---|---|
| 传统开发 | 需求文档 | 代码 | 文档容易和代码脱节 |
| Vibe Coding（Copilot 随手写） | 零散 prompt | AI 输出代码 | 需求漂移、隐性缺陷、不可复现 |
| AI-Native SDD | spec 规约 | spec 规约 | AI 输出被规约约束，可重复验证 |
配套工具生态
- GitHub Spec Kit：微软开源 SDD 工具包
- AWS Kiro：AWS 的 spec-first AI IDE
- Cursor / Claude Code：可配置为 SDD 工作流，强制先读 spec 再编码
关键概念
- Executable Spec（可执行规约）：描述系统行为而非实现细节，能自动生成校验逻辑
- Harness（校验底座）：给 AI Agent 的约束环境，包含规则、检查项、权限边界，保证 AI 不能脱离规约乱实现
- AI-Native Engineer ：角色转变，人不再主要写代码，而是设计规约、设计 Agent 运行环境、做质量治理ai-native-...
一句话总结
AI-Native SDD：先定契约，再让 AI 干活；规约为王，代码只是副产品，把大模型的随机性约束在明确的工程契约内，提升团队级 AI 编码稳定性。
SDD AI-Native spec.md 模板（可直接丢给Cursor / Claude Code / GitHub Spec Kit）
原则：描述WHAT，不写HOW；写清楚验收标准、边界、约束，不预设具体实现。 所有【】里的内容是占位，替换后删除【】
# Spec: 【模块/功能名称】
Version: 0.1
Status: Draft | Review | Approved
Author: 【姓名/团队】
Last Update: 【日期】
AI Harness Rules: 【强制给AI的全局约束】
## 1. 目标 (Goal)
一句话说明这个模块要解决什么业务问题，不写技术细节。
> 示例：提供用户订单查询接口，支持按用户ID分页查询已完成订单，用于前端订单列表展示。
## 2. 业务上下文 (Context)
- 所属系统：【系统名】
- 调用方：【前端/其他微服务】
- 依赖外部服务：【依赖服务名，无则填无】
- 业务边界：本模块**不负责**【哪些事情不属于它】
## 3. 功能需求 (Functional Requirements)
每条需求编号，**必须可验证**，避免模糊描述。
- FR-001：【功能描述】
- Acceptance Criteria（验收标准）：
- ✅ 正常场景：【输入 -> 预期输出】
- ✅ 边界场景：【边界输入 -> 预期输出】
- FR-002：【功能描述】
- Acceptance Criteria：
- ✅ ...
## 4. 非功能需求 (Non-Functional Requirements)
- NFR-001 性能：【如：单接口P95 < 200ms；支持QPS 500】
- NFR-002 可用性：【如：99.9%可用；降级策略：xxx】
- NFR-003 安全：【权限、脱敏、防注入、输入校验规则】
- NFR-004 兼容性：【数据库版本、运行环境、API版本】
## 5. 数据模型 & 契约 (Data Contract)
只定义结构、字段含义、约束，不写数据库建表SQL（可选，简单场景可附）。
### 入参
```json
{
"userId": "string，必填，用户唯一标识",
"pageNum": "int，可选，默认1，>=1",
"pageSize": "int，可选，默认10，最大50"
}返回结构体
{
"code": "int",
"msg": "string",
"data": {
"total": "long",
"records": []
}
}6. 错误码 & 异常行为
列出所有预期异常，定义返回结果。
- ERR-10001：用户不存在 → code=10001, msg="用户不存在"
- ERR-10002：pageSize超过上限 → code=10002, msg="分页大小不能超过50"
7. 业务规则 & 约束 (Business Rules)
业务硬规则，AI实现时不能突破。
- BR-001：只能查询当前登录用户自己的订单，禁止越权查看他人订单
- BR-002：已删除订单不返回
8. 排除项 (Out of Scope)
非常重要，明确禁止AI额外实现的功能，防止scope creep
- ❌ 不实现订单新增/修改/删除
- ❌ 不做复杂报表统计
- ❌ 不实现消息推送
9. 测试规约 (Test Spec)
AI需要自动生成单元/集成测试，覆盖下面case：
- 正向正常查询
- 入参非法校验（pageSize=0、负数）
- 用户不存在
- 分页到最后一页（空结果）
10. AI实现约束 (Harness for Agent)
这一段直接约束AI编码行为，SDD核心
- 架构约束：必须遵循【项目架构规范，如DDD分层、Controller/Service/Repository】
- 编码规范：【项目编码规范，如不允许直接SQL拼接，统一使用参数化查询】
- 禁止行为：
- 禁止新增spec未定义的接口、字段
- 禁止修改外部依赖模型
- 禁止硬编码业务魔法数字，统一常量
- 输出产物要求：
-
源代码
-
单元测试
-
接口注释（openapi/swagger注解）
使用小贴士
- 写spec时不要写代码，只写契约；写完再交给AI实现
- 评审spec，而不是评审AI生成的代码；spec通过才允许进入实现阶段
- 修改需求必须先改spec，再重新触发AI实现；不允许直接改代码绕开规约
- 简单小功能可以精简，复杂模块可以拆分多个spec
要不要我再给一个已经填好内容的完整样例spec.md（订单查询例子），方便你直接参考怎么写？
-