TashanGKD 基于已有项目重构 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-产品经理）
目标：让「怕遗漏」的风险变成可验证的清单
执行以下操作：
- 读取 D0（现有产品定义）和 D1（开发计划），提取所有功能
- 按功能域分组，为每个功能标注状态：
- ✅ 已实现且验证通过
- ⚠️ 已实现但有已知缺陷（记录缺陷描述）
- 🔄 正在开发中
- ⏳ 规划中（明确需求但未实现）
- ❌ 废弃（设计过但不再做）
- 为功能清单中每个功能分配优先级（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