下面我给你一个基于你当前打开的 LeanSpec 页面内容（ lean-spec.dev）并结合 KIRO 的 SDD（Software Design Doc）典型结构 的、可直接落地的迁移方案。
我会给你：
- 迁移思路（概念级）
- SDD → LeanSpec 的字段映射表（非常实用）
- 一步步迁移流程（适合你这种技术架构师）
- 一个真实可用的 LeanSpec 模板（你可以直接贴到项目里）
🧭 一、核心思路：SDD 是“重”，LeanSpec 是“轻 + AI 原生”
从 LeanSpec 的官方理念可知（ lean-spec.dev）：
- 文档不超过 300 行
- 适配人类与 AI 的工作记忆
- 边写代码边写规范
- 只在需要时增加结构
- AI 代理可直接读取并实现规范
而 KIRO 的 SDD 通常是：
- 结构完整、偏重、偏前期规划
- 包含大量设计细节、接口、流程图
- 适合人工评审，但不适合 AI 直接消费
因此迁移的关键不是“把 SDD 全部搬过来”，而是：
提炼 SDD 的核心决策、约束、状态、接口，把它压缩成 AI 能直接执行的 LeanSpec 格式。
🔄 二、SDD → LeanSpec 字段映射表（最重要的部分）
| KIRO SDD 常见内容 | LeanSpec 对应位置 | 迁移方式 |
|---|---|---|
| 背景、目标 | README.md 顶部 | 保留 3–5 行即可 |
| 系统架构图 | “系统结构”段落 | 用文字 + 模块列表替代图 |
| 模块设计 | “模块规范” | 每个模块 10–30 行 |
| 数据结构 | “状态定义 / 数据模型” | 只保留关键字段 |
| 接口设计 | “API / 交互协议” | 只保留输入/输出/约束 |
| 流程图 | “状态机 / 事件流” | 用事件列表替代图 |
| 非功能需求 | “约束 / 原则” | 只保留影响实现的部分 |
| 设计决策记录 | “决策记录（ADR）” | 每条 3–5 行 |
| 未来规划 | “待办 / 风险” | 精简成列表 |
LeanSpec 的目标不是替代 SDD，而是：
把 SDD 的“可执行部分”提炼成 AI 能直接驱动代码的规范。
🪜 三、迁移流程（你可以按这个步骤做）
步骤 1：从 SDD 中提取“必须让 AI 知道的内容”
包括：
- 系统的核心职责
- 模块边界
- 状态与事件
- 关键接口
- 不可违反的约束
这些通常只占 SDD 的 20%。
步骤 2：把 SDD 拆成 LeanSpec 的 4 个核心文件
LeanSpec 推荐从简单开始（ lean-spec.dev）：
1. README.md（总览）
- 项目目标
- 模块列表
- 关键状态
- 关键接口
- 约束
2. /spec/modules/
每个模块一个文件，10–30 行：
- 职责
- 输入/输出
- 状态
- 事件
- 约束
3. /spec/state.md
系统级状态机（如果需要）
4. /spec/decisions.md
设计决策（ADR）
步骤 3：把 SDD 的“图”转成 LeanSpec 的“结构化文本”
例如：
SDD 的流程图
👇
LeanSpec 的事件流：
事件流：
- 用户提交表单 → validate()
- validate() 失败 → 返回错误
- validate() 成功 → save()
- save() 成功 → emit("created")
SDD 的架构图
👇
LeanSpec 的模块列表：
模块：
- Auth：登录、权限
- Billing：计费、扣费
- Notification：消息推送
步骤 4：控制总行数 ≤ 300 行
LeanSpec 的“上下文经济”要求（ lean-spec.dev）：
- 文档必须适配人类与 AI 的工作记忆
- 5–10 分钟读完
因此：
- 不要复制 SDD
- 不要写长段落
- 不要写解释性文字
- 只写“可执行信息”
步骤 5：让 AI 工具（Cursor / Claude / Copilot）读取 LeanSpec 并生成代码
LeanSpec 是 AI 原生的（ lean-spec.dev）：
- AI 能直接搜索规范
- AI 能根据规范生成代码
- AI 能根据变更自动更新实现
这就是为什么迁移后开发效率会显著提升。
📄 四、给你一个可直接使用的 LeanSpec 模板（SDD 迁移版）
你可以把 SDD 内容按这个模板填进去：
README.md（总览）
# 项目目标
一句话描述系统做什么。# 模块
- ModuleA：职责…
- ModuleB：职责…
- ModuleC：职责…# 核心状态
- User: id, role, status
- Order: id, amount, state# 核心事件
- user.created
- order.paid
- order.refunded# 核心接口
POST /order/create
输入：{ userId, items }
输出：{ orderId }# 约束
- 所有订单必须有唯一 ID
- 支付必须在 30 秒内完成
/spec/modules/order.md
# Order 模块## 职责
- 创建订单
- 更新订单状态
- 触发事件## 状态
Order:
- id
- amount
- state: pending | paid | refunded## 事件流
- create() → pending
- pay() → paid
- refund() → refunded## 接口
POST /order/create
POST /order/pay## 约束
- 订单金额不可为负
/spec/state.md
Order 状态机：
pending → paid → refunded
/spec/decisions.md
# ADR## 001 使用事件驱动架构
原因：解耦模块。
影响：所有模块通过事件通信。