基于 Claude Code 驱动的老项目改造方法论

核心理念

1. 先确认再动手 — 避免做已存在的功能

2. 先设计再实现 — 需求和方案定稿后才写代码

3. 按层次推进 — 类型 → API → 状态 → 组件 → 页面

4. 每层验证 — 构建 + lint 通过才进入下一层

5. 关键决策人工把关 — AI 自主跑，但 4 个节点必须停

---

规模分级

进入流程前先判定需求规模，不同规模走不同流程：

判定标准（三维度组合）

维度	S 级	M 级	L 级
文件影响	1-2 个文件	3-8 个文件	8+ 或跨模块
状态变更	无新状态	有新状态	新页面级状态
已有代码	纯新增	改已有组件	改公共组件/跨应用

判定规则：任一维度命中高级别，整体取高级别。

各级必做步骤

步骤	S 级	M 级	L 级
第零步：现状确认	必做	必做	必做
第一步：拆需求（八维）	跳过	简化（目标+边界）	完整
第二步：拆方案	跳过	数据流设计	完整
第三步：后端对接	确认接口即可	文档+curl	文档+curl+mock
第四步：前端实现	直接实现	按层次推进	按层次推进
第五步：文档回灌	跳过	CLAUDE.md（如有新约束）	CLAUDE.md + docs/

---

完整流程（L 级）

第零步：现状确认

目的：避免重复造轮子。AI 扫代码无法替代人手验证。

执行：

1. 点产品 — 打开生产/测试环境，按需求路径点一遍，确认功能是否存在

2. 搜代码 — 用关键词搜索项目代码，排查是否有写了一半没上线的半成品、藏在 feature flag 后面的实现、已有但未接入路由的组件

   产出：一句话现状结论（"功能不存在" / "部分存在，xxx 已有" / "功能已存在，需改为优化/重构方向"）

---

第一步：拆需求（八维拆解）

从"一句话需求"拆解为结构化需求文档。

八个维度

#	维度	说明
1	业务目标	一句话描述这次做什么、为谁做
2	用户场景	典型场景 + 用户痛点
3	接口契约	方法、路径、入参、返回结构、错误码（后端提供或协商）
4	边界场景清单	至少 8 条 edge case，每条标"基于代码推断"或"待产品决策"
5	老项目约束	CLAUDE.md 禁区和历史包袱中相关项，标明来源
6	不在这次范围里的事	先列候选，人审核后砍掉或留到下期
7	交互/UI 规格	页面状态（loading、empty、error、success）、操作流程、动效、响应式
8	跨应用影响	微前端通信变更、共享状态变更、submodule 变更、组件库升级

人工审核点（决策停点 1/4）

审核三件事后反馈：

• 业务目标方向是否正确

• 边界场景的产品决策

• 不在这次范围里的最终裁定

---

第二步：拆方案

产出内容

1. 涉及链路 — 从入口到数据层的完整链路，表格标注每个节点（文件、状态、关键逻辑）

2. 改造点清单 — 编号 P01、P02...，标注类型（新增/修改）+ 文件路径 + 一句话改什么

3. 数据流设计 — Store/Props/Emit 链路、API 层封装方式、TypeScript 类型定义

4. 影响范围 — 每条标"高/中/低"风险

5. 改造步骤与顺序 — 按层次排序，标明依赖关系

6. 待审核的关键决策点 — 集中列出，方便人 review

人工审核点（决策停点 2/4）

审核方案中的状态/数据流设计决策：

• Store 结构是否合理

• Props 传递层级是否过深

• 是否需要新增 adapter

---

第三步：后端对接

三步对接

1. 确认接口文档 — 获取 Swagger/手写文档，确认入参、返回结构、错误码

2. curl 验证 — 在测试环境实际调接口，特别关注：

   • null vs 空数组 vs undefined

   • 嵌套结构层级

   • 分页/列表的空态

   • 错误码实际表现

3. 约定 mock 方案（后端未完成时） — 约定返回结构，前端用 mock 数据并行开发

Mock 策略

• 接口返回结构写入 TypeScript 类型文件作为契约

• mock 数据放在独立文件，联调时删除

• 联调验证节点：后端完成后必须用真实接口跑一遍确认

---

第四步：前端实现

锁住现有行为（修改已有组件时）

修改已有组件/函数前，必须先做：

1. grep 出所有调用方

2. 记录现有 props/emit/slots 契约

3. 记录作为基线："这些不能破坏"

   纯新增文件跳过此步。

人工审核点（决策停点 3/4）

确认已有组件的调用方和影响范围是否如预期。

按层次实现

类型定义 → API 层 → Store/状态 → 组件 → 页面集成

每层完成后执行验证：构建通过 + lint 通过，才进入下一层。

层	做什么	验证
类型定义	接口类型、组件 Props 类型、Store 状态类型	tsc 编译通过
API 层	封装接口调用方法，对齐项目请求层风格	构建 + lint
Store/状态	Pinia store 或组件内状态，数据流逻辑	构建 + lint
组件	UI 组件实现，使用项目组件库	构建 + lint
页面集成	路由接入、菜单配置、组装组件	构建 + lint + 浏览器验证

人工审核点（决策停点 4/4）

页面集成完成后，人工浏览器验证：

• 打开页面按需求操作一遍

• 对照改造前截图确认无视觉回归

• 确认交互流程完整

阻塞处理策略

错误类型	处理方式
构建/lint 报错	AI 自主修复，不限次数
已有组件契约冲突（改 props 导致其他调用方报错）	立刻停，升级给人决策
接口实际返回与文档不符	停，联系后端确认

---

第五步：文档回灌

改造完成后同步更新：

1. CLAUDE.md — 如果产生了影响所有未来改造的新约束，写进项目 CLAUDE.md

2. docs/ 任务文档 — 更新对应任务文件夹的 README.md，记录：背景、进度、卡点、解决方案

   判断标准：影响所有未来类似改造的 → CLAUDE.md；只这一次的特殊处理 → 任务文档。

---

Git 工作流

三个 commit 节点：

节点	时机	commit 内容
1	方案定稿后	docs/ 下的需求文档和方案文档
2	每层验证通过后	该层的代码变更
3	全部完成	提 PR，关联需求文档

---

提示词模板

分步模板

提示词 0：现状确认

我要做一个新需求："[一句话需求]"。
​
在我去浏览器确认之前，先帮我搜一下代码：
- 用关键词 [xxx] 搜索项目，看是否有相关的已有实现、半成品、或未接入路由的组件
- 如果找到相关代码，告诉我文件路径和当前状态
​
等我浏览器确认后再继续。

示例：

我要做一个新需求："给企业详情页加一个关联企业图谱展示"。
​
在我去浏览器确认之前，先帮我搜一下代码：
- 用关键词 relation-graph、enterprise-graph、关联图谱 搜索项目，看是否有相关的已有实现、半成品、或未接入路由的组件
- 如果找到相关代码，告诉我文件路径和当前状态
​
等我浏览器确认后再继续。

---

提示词 1：八维拆解

我有一个新需求：[需求描述]。
我已经确认：[现状描述，如"功能不存在" / "部分存在，xxx已有"]。
​
读 docs/ 下资产 + CLAUDE.md，再扫代码里相关实现，按以下八维写需求文档草稿：
​
1. 业务目标(一句话)
2. 用户场景(典型场景 + 痛点)
3. 接口契约(方法、路径、入参、返回、错误码，对齐项目现有风格)
4. 边界场景清单(至少 8 条 edge case，每条标"基于代码推断"或"待产品决策")
5. 老项目约束(CLAUDE.md 禁区和历史包袱里相关的，每条标来源)
6. 不在这次范围里的事(先列候选)
7. 交互/UI 规格(页面状态、操作流程、动效、响应式)
8. 跨应用影响(微前端通信、共享状态、submodule、组件库)
​
输出 markdown，保存到 docs/requirements/[feature-name].md。

示例：

我有一个新需求：给企业详情页加一个关联企业图谱展示。
我已经确认：功能不存在，但 relation 模块下有关联关系查找的接口和页面。
​
读 docs/ 下资产 + CLAUDE.md，再扫代码里 relation、graph、图谱相关实现，按以下八维写需求文档草稿：
... (同上)

---

提示词 2：人审核 + 定稿

我对 docs/requirements/[feature-name].md 做了以下判断：
​
业务目标修正：[修正内容或"无修正"]
边界场景的产品决策：
- [E0x]：[决策]
- ...
不在这次范围里的最终决策：
- 砍掉：[列表]
- 留到下期：[列表]
​
按以上判断更新文档，整理为正式 PRD 格式。

---

提示词 3：拆方案

基于 docs/requirements/[feature-name].md，按以下步骤拆方案：
​
1. 摸链路：找出涉及的完整链路，每个节点说明文件、状态(现有/新增/修改)、关键逻辑
2. 列改造点：拆成 P01、P02... 每条标类型 + 文件路径 + 一句话改什么
3. 设计数据流：Store/Props/Emit 链路 + API 层封装 + TypeScript 类型定义
4. 说影响范围：每条标高/中/低风险
5. 说步骤顺序：按层次排序（类型→API→Store→组件→页面），标依赖
6. 集中列出"待审核的关键决策点"
​
保存到 docs/requirements/[feature-name]-solution.md。

---

提示词 4：后端对接确认

基于 docs/requirements/[feature-name]-solution.md 中的接口契约，做以下对接：
​
1. [后端已完成时] 在测试环境 curl 以下接口，确认返回结构：
   - [接口列表]
   重点关注：null/空数组、嵌套层级、错误码实际表现
​
2. [后端未完成时] 基于约定的接口契约，生成 mock 数据文件：
   - TypeScript 类型文件作为契约
   - mock 数据独立文件，后续联调时删除
​
输出对接结论：哪些接口已验证通过、哪些需要 mock 并行。

---

提示词 5：锁住现有行为

基于 solution.md 的改造点，这次需要修改以下已有文件：
[文件列表]

改动前先做：
1. grep 出每个文件/组件的所有调用方
2. 记录现有 props/emit/slots 契约
3. 输出"不能破坏"的基线清单

等我确认基线后再开始实现。

---

提示词 6：按层实现

基于 solution.md 和确认的基线，按层次开始实现：

第一批：类型定义
- [P01、P02...]
- 完成后跑构建 + lint 确认通过

第二批：API 层
- [P03...]
- 完成后跑构建 + lint 确认通过

第三批：Store/状态
- [P04...]
- 完成后跑构建 + lint 确认通过

第四批：组件
- [P05、P06...]
- 完成后跑构建 + lint 确认通过

第五批：页面集成
- [P07...]
- 完成后跑构建 + lint 确认通过

每批完成汇报结果，全部通过后告诉我去浏览器验证。
阻塞规则：
- 构建/lint 报错自主修复
- 已有组件契约冲突立刻停
- 接口返回与预期不符立刻停

---

提示词 7：文档回灌

前端改造完成，把这一轮新发现回灌到文档：
1. CLAUDE.md：加项目级新约束（如有）
   判断标准：影响所有未来类似改造的写进 CLAUDE.md，只这一次的留在 solution.md
2. docs/ 任务文档：更新 README.md 记录背景、进度、卡点、解决方案

输出每份文件的改动 diff。

---

一键工作流模板

整段粘贴到 Claude Code，关键决策点会停下来等你输入：

我要做一个新需求：[一句话需求]
完整跑通前端开发流程，全程自主推进，遇到关键决策点停下来等我。

第零步：现状确认（必做，不能跳）
- 搜代码看有无已有实现/半成品
- 提醒我打开浏览器确认
- 等我确认后才进下一步

第一步：拆需求
- 读 docs/ + CLAUDE.md + 现有代码
- 按八维写需求文档草稿到 docs/requirements/<feature>.md
- 停下来等我反馈业务目标、边界决策、范围决策
- 我反馈完后整理为正式 PRD

第二步：拆方案
- 摸链路 + 列改造点 + 设计数据流 + 说影响 + 说步骤
- 整合成 solution.md，第 6 节"待审核决策点"单独抽出来
- 停下来等我审核状态/数据流设计决策
- 我反馈完后更新 solution.md

第三步：后端对接
- 确认接口文档，如后端已完成则 curl 验证
- 如后端未完成则生成 mock 文件并行开发
- 接口返回与文档不符则停下来告诉我

第四步：前端实现
- 修改已有组件前先 grep 调用方、记录契约基线
- 停下来等我确认影响范围
- 按层次实现：类型→API→Store→组件→页面
- 每层跑构建 + lint 验证
- 全部通过后停下来等我浏览器验证

第五步：文档回灌
- 更新 CLAUDE.md（如有新约束）和 docs/ 任务文档

自主原则：
- 每步跑完自己 review 输出质量，不合格自己重跑
- 构建/lint 报错自主修复
- 已有组件契约冲突立刻停
- 接口返回与预期不符立刻停
- 不要重构现有代码，只调用
- 关键决策点停下来等我，不要替我拍板

跑完输出 summary：列每个产出文件 + 我应该重点 review 的地方。

---

关键原则速查

原则	说明
先点产品再动手	AI 扫代码无法发现"功能已存在"，必须人手验证
断言凭实际不凭应该	验证基于真实行为，不基于预期
不重构现有方法，只调用	控制影响范围，避免牵一发动全身
改动前锁行为	修改已有组件前记录调用方和契约基线
每层验证	构建 + lint 通过才进入下一层
关键决策人工拍板	4 个停点 AI 不能替你做
文档回灌	新约束写回 CLAUDE.md，不让教训白费