OpenSpec 与 Cursor 集成指南

本文档旨在为复杂系统（如数字孪生、平台架构、Web3 项目）提供一套工程级的 OpenSpec + Cursor 集成工作流。核心理念是将 Spec 作为唯一事实源（Source of Truth），利用 Cursor 的不同模式实现从设计到落地的精确控制。

核心理念

在引入 AI 辅助开发的场景下，特别是在中台或平台型项目中，必须建立严格的层级约束：

• OpenSpec: 法律条文（不可违背的事实源）
• Plan 模式: 施工方案（只设计，不动手）
• Agent 模式: 施工队（只执行，不决策）

Cursor 模式深度解析：Plan vs Agent

很多人混淆了 Cursor 的 Agent 和 Plan 模式，理解它们的本质区别是掌握本工作流的关键。

1. Plan 模式（“设计阶段 AI”）

本质: Plan 是一个“只思考、不动手”的模式。它的职责是拆解问题、规划步骤、标注依赖和风险。

• 能力边界:
  • ✅ 拆解问题、规划步骤
  • ✅ 架构拆分、技术选型
  • ❌ 修改代码、生成文件

适用场景: 新功能方案设计、架构拆分、多模块任务拆解。

典型输出:

目标：实现登录模块 步骤：1. 定义 API 规格; 2. 设计数据结构… 风险：Token 过期策略需确认…

2. Agent 模式（“执行型 AI 工程师”）

本质: Agent 是一个“长期执行者”，像是一个被雇佣的 AI 工程师。

• 能力边界:
  • ✅ 读写代码、新建文件
  • ✅ 跨文件修改、多轮自我校验
  • ⚠️ 容易发散，必须有明确约束

适用场景: 具体代码实现、Bug 修复、模块迁移。

最佳工作流：Plan + Agent 组合拳

单纯使用 Agent 容易导致代码失控，推荐采用 Plan -> Human Review -> Agent 的流水线。

1. Plan: 拆清楚事情。
2. Human: 确认 Plan 无误。
3. Agent: 严格按 Plan 执行。

推荐 Prompt 模板

Step 1: Plan 阶段

用 Plan 模式，
根据 specs/ 目录，
拆分实现步骤，不要写代码。

Step 2: Agent 阶段

切换到 Agent 模式，
严格按照已确认的 Plan 执行，
不得引入 Plan 外功能。
specs/ 目录是唯一事实源。

---

实战：旧项目重构流程

针对遗留系统的重构，切忌直接让 Agent “优化整个项目”。请遵循 “不翻车、不失控、可回滚” 的标准流程。

流程概览

阶段	动作	Cursor 模式	核心目标
Step 0	冻结旧代码	-	建立安全基线 (refactor/phase-1)
Step 1	反向抽 Spec	Plan	还原项目真实画像，明确“现状”
Step 2	架构重构蓝图	Plan	设计“目标架构”，明确数据/缓存策略
Step 3	模块级迁移	Plan	规划迁移批次 (Batching)
Step 4	影子重构	Agent	实现新代码，新旧共存
Step 5	验证与切换	Chat	验证行为一致性，逐步切换流量

关键步骤详解

Step 1: 反向抽 Spec (Reverse Engineering)

旧项目的真实逻辑往往隐藏在代码细节中。使用 Plan 模式阅读代码，反向总结核心业务模块、数据结构和隐含规则。

Prompt: “阅读当前项目代码，反向总结：1. 核心业务模块 2. 关键数据结构 3. 对外接口行为。不要提出优化方案，只做事实级总结。“

Step 2: 架构重构蓝图

在不改变业务行为的前提下，设计未来的系统结构。例如，将静态 JSON 数据迁移至数据库，引入 Redis 缓存等。

Prompt: “基于当前 specs，设计目标架构：1. JSON -> 数据库 2. 明确 Redis 缓存策略 3. 模块按领域拆分。保持业务行为不变。“

Step 3: 分模块 Agent 重构 (Shadow Refactoring)

影子重构是老项目最安全的方式。新建 auth_v2 模块，与旧 auth 模块并存，通过配置开关控制。

Agent 执行约束:

你是执行型 Agent。
目标：重构 auth 模块
约束：
- 保持现有对外行为不变
- 新建 auth_v2 模块，不修改原 auth
- 提供迁移验证点

避坑指南

1. 禁止 Agent “顺手优化”: 重构只做结构调整，不做功能升级。
2. 必须有 Spec: 哪怕是反向生成的 Spec，也必须作为 Agent 的执以依据。
3. 控制粒度: 一次只动一个模块，一次只做一个 Batch。

---

总结

Plan 解决“想对”，Agent 解决“做到”。 没有 Plan 的 Agent 是野狗，有 Plan 没 Agent 是 PPT。 重构旧项目时，Plan 是你的“CT 扫描”，Agent 是“手术刀”。