---
name: project-reconstruction
description: 基于已有项目做重构/新建（搬家不重写）的完整流程 Skill。当用户需要从现有混乱项目迁移到干净新项目时激活，引导完成：新项目文件夹 → PM功能清单 → 技术架构+红蓝推演（回写闭环）→ Cursor规范配置 → 分Phase构建。区别于 role-技术架构师（后者设计新技术方案）：本 Skill 是迁移型，先盘点已有资产，再设计去哪里放。触发词：「基于已有项目重构」「重构方案」「新建项目并迁移」「搬家不重写」「从零开始但复用现有代码」「项目架构整改」。
---

# 基于已有项目重构 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 的标准格式：
```markdown
### 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`