将 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 之手，逐步将团队头疼的"老破小代码"蚕食并改造成"有规范保障、可长久演进"的现代资产。