老系统现代化（Legacy Modernization）
把一次高风险的老系统改造，拆成可验证、可回退、可交接的小步，并以"入口枚举基线 + 对抗式审查 + 差距台账"对抗漏需求、漏审查、漏交付三大风险。
> v2.0 变更：更名（与业界"应用现代化 / 老系统现代化"术语对齐）；新增起点评估与迁移策略选择（重写/平移/绞杀者）、技术栈选型手册（五步流程+评分矩阵+决策点 checklist+反模式）、阶段 9 终局审计（四维差距表+差距台账闭环）、对抗式审查（双 AI 交叉+入口反推+审查盲区清单）、入口枚举基线（五维盘点+防漏需求）。
> v2.1 变更：①行为基准采集——阶段 0 留档老系统关键业务流真实行为样本，作为阶段 4/9"行为等价"审计的对照物；②数据迁移与校验——阶段 3 随批同步搬迁数据（幂等/可重跑/断点续传 + 行数/抽样/关键字段校验）；③双跑观察期——Contract 前新旧并行对照；④回退演练——回退预案必须实练一次；⑤止损条件——策略 ADR 写明止损线；⑥扫描成本纪律——统计用命令计数、抽样精读、并行子代理、产出上限。
三大风险与内置对策
| 风险 | 表现 | 技能内置对策 |
|---|---|---|
| 需求分析漏项 | 老系统功能没进清单，迁移无从谈起 | 阶段 0 起点评估 + 五维盘点 + 入口枚举基线；阶段 1 需求覆盖校验 |
| 审查漏检 | AI 审查没发现的问题 | 阶段 4 对抗式审查（双 AI 交叉 / 入口反推 / API 面 diff / 抽样深挖）+ 审查盲区清单 |
| 交付与原系统差距大 | 代码在，但行为 / 权限 / 性能不对等 | 阶段 9 终局审计（四维差距表）+ 差距台账闭环 |
何时使用
适用（用户意图命中即启动本技能）：
- "把老系统迁移 / 重写 / 升级到新技术栈"
- "老项目架构换骨、分层重构"
- "老项目技术栈怎么选 / 值不值得重构"
- "评审或制定一份迁移 / 重构方案"
- "检查一次重构完成度、新旧系统功能差距"
不适用：
- 零散 bug 修复、性能调优 → 交给对应专项技能
- 全新项目（绿场，无历史包袱）→ 直接走设计类技能
- 改动量小、不值得改造的项目 → 只做局部修改
核心原则（贯穿全程）
- 老库只读：老代码是"业务事实参考"（接口语义、规则、边界 case），不是可搬运的资产；一切改动只发生在新区。
- 策略先行，选型有据：动手前做起点评估（源码/环境/文档/知识四要素）决定改造策略（重写/平移/绞杀者），技术栈选型走"评分矩阵→原型验证→ADR 冻结"，不口头定栈、不追新守旧。
- Expand-Contract，分批搬迁，止损有界：逐批推进，一批 = 一个能力域（规模控制在可独立验证与回退范围）；旧系统未拆完前天然是回退安全网；改造前在 ADR 定止损线（如 P0 连续 N 批验收失败、核心性能劣化超阈值 → 暂停并回退），不无限投入。
- 量化验收：完成度以"代码级量化对照"为准，不以口头或文档自述为准。
- 文档即上下文：规范、方案、词汇表、记忆索引先行；AI 协作 / 多会话场景下，文档是唯一可靠的上下文接力。
- 完整性优先：一切审查以"入口枚举基线"为准（老系统菜单/路由/表/任务/接口的全量清单），不以新代码自述为准。
- 双重复核：盘点基线、覆盖率、终局审计三个关键结论，必须由两个独立视角交叉验证（如两个互不参考的 AI 会话各做一遍再对账），防止单模型漏检。
总流程
| 阶段 | 动作 | 验收 | 自检 |
|---|---|---|---|
| 0 盘点 | 起点评估（源码/环境/文档/知识）→ 定改造策略（ADR 含止损线）；五维盘点 + 行为基准采集，缺源码走反编译 | 策略 ADR + 入口枚举基线 + 行为基准样本 | 盘点产出后 + 双重复核 |
| 1 设计 | 技术栈选型（评分矩阵→PoC→ADR 冻结）+ 需求/架构/数据库/迁移方案/规范/页面映射/测试计划 | 8 份文档冻结 + 选型 ADR + 需求覆盖校验通过 | 文档冻结后 |
| 2 Expand | 新工程骨架 + 数据模型 + 鉴权 + 一个端到端闭环 | 旧系统行为不变，地基可用 | 端到端闭环跑通后 |
| 3 Migrate | 按批次拓扑排序逐批实现（功能 + 数据搬迁） | 每批过 DoD + 数据校验 | 每批收尾独立自检 |
| 4 量化复查 | 对抗式审查：覆盖率矩阵 + 占位扫描 + 行为差距 | 真实完成度 + P0–P3 缺口 | 产出后 + 双 AI 交叉 |
| 5 GAP 补齐 | 按优先级补缺口 | 逐项过 DoD | P0 闭环后 |
| 6 测试固化 | 用例分层、种子数据、性能基线 | 体系可重跑 | 全部就绪后 |
| 7 Contract | 双跑观察期（新旧并行抽样对照）→ 旧系统归档、零旧引用、文档收尾 | 三件套验收 + 双跑对照零差异 | 全量验证后（不可逆，双人复核） |
| 8 部署移交 | 部署清单、干净环境演练、回退演练、遗留台账 | 接手者可直接开工 + 回退预案已实练 | 演练完成后 |
| 9 终局审计 | 四维差距审计 + 差距台账闭环 | P0 差距清零，台账随包移交 | 审计后 + 双重复核 |
各阶段详细动作、检查项与退出条件见 references/phase-playbook.md；技术栈选型见 references/tech-stack-selection.md；老系统只有 jar 时见 references/decompilation-playbook.md。
全局纪律（任何阶段都遵守）
- 迁移中不"顺便重构"：发现老逻辑疑点记 TODO，不展开。
- 提交纪律：每批独立提交，注明参考来源；代码与文档分开提交；初始提交按目录拆分，避免超大推送。
- 文档闭环：规范与实现不一致时，改代码或改文档二选一当场闭环，不留暗账。
- 迁移脚本只增不改：版本化迁移脚本按序追加，老脚本永不回改。
- 量化优先：所有"完成 / 缺失 / 覆盖"结论必须带数字、带口径、带来源。
- 扫描成本纪律：统计用命令行计数（如
grep -c）而非逐文件通读；每能力域抽样精读 3~5 个代表文件；大仓库用并行子代理探索；单次产出设上限（报告候选 / 缺口卡数量）。 - 回写知识：每阶段收尾更新词汇表、决策记录与记忆索引（写入前需用户确认）。
- 每阶段自检留痕：对照该阶段"退出条件"逐项勾选并写入台账，未通过不得进入下一阶段。自检执行标准见 references/self-check-methodology.md。
验证网（交付质量的生命线）
| 层 | 手段 | 防什么 |
|---|---|---|
| 架构规则 | 架构约束测试（分层约束、禁止直调框架 API 等） | 架构腐化 |
| 静态红线 | lint / 编码规范门禁（行数、方法数、命名） | 代码膨胀、风格漂移 |
| 单元测试 | 每批正常 / 边界 / 异常三路 | 逻辑回归 |
| 冒烟脚本 | 登录 → 主链路 → 落库校验 → 负向用例，逐域扩展 | 交付失真 |
| 覆盖率复查 | 新旧代码量化矩阵 + 入口反推 | 自报失真 |
| 对抗式审查 | 双 AI 交叉 + 审查盲区清单 | 漏检 |
| 性能基线 | 关键场景 P50 / P95 / P99 / RPS | 性能劣化 |
| 差距审计 | 四维差距表（功能 / 行为 / 权限 / 性能）+ 台账闭环 | 与原系统差距失控 |
| 人工验收 | 验收清单 + 页面 / 接口测试指南 | 定义"完成" |
关键术语
- DoD（Definition of Done）：一个批次"算完成"的验收标准集。
- 能力域：老系统的业务分区，迁移批次按它切分。
- 接缝（seam）：可替换依赖的边界，改造后应成为稳定接口。
- 占位实现：留了接口没有实现、假数据、TODO 直返等"看起来完成"的代码。
- 入口枚举基线：老系统全部对外入口（菜单、路由、表、定时任务、接口、子应用）的清单，是需求与审查的唯一基准。
- 对抗式审查：假设"存在漏检"而设计的审查方法（交叉验证、反向反推、抽样深挖），而非单向扫描。
- 起点评估：用源码可用性、环境可运行性、文档完整度、领域知识可得性四要素决定改造策略。
- 绞杀者模式（Strangler Fig）：新旧系统长期共存、按入口逐段替换的策略；与全量重写、平移重构并列的三种改造路径。
- 回退安全网：旧系统未拆前 = 天然回退网；每批独立提交 = 单批回退能力。
参考资料（按需加载，勿全量读）
- references/phase-playbook.md —— 九阶段详细动作、检查项与退出条件
- references/tech-stack-selection.md —— 技术栈选型手册（五步流程 + 评分矩阵 + 决策点 checklist + 反模式）
- references/decompilation-playbook.md —— jar 反编译补源码完整流程
- references/self-check-methodology.md —— 阶段自检方法论（双轴审查 + 严重程度 + 结论判定 + 补救闭环）
- references/templates.md —— 迁移方案表、DoD、记忆索引、词汇表、冒烟骨架、盘点矩阵、起点评估矩阵、选型评分矩阵、审查盲区清单、差距台账、自查清单、数据迁移校验清单等模板
