下面我给你一个基于你当前打开的 LeanSpec 页面内容（ lean-spec.dev）并结合 KIRO 的 SDD（Software Design Doc）典型结构 的、可直接落地的迁移方案。
我会给你：

1. 迁移思路（概念级）
2. SDD → LeanSpec 的字段映射表（非常实用）
3. 一步步迁移流程（适合你这种技术架构师）
4. 一个真实可用的 LeanSpec 模板（你可以直接贴到项目里）

🧭 一、核心思路：SDD 是“重”，LeanSpec 是“轻 + AI 原生”

从 LeanSpec 的官方理念可知（ lean-spec.dev）：

• 文档不超过 300 行
• 适配人类与 AI 的工作记忆
• 边写代码边写规范
• 只在需要时增加结构
• AI 代理可直接读取并实现规范

而 KIRO 的 SDD 通常是：

• 结构完整、偏重、偏前期规划
• 包含大量设计细节、接口、流程图
• 适合人工评审，但不适合 AI 直接消费

因此迁移的关键不是“把 SDD 全部搬过来”，而是：

提炼 SDD 的核心决策、约束、状态、接口，把它压缩成 AI 能直接执行的 LeanSpec 格式。

🔄 二、SDD → LeanSpec 字段映射表（最重要的部分）

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 使用事件驱动架构
原因：解耦模块。
影响：所有模块通过事件通信。