【openspec】存量项目中如何使用进行开发

将 OpenSpec 引入一个已经拥有大量代码的存量项目（Legacy Project），最忌讳的是"毕其功于一役"------试图一次性把所有旧代码都补齐规范。这不仅会消耗海量的 Token，还会因为缺乏上下文让 AI 产生严重幻觉。

在存量项目中，推荐采用"逐步蚕食、增量驱动"的策略，即：不动不补，动哪补哪。

以下是标准的落地实施指南：

1. 落地三部曲：从零到第一步

第一步：全局初始化

首先，像新项目一样，在项目根目录下安装并初始化 OpenSpec：

bash 复制代码

npm install -g @fission-ai/openspec@latest
openspec init

这会在项目中建立 openspec/ 目录并配置好 AI 的 Skills 与 Commands。此时，你的 specs/ 目录是空的，这完全没有关系。

第二步：建立系统"骨架"（Main Spec 鸟瞰图）

不要让 AI 去读几万行代码写细则。人类或 AI 应该先在 openspec/specs/ 下建立 1~2 个高层级的、概括性的 主规范文件。

例如，创建一个 openspec/specs/overview.md，只写大框架：

markdown 复制代码

# System Overview
本项目是一个基于 Python Fastapi 的电商后台系统。

## Core Modules
- Auth Module: 负责 JWT 鉴权与微信登录。
- Order Module: 负责订单创建、支付回调。

这个骨架的目的是给 AI 一个基本的"世界观"，让它知道自己在一个什么样的项目里。

第三步：开启"增量模式"（动哪补哪）

当收到新需求，或者需要重构某个旧模块时，正式启动 OpenSpec 工作流。

2. 存量项目开发的核心数据流

以"重构存量项目中的用户登录模块，增加手机验证码登录"为例，开发流程如下：

复制代码

[ 1. 触发变更 ] ──> 运行 `/openspec-propose` 创建变更单
                       │
                       ▼
[ 2. 逆向工程 ] ──> 引导 AI 去读与登录相关的【特定存量代码文件】
                       │
                       ▼
[ 3. 补齐局部 Spec ] ──> AI 理解后，在 `changes/` 提案中补齐该模块的规范契约
                       │
                       ▼
[ 4. 编码与验证 ] ──> 运行 `/openspec-apply`，AI 编写新代码并修改旧代码
                       │
                       ▼
[ 5. 局部变全局 ] ──> 运行 `/openspec-sync`，登录模块的规范被合入 `specs/auth.md`

关键细节：如何引导 AI 做"局部逆向工程"？

在第一步输入 /openspec-propose 时，你必须在提示词中明确指定老代码的范围，防止 AI 全盘瞎猜。例如：

/openspec-propose "为现有登录增加验证码功能。请重点参考现有的 src/auth/service.py 和 src/auth/router.py 里的登录逻辑，确保新方案不破坏原有的 JWT 签发机制。"

AI 收到指令后，会执行以下动作：

它是带着目的去读那两个老文件。
它会在新生成的 openspec/changes/xxxx.md 中，先把读出来的老登录逻辑写成规范（MODIFIED 标记），再把新验证码逻辑加进去。
这样，原本没有文档的老模块，借着这次修改的机会，在局部成功建立起了规范契约。

3. 存量项目落地军规（Best Practices）

🚫 错误做法 ：运行 openspec analyze . 企图让 AI 一键把整个项目的代码转成 markdown 规范。（Token 直接爆炸，且由于缺乏业务背景，写出来的全是废话代码注释）。

** Letting AI run wild is dangerous.**

针对存量项目，请务必遵守以下原则：

只写行为，不写实现：主规范（Specs）里记录的是"用户输入密码，系统返回 Token"，绝对不要把旧代码里的类名、数据库表名硬编码进 Specs。否则一旦代码重构，文档立马腐烂。
逐步蚕食（Gradual Adoption） ：随着项目的持续迭代，经历过 10 次需求变更后，系统最核心、最活跃的 10 个业务模块就会自然而然地在 openspec/specs/ 下建立起完美的规范。而那些几年都不动一次的死代码，就让它继续躺在历史里，不需要为其补写任何规范。
从测试倒推规范：如果旧代码很难读，可以先让 AI 运行现有的单元测试，或者让 AI 为旧代码写几个基本测试。通过测试用例（Given-When-Then）来倒推并总结出 Spec 规范，准确率会极高。

通过这种"增量演进"的方式，存量项目不仅能在不影响业务的前提下平滑引入 OpenSpec，还能借 AI 之手，逐步将团队头疼的"老破小代码"蚕食并改造成"有规范保障、可长久演进"的现代资产。