迁移到 LeanSpec

本指南帮助您从现有的 SDD 工具和文档系统迁移到 LeanSpec。

快速概览

LeanSpec 迁移主要关注两个领域：

元数据/前置元数据（主要） - 使用 lean-spec backfill 从 git 历史中提取
文件夹组织（不同） - 取决于您的源工具

好消息：LeanSpec 对内容格式很灵活——您可以保持现有的写作风格！

按源工具划分的迁移复杂度

GitHub spec-kit（最简单）✅

源：.specify/specs/

**已兼容！**spec-kit 使用相同的文件夹结构（###-name/）。

迁移步骤：

# 1. 从 .specify/specs 移动到 specs/
mv .specify/specs specs/

# 2. 重命名 spec.md → README.md
find specs -name 'spec.md' -execdir mv \{\} README.md \;

# 3. 从 git 历史生成前置元数据
lean-spec backfill --assignee --all

# 4. 验证
lean-spec validate
lean-spec board

时间：20 个规范约 5 分钟

OpenSpec（中等）⚠️

源：openspec/specs/ + openspec/changes/archive/

挑战：合并当前规范和已归档变更的单独目录。

迁移步骤：

# 1. 复制并合并目录
cp -r openspec/specs/* specs/
cp -r openspec/changes/archive/* specs/

# 2. 按顺序重新编号规范
mv specs/auth specs/001-user-authentication
mv specs/api-gateway specs/002-api-gateway

# 3. 重命名 spec.md → README.md
find specs -name 'spec.md' -execdir mv \{\} README.md \;

# 4. 从 git 历史生成前置元数据
lean-spec backfill --assignee --all

# 5. 验证
lean-spec validate
lean-spec board

时间：20 个规范约 15-30 分钟

ADR/RFC 集合（复杂）🔴

源：扁平 markdown 文件（例如，docs/adr/####-title.md）

挑战：将扁平文件重组为文件夹层次结构。

迁移步骤：

# 1. 为每个 ADR 创建文件夹
mkdir -p specs/001-use-microservices
mv docs/adr/0001-use-microservices.md specs/001-use-microservices/README.md

mkdir -p specs/002-event-sourcing-audit
mv docs/adr/0042-event-sourcing-audit.md specs/002-event-sourcing-audit/README.md

# 对所有 ADR 重复...

# 2. 从 git 历史生成前置元数据
lean-spec backfill --assignee --all

# 3. 验证
lean-spec validate
lean-spec board

时间：20 个规范约 30-60 分钟

`lean-spec backfill` 命令

这是您从 git 历史生成前置元数据的主要迁移工具。

基本用法

# 从 git 历史提取时间戳
lean-spec backfill

# 从 git 作者包含受让人
lean-spec backfill --assignee

# 提取所有可用元数据
lean-spec backfill --all

# 预览更改而不应用
lean-spec backfill --dry-run

它提取什么

从 git 历史：

created_at - 首次提交时间戳
updated_at - 最后提交时间戳
completed_at - 状态更改为 'complete' 的时间
assignee - 首次提交作者（使用 --assignee）
transitions - 完整状态变更历史（使用 --transitions）

之后手动设置：

priority - 默认为 'medium'，使用 lean-spec update --priority 调整
tags - 从文件夹名称默认，使用 lean-spec update --tags 调整
status - 从内容/历史推断，如需要可调整

示例输出

---
status: complete
created_at: '2024-03-15T10:23:45Z'
updated_at: '2024-11-08T14:30:12Z'
completed_at: '2024-03-20T16:45:00Z'
assignee: Alice Chen
priority: high
tags:
  - product
  - mvp
---

使用 `lean-spec migrate`

对于更复杂的迁移或 AI 辅助工作流，使用 lean-spec migrate 命令。

手动模式（默认）

为任何 AI 工具输出迁移说明：

lean-spec migrate ./docs/adr/

这会生成一个提示，您可以复制到 ChatGPT、Claude、Copilot 或任何 AI 助手：

您正在帮助将规范文档迁移到 LeanSpec 格式。

源：./docs/adr/（找到 23 个文档）

您的任务：
1. 分析源文档
2. 提取元数据（标题、状态、日期、优先级）
3. 对于每个文档：
   - 运行：lean-spec create <name>
   - 运行：lean-spec update <name> --status <status>
   - 运行：lean-spec update <name> --priority <priority>
   - 编辑内容以匹配 LeanSpec 结构
4. 保留决策理由和关系
5. 保持规范在 400 行以下

现在执行迁移命令。

AI 辅助模式

使用 AI CLI 工具自动迁移：

# 使用 GitHub Copilot CLI
lean-spec migrate ./docs/adr/ --with copilot

# 使用 Claude CLI
lean-spec migrate ./docs/adr/ --with claude

# 使用 Gemini CLI
lean-spec migrate ./docs/adr/ --with gemini

先决条件：

AI CLI 工具必须已安装
工具必须已认证/配置

选项：

# 预览而不更改
lean-spec migrate ./docs/adr/ --dry-run

# 分批处理
lean-spec migrate ./docs/adr/ --batch-size 10

# 迁移后自动运行回填
lean-spec migrate ./docs/adr/ --backfill

迁移检查清单

使用此检查清单确保完整迁移：

迁移前

备份您的现有文档
检查源文件夹结构
检查 git 历史是否可用（用于 backfill）
安装 LeanSpec：npm install -g lean-spec
初始化 LeanSpec：lean-spec init

迁移期间

重组文件夹（如您的源工具需要）
将主规范文件重命名为 README.md
运行 lean-spec backfill --assignee --all
如需要，手动调整优先级
如需要，手动调整标签
验证状态值是否正确

迁移后

运行 lean-spec validate 检查问题
运行 lean-spec board 可视化迁移
测试规范发现：lean-spec list、lean-spec search
更新任何损坏的关系（depends_on、related）
迁移系统提示（AGENTS.md、.cursorrules）

迁移系统提示

不要忘记迁移 AI 指导文件！

常见源文件

# 源工具通常有：
openspec/AGENTS.md
.cursorrules
.github/copilot-instructions.md
CLAUDE.md

LeanSpec 使用

AGENTS.md（在项目根目录）

迁移策略

检查源工具的现有 AI 指导
保留项目特定约定
与 LeanSpec AGENTS.md 合并（由 lean-spec init 创建）
更新命令：openspec → lean-spec 等
保持团队工作流完整

这确保 AI 代理在过渡期间保持连续性。

常见迁移场景

场景 1：每个功能有多个文件的 spec-kit

源：

.specify/specs/
└── 001-task-management/
    ├── spec.md
    ├── plan.md
    ├── tasks.md
    └── contracts/
        └── api.yml

选项：

选项 A：保留子规范（推荐用于复杂功能）

mv .specify/specs specs/
mv specs/001-task-management/spec.md specs/001-task-management/README.md
# 保持 plan.md、tasks.md、contracts/ 原样
lean-spec backfill --assignee --all

选项 B：合并（用于简单功能）

# 手动将 spec.md + plan.md 合并到 README.md
# 然后运行回填
lean-spec backfill --assignee --all

场景 2：具有单独目录的 OpenSpec

源：

openspec/
├── specs/auth/spec.md
└── changes/archive/2024-11-15-oauth/

迁移：

# 1. 合并目录
cp -r openspec/specs/* specs/
cp -r openspec/changes/archive/* specs/

# 2. 重新编号和重命名
mv specs/auth specs/001-authentication
find specs -name 'spec.md' -execdir mv \{\} README.md \;

# 3. 回填元数据
lean-spec backfill --assignee --all

# 4. 更新 AGENTS.md 命令
sed -i 's/openspec/lean-spec/g' AGENTS.md

场景 3：扁平 ADR 文件

源：

docs/adr/
├── 0001-use-microservices.md
├── 0042-event-sourcing.md
└── 0105-graphql-api.md

迁移：

# 1. 创建文件夹层次结构
for file in docs/adr/*.md; do
  name=$(basename "$file" .md | sed 's/^[0-9]*-//')
  num=$(ls -1 specs/ | wc -l | xargs printf "%03d")
  mkdir -p "specs/$\{num\}-$\{name\}"
  mv "$file" "specs/$\{num\}-$\{name\}/README.md"
done

# 2. 回填元数据
lean-spec backfill --assignee --all

从外部系统迁移

对于 Linear、Jira、Confluence 或 Notion 等系统：

首先导出

从系统导出为 markdown 或 JSON
将导出放在目录中（例如，./exports/）
在导出的文件上运行迁移

# 从 Linear、Jira 等导出到 ./exports/
lean-spec migrate ./exports/

为什么没有直接 API 集成？

LeanSpec 故意不与外部系统 API 集成，因为：

安全性：不需要凭据管理
简单性：无需身份验证、API 密钥、速率限制
维护：外部 API 会变化、中断、需要更新
隐私：您的数据保持本地

导出工作流已建立良好，让您保持控制。

故障排除

问题：没有 git 历史可用

解决方案：手动设置时间戳或使用当前日期

# backfill 将对没有 git 历史的规范使用当前时间戳
lean-spec backfill --assignee --all

# 或手动设置
lean-spec update 001 --priority high

问题：重复序列号

解决方案：使用 lean-spec check 检测冲突

lean-spec check
# 通过手动重命名文件夹修复冲突

问题：内容格式不匹配模板

好消息：LeanSpec 很灵活！保持您的现有格式。

您不需要重写内容以匹配特定结构。LeanSpec 的第一原则是"意图优于实现"——只要规范清楚地传达意图，具体格式并不重要。

问题：迁移后关系损坏

解决方案：手动更新 depends_on 和 related 字段

# 为每个规范编辑 README.md 中的前置元数据
---
depends_on: [002, 005]
related: [010, 012]
---

# 验证关系
lean-spec deps 001

迁移时间估计

基于实际迁移：

源工具	规范数	时间	复杂度
spec-kit	20	5 分钟	✅ 简单
spec-kit	100	15 分钟	✅ 简单
OpenSpec	20	20 分钟	⚠️ 中等
OpenSpec	100	60 分钟	⚠️ 中等
ADR	20	45 分钟	🔴 复杂
ADR	100	3 小时	🔴 复杂

注意：时间包括回填和验证。复杂迁移可能需要手动调整。

获取帮助

需要迁移支持？

GitHub Issues：报告迁移问题
示例：查看规范 063 获取详细示例
命令帮助：运行 lean-spec migrate --help 或 lean-spec backfill --help

下一步

迁移后：

学习工作流：创建和管理规范
设置 AI 集成：MCP 集成
理解原则：第一原则
为您的团队配置：配置参考

快速概览​

按源工具划分的迁移复杂度​

GitHub spec-kit（最简单）✅​

OpenSpec（中等）⚠️​

ADR/RFC 集合（复杂）🔴​

lean-spec backfill 命令​

基本用法​

它提取什么​

示例输出​

使用 lean-spec migrate​

手动模式（默认）​

AI 辅助模式​

迁移检查清单​

迁移前​

迁移期间​

迁移后​

迁移系统提示​

常见源文件​

LeanSpec 使用​

迁移策略​

常见迁移场景​

场景 1：每个功能有多个文件的 spec-kit​

场景 2：具有单独目录的 OpenSpec​

场景 3：扁平 ADR 文件​

从外部系统迁移​

首先导出​

为什么没有直接 API 集成？​

故障排除​

问题：没有 git 历史可用​

问题：重复序列号​

问题：内容格式不匹配模板​

问题：迁移后关系损坏​

迁移时间估计​

获取帮助​

下一步​

快速概览

按源工具划分的迁移复杂度

GitHub spec-kit（最简单）✅

OpenSpec（中等）⚠️

ADR/RFC 集合（复杂）🔴

`lean-spec backfill` 命令

基本用法

它提取什么

示例输出

使用 `lean-spec migrate`

手动模式（默认）

AI 辅助模式

迁移检查清单

迁移前

迁移期间

迁移后

迁移系统提示

常见源文件

LeanSpec 使用

迁移策略

常见迁移场景

场景 1：每个功能有多个文件的 spec-kit

场景 2：具有单独目录的 OpenSpec

场景 3：扁平 ADR 文件

从外部系统迁移

首先导出

为什么没有直接 API 集成？

故障排除

问题：没有 git 历史可用

问题：重复序列号

问题：内容格式不匹配模板

问题：迁移后关系损坏

迁移时间估计

获取帮助

下一步