基于已有项目重构 Skill（project-reconstruction）

版本：v1.1 · 2026-03-23

适用场景：现有项目技术债积累严重，但 90% 业务逻辑是对的，只是放错了地方。 核心原则：迁移单位是「目录结构和模块边界」，不是重写业务逻辑。

关联角色：

• role-产品经理（Step 2：功能清单）
• role-技术架构师（Step 3：框架设计）
• role-审核者-系统破坏（Step 3.5：红蓝推演）
• skill-designer（Step 4：Cursor 规范配置）

---

知识导航表（激活前按顺序读取）

层级	文档	用途
D0	现有项目的 产品经理/产品定义.md	了解当前产品是什么
D1	现有项目的 产品经理/开发计划.md	了解哪些功能已实现
D2	现有项目的 技术架构师/*.md（若有）	了解现有技术积累
D3	_内部总控/认知结构/L1_系统性文档/系统架构思维维度/	架构设计的认知根

---

激活后立即执行

Step 0：评估是否适合重构（而非增量整改）

与用户确认以下判断（全部 Yes 才进入重构流程）：

□ 现有项目的技术债是「结构性的」（不是几个 Bug），改一个地方要追 3-5 个依赖方？
□ 业务逻辑大体正确，问题主要在「东西放错了地方」？
□ 可以接受约 1-2 周的迁移期（新旧项目并行）？
□ 核心数据（DB/文件系统）可以无损迁移？

若有 No → 评估增量整改是否更合适，向用户说明。 若全部 Yes → 继续 Step 1。

---

Step 1：新建项目文件夹 + 规范结构

在 项目群/ 下新建：{新项目名}/
├── 0_迁移决策/
│   └── 重构决策.md        ← Step 1 完成后写入
├── 1_产品定义/
│   └── 功能清单.md         ← Step 2 输出
├── 2_技术架构/
│   ├── 技术框架.md         ← Step 3 输出
│   └── 红蓝推演.md         ← Step 3.5 输出（必须回写到技术框架）
├── 3_开发计划/
│   └── 开发计划.md         ← Step 5 输出
├── 开发规范.md             ← Step 4 输出
└── README.md              ← 阅读顺序说明

写入 0_迁移决策/重构决策.md，包含：

• 为什么选重构而非增量整改（具体原因，不是套话）
• 哪些代码直接 copy，哪些需要重写（按文件级估计）
• 数据迁移策略（DB/文件系统）
• 风险评估（功能遗漏风险 / 数据迁移风险 / API兼容风险）

---

Step 2：PM 视角——功能清单（角色：role-产品经理）

目标：让「怕遗漏」的风险变成可验证的清单

执行以下操作：

1. 读取 D0（现有产品定义）和 D1（开发计划），提取所有功能
2. 按功能域分组，为每个功能标注状态：
   • ✅ 已实现且验证通过
   • ⚠️ 已实现但有已知缺陷（记录缺陷描述）
   • 🔄 正在开发中
   • ⏳ 规划中（明确需求但未实现）
   • ❌ 废弃（设计过但不再做）
3. 为功能清单中每个功能分配优先级（P0/P1/P2/P3）

输出：1_产品定义/功能清单.md

验收：用户确认功能清单无遗漏（重点检查 ✅ 的功能是否都在新框架里有对应位置）

---

Step 3：技术架构师视角——新框架设计（角色：role-技术架构师）

目标：设计「第一天就是对的」的架构，然后把旧代码搬进来

执行顺序（不可跳过）：

3a. 第一性原理推导

先定义核心数据模型（不看旧代码），回答：

这个系统的核心实体是什么？它们之间是什么关系？
每个实体的生命周期是什么？谁拥有谁？

3b. 模块切片（从依赖关系推导，不从旧项目目录推导）

按 Slice 依赖层次从底向上设计：

Slice 1（最底层，无依赖）→ Slice 2 → ... → Slice N（最上层）
每个 Slice：
  - 职责一句话
  - 对外接口（输入/输出）
  - 内部不对外暴露的内容
  - 与其他 Slice 的依赖关系

3c. 目录结构（从切片推导，不从旧项目复制）

每个 Slice 对应的目录，目录名应该直接体现 Slice 的职责。

3d. 关键接口定义（代码级，能直接实现的精度）

对每个 Slice 边界，写出 Python/TypeScript 接口定义（方法签名 + 一句话说明），确保：

任何工程师看到接口定义，可以不问任何问题直接实现

3e. 技术积累对应（读旧项目代码）

读现有项目的代码，对每个新框架模块，找到旧项目中对应的实现，标注：

[新框架模块] ← 来自 [旧项目文件/函数]（直接 copy / 微调 / 重写）

3f. 设计决策记录（ADR）

任何非显而易见的设计选择，写 ADR：

ADR-NN：为什么选X而非Y
决策/原因/代价/验证方法

输出：2_技术架构/技术框架.md

---

Step 3.5：红蓝推演（角色：role-审核者-系统破坏）

⚠️ 这步是强制的，不是可选的

对 Step 3 输出的技术框架，执行安全/稳定性/可演化性攻击：

至少覆盖以下场景：

安全类：用户可控的输入如何攻击系统？（路径穿越/注入/越权）
并发类：多个请求同时操作同一资源会怎样？
一致性类：操作中断时，系统数据是否还自洽？
边界类：空状态/超大文件/特殊字符如何处理？
迁移类：旧数据迁入后，新系统能正确读取吗？

必须闭环：

发现问题（R编号）
    ↓
在技术框架里写修复（标注「来源：红蓝 Rx」）
    ↓
在红蓝报告里标注「已回写 ✅」
    ↓
在开发计划里写对应的单元测试（test_Rx_xxx）

⚠️ 禁止：写完红蓝报告就停。必须确认每个发现都已回写到技术框架。

输出：2_技术架构/红蓝推演.md（含回写状态表）

---

Step 4：建立项目规范（Cursor 规范层）

⚠️ 规范建在主工作区，不是子项目

规范文件建在 被激活的主 Cursor 工作区，不是新项目的子目录，因为 AI 始终在主工作区工作。

4a. 开发规范文档（写在新项目目录里，供人读）

{新项目}/开发规范.md 包含：

• Phase 执行门槛（完成条件 = 测试通过，不是「基本完成」）
• 代码约束（哪些做法被禁止，来自红蓝推演的发现）
• 测试分层规范（单元/Layer0/Layer1 各自的责任边界）
• 文档自洽规范（技术框架是单一真源）
• AI 辅助开发规范（AI 不自决架构，只提方案等用户确认）

4b. Cursor Rule（写在主工作区）

在主工作区 .cursor/rules/ 下新建 1-3 个 project-specific Rule：

{项目名}-arch-guard.mdc（alwaysApply: false，触发词为项目名）：

• 本项目的架构约束（来自技术框架的禁止项）
• Phase 完成门槛
• 文档同步要求

注意：Rule 的 alwaysApply: true 仅用于系统级全局约束。项目级 Rule 用 description + 触发词激活，避免 context 膨胀。

---

Step 5：分 Phase 开发计划（开发计划.md）

按技术框架的 Slice 层次，从底层向上规划 Phase：

Phase 0：项目脚手架（目录结构 + 第一个 /health 端点）
Phase 1：Slice 1+2（最底层两个 Slice）
Phase 2：Slice 3+4
...
Phase N：数据迁移 + 切流量

每个 Phase 的标准格式：

### Phase N | ⬜ | [描述]

**目标**：[一句话，用户体感的变化]

**任务清单**（逐一勾选）：
- [ ] [具体任务，包含文件名]

**测试**（在任务完成后运行）：
- [ ] pytest tests/unit/test_xxx.py → X/X PASS
- [ ] integration_test.py --layer0 → X/X PASS

**验收**（人工确认，不可省略）：
- [具体的用户操作，不是「功能正确」这种模糊表述]

关键约束：

• Phase 顺序 = Slice 依赖顺序（不能跳过前置 Phase）
• 每个 Phase 的验收必须包含 Layer 0 测试通过证明
• Phase 标记为 ✅ 之前，必须已更新功能清单的对应项状态

输出：3_开发计划/开发计划.md

---

Skill 完成标准

本 Skill 执行完毕时，以下文档必须全部存在且内容完整：

文档	最低内容要求
重构决策.md	有具体原因，不是套话；有代码级迁移策略
功能清单.md	覆盖现有所有功能，每个有状态和优先级
技术框架.md	接口定义到方法签名级别；有技术积累对应表；红蓝发现已回写
红蓝推演.md	有回写状态表（每个Rx标注已回写/接受风险）
开发规范.md	有Phase完成门槛；有代码约束（可执行，不是原则）
开发计划.md	每Phase有具体任务+测试+验收
主工作区 Rule	至少一个project-specific Rule 在 .cursor/rules/ 下

---

常见失败模式

失败模式	根因	预防
红蓝推演写完就存档，没有回写	把推演当「存档」而非「设计迭代」	Step 3.5 明确要求每个Rx在框架里有对应
新框架「参考」旧项目目录，导致新项目和旧项目结构一样	Step 3b 没有先做第一性原理，直接看旧目录	Step 3a 必须先于 Step 3b（不看旧代码推导切片）
Rule 建在子项目目录，AI 工作时不自动激活	不理解 Cursor 的 Rule 生效范围	Step 4 明确指出 Rule 建在主工作区
Phase 完成但功能清单没更新	文档同步被遗忘	开发规范第五章 + doc-sync Rule
重写而非搬家（代码量翻倍）	没有在迁移计划里标注「直接copy」	重构决策.md 必须有文件级迁移策略
登录后全站 API 401（请求无 Authorization）	前端 localStorage 读写 token 的 key 跨文件不一致（如 api.ts 读 A、AuthContext 写 B）	迁移前 grep 全项目 localStorage.getItem/setItem，统一 key 并写入开发规范
后端 ModuleNotFoundError（旧 import 路径）	文件迁入新包/目录后，模块内部仍 from routers.xxx 等旧路径，未随物理位置更新	批量 grep 旧路径前缀，系统性替换 import；移动文件后复查该文件及调用方
前端调 API 404（端点不存在或路径错位）	仅 copy 功能代码，未对照旧后端完整路由表；路径前缀（如 /cognition）或整段路由遗漏	Phase 0 脚手架阶段列出旧项目全部注册路由，与新项目对照；缺失则补兼容端点或统一前后端契约

---

变更记录

v1.0 — 2026-03-22 — 初始创建

触发事件：tashan-openbrain_myagent 项目因架构债务积累（workspace 隔离失效、npc-content 外置、sources_dir 安全漏洞），决定创建 tashan-openbrain_v2 干净重建。本次执行过程（PM→架构师→红蓝→规范→计划）被提炼为通用 Skill。

核心经验：

• 红蓝推演必须有回写闭环（不是存档）
• Cursor Rule 必须建在主工作区（不是子项目目录）
• 功能清单先行（防止迁移遗漏），技术框架后行（先第一性原理再看旧代码）

验证状态：✅ 已验证（tashan-openbrain_v2 完整走完本流程）

v1.1 — 2026-03-23 — 常见失败模式补充（v2 迁移实战）

根因：tashanbrain v2 迁移实战中出现 localStorage key 分裂、模块搬迁后 internal import 未更新、前后端路由不对照三类问题，原有「常见失败模式」未覆盖。

经验核心：复制代码不等于行为一致；token key、import 路径、HTTP 路由必须在迁移清单中可 grep、可对照。

修改内容：

• 「常见失败模式」表格新增 3 行：localStorage token key 一致性、平台/模块迁移后 import 批量校正、Phase 0 旧路由清单与前后端契约对照。

验证结果：

• 正向验证：下次迁移类任务中，执行者应能按表内「预防」列执行检查项 → 🔵 待验证

验证状态：🔵 待验证

备份路径：history/SKILL_v1.0_20260323.md