把 15 个模块、3412 个文件、73 万行的遗留内部系统，
用 AI 原生方式重写一遍

Section 00

00摘要：十一条核心论断

这份手册的每一章都服务于下面某一条论断。论断是可证伪的：如果你的系统在某一条上不成立，那一章的做法就该改或跳过。只读这一页，你也应该能判断自己要付出什么代价。

1. 73 万行不是起点，是待压缩的输入。长时间演化的企业级 Java 系统里，未使用或已死的代码占到相当比例：Romano 与 Scanniello 对若干 Java 仓库样本的统计给出未使用函数的中位数约 15%，行业观察则把典型区间放在 5%~30%，且系统越大、越老，比例越高（单一案例报道过清理掉 67% 体量的做法，属个案而非均值）。所以目标规模应先按 150k~300k 行估算，而不是 730k。见证据强度：中位数来自受控样本研究，67% 为单一案例。
2. 旧系统真正的资产不是代码，是冻结在代码里、且没有任何文档的业务规则。「那个大客户的特殊折扣」「某种币值的舍入规则」「因为合作方系统不稳才加的重试」——这些载荷性行为（load-bearing behaviour）既不写在需求里，也常常不在测试里，只有真实流量会触发它们。第一件要造的东西不是新系统，是能观测并锁定这些行为的装置。
3. Java → TypeScript/Python 不存在逐行翻译。这是本次选路最大的单点风险。Spring 的事务语义、MyBatis/Hibernate 的一级缓存与延迟加载、反射装配、拦截器链、AO P 切面——这些运行时行为无法在另一语言里被结构性对应。任何「把 XxxService.java 翻译成 TypeScript」的做法都不会通过生产验收，必须改为按行为切片重写 + 等价性判据。
4. 瓶颈不在生成，在验收；这份手册的重心因此放在 Harness 而不是 Prompt。DORA 2025（n≈5000）发现 AI 采纳虽正向关联交付吞吐量，但同时与软件交付不稳定性上升相关联；CodeRabbit 对 470 个真实 PR 的对照测量显示，AI 撰写 PR 的平均问题数是人工 PR 的 1.7 倍（10.83 vs 6.45），安全问题最多到 2.74 倍。生成器已经够快了，缺的是能自动说「不」的东西。
5. AI 是放大器，不是捷径——它会放大你现在的样子。同一份 DORA 数据：AI 采纳也需要底层平台能力承接，否则只是更快地堆积技术债。对一个本就缺乏自动化测试、CI 慢、回滚贵的老团队，直接上 AI 重写的结果是灾难性的。因此阶段零不是写代码，是先修平台（快速 CI、一键回滚、可观测）。
6. 规格取代代码成为一等公民，代码降为「编译产物」。这里说的 spec 不是写文档，而是从旧系统提取 + 人确认过的行为契约，用 markdown 落到仓库里。失败itim要修的是 spec 而不是代码——这正是 MISSION+ 的 ACDC 循环里「验证失败回退到规格」那条纪律。
7. 上下文工程决定成败，模型强弱是第二位的。一个 60% 塞满探索噪音的上下文窗口，表现不如 15% 精选信号的窗口。3412 个文件的全仓库「你来分析一下」注定产出空泛结论。正确姿势是分层 CLAUDE.md + 每接缝一份 brief + 用子智能体卸载探索。
8. 绞杀者的最小单位不是 Maven 模块，是路由规则。15 个模块是按技术分层和历史演进切出来的，不是按业务接缝切的。直接把模块当作迁移单元会撞上跨模块调用网。要先把「模块依赖图」还原成「行为接缝图」，再按业务语义重新打包。
9. 每个切片走同一条七步固定流程，这是「真实能开发出来」的关键。固定流程让工作可被批处理、可被换人执行、可被 AI 半自动执行，也让进度可度量。MISSION+ 的现场纪录是：一名工程师 + 每阶段最多 20 个子智能体，把 35 万行 Java/JSP 重建为 TypeScript，第 5 天跑到可运行的开发版本（注意：是可运行开发版，不是生产上线）。
10. 护栏必须机器化，不能靠「人仔细看」。Anthropic 的 Claude Code 使用研究里，专业人员达到已验证成功的会话约 30%，约九成代码产出会话只到「部分成功」。差距正是靠 Stop hook、CI 门禁、差异率阈值、准入列表这些确定性机制来补，而不是靠评审态度。
11. 必须预先写死止损线。如果第 3 个切片在 12 周内没完成生产切换，说明接缝假设或团队能力不成立，应当降级为原地现代化而不是加人硬推。没有 kill criteria 的重写项目会在第 18 个月变成政治问题。

Section 01

01判定：你的系统究竟处在什么位置

不是所有遗留系统都适合走这条路。先花两周做五项闸门体检，用工具的真实输出填下面这张表，然后按表末的裁决规则选择路线。这五项的共同点是：它们决定了「你我有无办法证明新旧等价」——证明不了等价，绞杀者就退化成赌博。

五个数字的基线，第一天就要测出来

下面这组基线数字会在后面每一步反复用到。它们不是装饰性指标，而是用来判断某一步是否真的推进了的唯一依据。

# 1. 真实体量：排除 generated / protobuf / 前端打包产物
find . -name "*.java" -not -path "*/generated/*" -not -path "*/target/*" | wc -l
find . -name "*.java" -not -path "*/generated/*" -not -path "*/target/*" -print0 \
  | xargs -0 wc -l | tail -1

# 2. 每模块体量分布（决定切片优先看的战场）
for m in */pom.xml; do d=$(dirname "$m");
  printf "%-28s %6s files  %8s loc\n" "$d" \
    "$(find "$d" -name '*.java' | wc -l | tr -d ' ')" \
    "$(find "$d" -name '*.java' -print0 | xargs -0 cat 2>/dev/null | wc -l | tr -d ' ')"
done | sort -k4 -nr

# 3. 生产被调用的接口比例（从 Nginx / 网关 access log）
awk '{print $7}' access.log* | sed 's/[0-9]\{3,\}/:id:/g; s/?.*//' \
  | sort | uniq -c | sort -nr > /tmp/ep.tsv
wc -l /tmp/ep.tsv            # 分母：生产实际出现过的 URL 形态数
awk '$1<10' /tmp/ep.tsv | wc -l   # 90 天内调用 < 10 次的长尾

# 4. 数据库写入面
grep -rn "@Insert\|@Update\|@Delete\|executeUpdate\|\.persist(\|\.save(" --include="*.java" . | wc -l

# 5. CI 与回滚耗时（直接问运维要最近 20 次发布的数字）

Section 02

02四条理论根基，各自推出一批具体工程动作

好的理论要能推导。这里每条根基都硬推出一份「必须做 / 不许做」的清单——后面所有章节的操作都是从这四条推出来的，遇到没写到的情况，回到这四条自行推导。

根基一：放大器定律 —— AI 放大的是你现有的样子

DORA 2025 对约 5000 名技术从业者的调研给出一个反复被验证的判断：AI 在软件交付中的作用是「放大器」。它放大高效团队的成效，也放大陷于混乱的团队的功能失调。同一份数据里还有一组常被忽略的张力：90% 的人已在日常使用 AI，八成以上说生产力提升了，但约三成对 AI 输出缺乏信任；与此同时 AI 采纳与软件交付不稳定性上升相关联。

• 必须做：阶段零先把 CI 压到 15 分钟内、把回滚做成单点操作、补上可观测（traceID 贯穿）。这三条没做完，不要开始
• 必须做：把「每笔请求都有 traceID」做成新的乳化标准——后面影子流量比对要靠它做请求对齐
• 不许做：不许因为 AI 写得快就跳过 lint / typecheck / 格式化。类型系统是 TS 迁移最便宜的一道防线

根基二：Feathers 的接缝 —— 先造接缝，再造手术

遗留代码之所以难改，通常不是逻辑复杂，而是依赖藏得太深：函数中间直接连库、直接读时间、直接发 HTTP、直接碰全局单例。Michael Feathers 给的接缝（seam）定义是「无须在该处编辑代码就能改变其行为的位置」。有了接缝，你才能在旧系统上插探针、装容错、把流量引到新实现。

• 必须做：在每个待迁移切片的入口先造一个接缝（路由层或仓储层），再谈提取逻辑
• 必须做：把时间、随机数、外部 HTTP、消息队列这些非确定性依赖先抽出来，否则 golden master 比对全是噪点
• 不许做：不许在没有接缝的地方「原地改造」。先引流，再替换，最后才删除旧代码——这三步的顺序不可颠倒

根基三：表征测试 —— 旧系统的行为是唯一真实的规格说明

普通测试是「需求 → 写测试 → 让代码通过」。表征测试（characterization test，Michael Feathers 提出，也叫 Golden Master）反过来：跑一遍代码 → 观察输出 → 把这个输出钉死为期望值。它记录的是「它现在做什么」，而不是「它应该做什么」。对于一份跑了十年、需求文档早就对不上的内部系统，这是唯一诚实的规格来源。

// 表征测试的写法：先故意写错，拿到真实值，再把真实值回填为期望值
test('characterize: calcSettlement', async () => {
  const out = await calcSettlement(fixture.order_20240701);
  expect(out).toBe('THIS_IS_WRONG_ON_PURPOSE');   // 1. 跑 → 失败信息给出真实输出
});
// 2. 把失败信息里的 actual 回填进去，测试转绿 → 行为被钉住
// 3. 之后的任何重构，只要这个值变了，测试立刻报警

根基四：规格先行 —— 失败时改规格，而不是改代码

MISSION+ 的 ACDC 循环里有一条纪律被反复强调：验证失败要把工作退回规格，而不是退进代码。这与 Endgate 的 ACDC 白皮书所述一致——当 intent 只存在于聊天记录里，团队就丢失了「为什么这么做」的记录，结果是产出更快、返工更多。落到做法上：

• 必须做：每个切片先产出 spec/<slice>/behavior.md，人签字后再让 AI 生成代码
• 必须做：Vibe 式 diff 打到 spec 上时，把它和改动物一起进评审；半年后有人问「为什么部分退款的标签变了」，答案应该在那个评审里
• 不许做：不许让 AI 反过来从自己生成的代码总结写 spec。那会产生自洽但错误的闭环——spec 必须从旧系统行为 + 人工确认双向而来

Section 03

03总蓝图：七个阶段，和一条不断重复的循环

整个工程分成七个阶段。其中前三个是一次性投入（约 3~4 个月），第五阶段是要被重复 15~25 次的核心循环，第六阶段与第五阶段并行推进，第七阶段收尾。真正决定周期长短的不是一次迁移多少行，而是你多久完成一次完整的切片循环。

Section 04

04阶段零 · 战前两周：把 Harness 建起来

这一步完全不碰业务代码。它的产出是一个「可以让 AI 在里面连续工作而人敢离开」的环境。跳过这步的团队，通常会在第 3 个月发现自己在用人工 review 补 AI 的漏洞，速度优势全部吐回去。

第 1 天 · 建三条硬护栏（半天）

先写 .claude/settings.json 并提交进仓库，让每个参与的人都继承同一套护栏。三条护栏对应三类真实事故：读走密钥、一次改动跨太多 file、以及「看起来完成了」。

// .claude/settings.json —— 提交进仓库，全团队继承
{
  "permissions": {
    "allow": [
      "Bash(npm run verify)", "Bash(npm run test *)", "Bash(npx tsc *)",
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)"
    ],
    "deny": [
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Read(./src/main/resources/**/*.properties)",
      "Bash(cat .env*)", "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-on-write.sh" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-gate.sh" }] }
    ]
  }
}

注意：权限是一层层叠加的（user → project → local），而 .claudeignore 或允许规则都可能被索引、全局搜索、系统提醒绕过；要真正挡住对密钥文件的读取，靠的是 PreToolUse hook 退出码 2，而不是某条 allow 规则。把 hook（覆盖动态逻辑和 Bash 读取）与 deny 规则（在权限层覆盖文件工具）成对使用。

# .claude/hooks/protect-files.sh   —— 挡住 .env / lock 文件 / .git
#!/bin/bash
INPUT=$(cat)
FP=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
for p in ".env" "package-lock.json" ".git/"; do
  if [[ "$FP" == *"$p"* ]]; then
    echo "Blocked: $FP matches protected pattern '$p'" >&2
    exit 2                      # 退出码 2 = 阻断该次工具调用
  fi
done
exit 0

# .claude/hooks/verify-gate.sh    —— Stop hook：不通过就不许这一轮结束
#!/bin/bash
set -o pipefail
OUT=$(npm run verify 2>&1)      # 指向你的 typecheck + lint + test + golden 比对
if [ $? -ne 0 ]; then
  echo "$OUT" | tail -40 >&2     # 把失败输出喂回给模型，它会接着修
  exit 2
fi
exit 0

第 2~3 天 · 定义 npm run verify（或对应的 make verify）

这一条命令是整个 Harness 的心脏。所有门禁最终都收敛到它身上，因为 hook 只能跑一个命令。它的设计原则：快、确定性、无副作用、失败信息可读。

// package.json （Python 侧对应 Makefile + pytest + ruff + mypy）
{
  "scripts": {
    "verify": "npm run typecheck && npm run lint && npm run test:unit && npm run golden",
    "typecheck": "tsc --noEmit",
    "lint": "eslint . --max-warnings 0",
    "test:unit": "vitest run --reporter=dot",
    "golden": "node scripts/golden-compare.js --dir ./golden --fail-on-diff",
    "shadow:report": "node scripts/shadow-diff.js --since 24h --threshold 0.005"
  }
}

• verify 必须能在 15 分钟内跑完，否则 AI 的迭代节奏被拖垮——这是阶段零要先优化 CI 的原因
• verify 不得触碰生产数据库或外部服务；golden 比对只读本地 fixture
• verify 的失败输出必须包含「哪个输入、期望什么、实际得到什么」，否则模型修不动

第 4~5 天 · 三层 CLAUDE.md 骨架

单文件 CLAUDE.md 超过一两百行后，指令遵循度会明显下降——模型会有选择地忽略。正确做法是分层加载：Claude Code 会向上加载从当前目录到根目录沿路所有 CLAUDE.md，子目录则是访问到才加载，兄弟目录永不互相加载。这意味着你可以精确控制「在某个切片里工作时，AI 看到什么」。

repo/
├── CLAUDE.md                    # 根：全局规则 + 架构地图 + 入口索引（≤ 200 行）
├── packages/
│   ├── gateway/CLAUDE.md        # 仅在这个包工作时加载
│   ├── settlement/CLAUDE.md     # 仅在这个包工作时加载
│   └── ...
└── spec/                        # 规格库，见第 06 章
    └── index.md                 # 所有 spec 的索引，根 CLAUDE.md 指向它

# CLAUDE.md（根，示范）

## 这是什么项目
旧系统 X（Java / 15 Maven 模块）正在被绞杀式替换为新栈（TypeScript）。
旧代码在 `legacy/`，只读，不要修改。新代码在 `packages/`。

## 永远不要做
- 不要把 `legacy/` 下的 Java 文件整份喂给上下文，按 `spec/` 里的 brief 走
- 不要在没写 spec 的情况下生成业务代码 —— 先建 `spec/<slice>/behavior.md`
- 不要读 `.env`、不要碰 `resources/*.properties`（已被 hook 拦截，这里再写一次）

## 这次任务怎么开始
1. 读 `spec/<slice>/behavior.md` —— 它是唯一的需求来源
2. 允许直接读的旧代码：behavior.md 里「溯源」字段列出的那些文件
3. 实现完成后跑 `npm run verify`；Stop hook 会替你跑，不要假装通过

## 验证纪录片
- `npm run verify`        主门禁（typecheck + lint + 单测 + golden）
- `npm run shadow:report` 生产影子流量差异率报告，阈值 0.5%

## 各包入口
- gateway:      packages/gateway/src/index.ts
- settlement:   packages/settlement/src/app.ts
（改动涉及多包时，先写 plan 到 `.plan/` 下的 md，再动手）

Section 05

05阶段一 · 代码考古：先把 730k 压下去

这是投产比最高、也最容易被跳过的一步。理由很直接：后面每一个 AI 探索任务，都要为仓库里的噪音付 Context 税。把 30% 的死代码删掉，等价于让后面所有对话免费获得 30% 的额外上下文预算。

步骤 1 · 静态调用图：谁从来没被人引用过

不需要买商业工具。用正则做粗粒度近似就够了——因为它的作用只是筛出候选，定罪权交给运行时证据。

#!/usr/bin/env python3
"""fanin_scan.py —— 粗粒度静态存活性筛查（候选生成，不定罪）
用法: python3 fanin_scan.py /path/to/repo > /tmp/fanin.tsv"""
import re, sys, os, collections

ROOT = sys.argv[1]
CLASS_RE   = re.compile(r'(?:class|interface|enum)\s+([A-Z][A-Za-z0-9_]*)')
IMPORT_RE  = re.compile(r'import\s+(?:static\s+)?([\w.]+)\.([A-Z][A-Za-z0-9_]*)\s*;')
USAGE_RE   = re.compile(r'\b([A-Z][A-Za-z0-9_]{2,})\b')

decls, files = {}, {}
for dp, _, fns in os.walk(ROOT):
    if '/target/' in dp or '/generated/' in dp: continue
    for fn in fns:
        if not fn.endswith('.java'): continue
        p = os.path.join(dp, fn)
        src = open(p, encoding='utf-8', errors='ignore').read()
        files[p] = src
        for name in CLASS_RE.findall(src):
            decls.setdefault(name, set()).add(p)

imp_cnt = collections.Counter()
body_cnt = collections.Counter()
for src in files.values():
    for full, cls in IMPORT_RE.findall(src):
        imp_cnt[cls] += 1
    body = IMPORT_RE.sub('', src)
    for name in USAGE_RE.findall(body):
        body_cnt[name] += 1

print("class\timports\tbody_uses\tsource_file")
for name, paths in sorted(decls.items()):
    i, b = imp_cnt.get(name, 0), body_cnt.get(name, 0)
    if i == 0 and b <= 1:                      # 只出现在自己的声明里
        print(f"{name}\t{i}\t{b}\t{','.join(sorted(paths))}")

# 出来的数字应该让你警觉：通常几百到一两千个类属于这一类
python3 fanin_scan.py . > /tmp/fanin.tsv
wc -l /tmp/fanin.tsv
awk -F'\t' '{print $4}' /tmp/fanin.tsv | tr ',' '\n' | sed 's#/[^/]*$##' | sort | uniq -c | sort -nr | head -20
# ↑ 按包聚合：死代码往往高度集中在几个「当年做完没上线」的模块里

步骤 2 · 运行时插桩：生产到底跑了哪些方法

静态分析会被反射、动态代理、字符串查表骗过去。唯一诚实的答案来自运行的 JVM。两个成本递增的做法：

// 在旧系统里临时加一个 actuator endpoint，dump 所有注册路由
@ReadOperation
public Map<String,String> routes(RequestMappingHandlerMapping m) {
    return m.getHandlerMethods().entrySet().stream()
        .collect(toMap(e -> e.getKey().toString(),
                       e -> e.getValue().getBeanType().getName() + "#"
                            + e.getValue().getMethod().getName()));
}

步骤 3 · Git 考古：给每个文件算 bus factor

# 每个文件的：最后修改时间 / 改动次数 / 独立作者数
git log --since="3 years ago" --name-only --format="COMMIT|%at|%ae" \
  | awk -F'|' '/^COMMIT\|/{ t=$2; a=$3; next } NF{ print $0"\t"t"\t"a }' \
  | sort | awk -F'\t' '{ c[$1]++; who[$1"|"$3]=1; if($2>last[$1]) last[$1]=$2 }
    END{ for(f in c){ n=split("",x); # 统计 who[...]
        for(k in who){ split(k,p,"|"); if(p[1]==f) authors[f]++ }
        printf "%s\t%d\t%d\t%d\n", f, c[f], authors[f], last[f] } }' \
  | sort -k4 -n > /tmp/git-heat.tsv

# 「两年没人动 + 只有 1 个作者 + 静态零引用」→ 高置信候选
join -t$'\t' <(sort /tmp/fanin-code.tsv) <(sort /tmp/git-heat.tsv) | awk -F'\t' '$5==1'

步骤 4 · 删除纪律

1. 先加日志再删。对候选路径打点，观察两周零命中后才允许删除
2. 连带删除它的测试。一个只用来验证已删行为的测试，以及只为了让这个测试通过而存在的代码——它们是一对共生的僵尸，必须成对清除，否则 CI 会变成维护死代码的成本
3. 单笔隔离 commit。一次删一个自包含的包，跑完构建再删下一批。误删的代码在 Git 历史里，git revert 一次就回来
4. 分批递增。从「自包含包 → 明确下线功能的开关 → 已知废弃的旧接口」逐步升级到更大的块

Section 06

06阶段二 · 抽取规格：让旧系统说出它真正在做什么

这一步是整个工程的价值枢纽。请注意它不是「让 AI 读完代码生成一份设计文档」——那样做出来的文档漂亮但没法验收。规格 = 可被追溯的行为断言 + 人工签署。

三层材料，缺一层就不能签字

步骤 1 · 造接缝，把真样本抓出来

在要迁移的切片入口插一层薄薄的拦截，把每次调用的入参与返回值落盘（脱敏后）。这就是 Feathers 说的 seam——不改业务逻辑，只为观测。

// 旧系统侧：一个 request-scoped 的采集切面，两周即可下线
@Aspect @Component @Profile("capture")
public class CaptureAspect {
    @Around("within(com.corp.settlement..*) && @annotation(Capture)")
    public Object capture(ProceedingJoinPoint pjp) throws Throwable {
        long t0 = System.nanoTime();
        Object out; Throwable err = null;
        try { out = pjp.proceed(); }
        catch (Throwable e) { err = e; throw e; }
        finally {
            Captured c = new Captured(
                MDC.get("traceId"),
                pjp.getSignature().toShortString(),
                scrub(pjp.getArgs()),          // 必须脱敏：手机号/身份证/金额
                scrub(out), err,
                System.nanoTime() - t0);
            captureSink.write(c);              // 落 Parquet / JSONL，勿写生产库
        }
        return out;
    }
}

• 采集必须异步且不阻塞主流程；Sink 失败只能记录不能抛异常
• 脱敏在采集侧做，不要让原始 PII 落到中间文件里
• 样本要按段落分层采样（新客/老客/异常流/边界值），而不是简单地取前 1000 条——那里全是同一形状的正常流

步骤 2 · 生成 golden master：金的是「投影」而不是「原文」

直接快照返回值在两种场景下会失效：输出本身不确定（时间戳、随机 ID、浮点结合率），以及 LLM 类组件的温度导致的抖动。正确的做法是钉住一个确定性投影函数的结果。常见投影，按稳定度大致排序：

// golden/api/settlement.calc.jsonl —— 每行一组输入，首行是 pin 下来的配置
{"_config":{"captured":"2026-08-11","samples":5,"old_version":"v10.4.2","note":"临时="-journalable"}}
{"case_id":"inv-0031","shape":["amount:currency:due_date:order_id"],
 "label":"overdue","entities":["4417","CNY"],
 "amount":128.40,"side_effects":["notifyFinance"]}
{"case_id":"inv-0032","shape":["amount:currency:due_date:order_id"],
 "label":"partial_overdue","entities":["4418","CNY"],
 "amount":0.00,"side_effects":[]}

步骤 3 · 让 AI 写 behavior.md，人来签

这一步的 Prompt 要给「bound context」而不是「请你总结一下」。关键：在 Prompt 里指定可读哪些文件，这样探测器就不会被庞大的仓库污染。

> 你在为一个使用了 10 年的遗留系统做行为规格提取。严格遵守：
>
> 1. 只能读我列出的这些文件：`legacy/module-a/src/main/java/com/corp/settlement/` 下
>    的 Calc*.java、Rule*.java、DiscountPolicy.java。**不要**读 com.corp.settlement.batch/ 之外的目录，
>    不要读任何 *Test.java（那些是错的，别被它们误导）。
> 2. 同时读样本：`golden/api/settlement.calc.jsonl`（前 60 行即可），它是真实生产输入的投影。
> 3. 产出 spec/settlement/behavior.md，每条规则必须写成三段：
>      规则 / 判定：  〈一句话，必须是可被测试用例反驳的陈述〉
>      溯源：         〈代码位置，或某个 case_id 的样本〉——两者都没有就整条删掉
>      状态：         confirmed-by-business |疑似bug-待确认 |无法确认
> 4. 遇到看起来像 bug 的行为：**照实记录**并标记「疑似bug-待确认」，
>    不许替我把 bug 修好。我们要的是「它现在做什么」，不是「它应该做什么」。
> 5. 用到 URL/IQ/报表等外部依赖时列清单，不要深入展开。
> 6. 每产出 10 条规则暂停，等我确认方向后继续。

# spec/settlement/behavior.md （示范片段）

## R-017 部分还款的逾期标签判定
**判定**：当还款额 > 0 但 < 应还额，且距到期日 > 3 天时，标签取 `partial_overdue`，
         并且**不**触发催缴通知。
**溯源**：`DiscountPolicy.java:184-192`；样本 `inv-0032`（2026-08-11 采集）
**状态**：疑似bug-待确认 —— 业务方表示「应当触发催缴」，此行为疑似 2019 年为某大客户临时放宽

## R-018 外币结算的舍入方向
**判定**：外币金额一律按 `ROUND_HALF_UP` 保留两位，本位币按 `ROUND_HALF_EVEN`。
**溯源**：`CalcSettlement.java:311`；样本 `fx-0007`、`fx-0041`
**状态**：confirmed-by-business

步骤 4 · 签字的意义

behavior.md 必须由既懂业务又看得懂这份代码的人逐条签署，包括那些「疑似 bug」。签字的那一刻你在回答一个不可逆的问题：我们要把这个 bug 一起搬过去，还是趁此机会修正它？无论哪种都要写下来——这决定了后面双跑时哪些差异是「预期的」。

有一个现场经验值得记住：一个跑了十年、几乎没有文档、只有过时用户故事的系统，在重建之后拥有数十万行 markdown——其中约八成是模型改代码的副产物而不是额外劳动，其余约一成半由从旧代码抽出来的规格种子长出来。关键在于让规格成为流水线的副产物，而不是额外任务。

Section 07

07阶段三 · 切片定序：把 15 个模块打散成 15~25 个行为接缝

这一步最常见的错误是：直接拿 Maven 模块当切片。15 个模块是按技术分层和历史演进切出来的，不是按业务接缝切的——你会发现「订单」这个业务概念横跨 6 个模块，而「报表」模块里躺着三种完全不相干的东西。切片必须按能被一条路由规则切出来的行为边界来定义。

用静态依赖矩阵找回真实的业务边界

把「module → module」的调用关系画成矩阵，再和数据库表的所有权叠起来看，通常几分钟就能看出哪几处才是真正的接缝。

# 1. 从 Maven 模块”到“模块”的调用强度矩阵（正则近似胜过没有）
python3 - <<'PY'
import re, os, collections, itertools
ROOT='.'; mods=['module-a','module-b','module-c']        # 换成你的 15 个模块名
imp = collections.Counter()
for dp,_,fns in os.walk(ROOT):
    if '/target/' in dp: continue
    for fn in fns:
        if not fn.endswith('.java'): continue
        src=open(os.path.join(dp,fn),encoding='utf-8',errors='ignore').read()
        src_mod=next((m for m in mods if f'/{m}/' in dp), None)
        if not src_mod: continue
        for pkg,cls in re.findall(r'import\s+([\w.]+)\.([A-Z]\w+)\s*;', src):
            tgt_mod=next((m for m in mods if f'corp.{m.replace("-",".")}' in pkg), None)
            if tgt_mod and tgt_mod!=src_mod: imp[(src_mod,tgt_mod)]+=1
print('\t'+'\t'.join(mods))
for a in mods:
    print(a+'\t'+'\t'.join(str(imp.get((a,b),0)) for b in mods))
PY
# 2. 把表的所有权叠加上去
SELECT table_schema, table_name, COUNT(*) AS write_sites
  FROM information_schema.tables t JOIN audit_log_table_access a USING(table_name)
 WHERE a.op IN ('INSERT','UPDATE','DELETE') GROUP BY 1,2 ORDER BY 3 DESC;

排期：把 24 个月切成能看见的刻度

Section 08

08阶段四 · 切片七步：这套循环要跑 15~25 遍

这是手册的核心。每一个切片都走同七步，不多不少。固定流程的价值在于：它让工作可批处理、可换人、可被 AI 半自动执行，也让「进度到哪了」变成一个客观数字。

# 每片必须量化七个数，写在 spec/<slice>/README.md 顶部
日请求量:      128,000        P99 延迟:    340 ms
读 / 写比:     92 : 8         数据量:      表 14 张，主表 2.3 GB
下游依赖:      5 个内部服务 + 1 个外部 API
上游调用方:    11 个已登记，0 个未知
变更频率:      近 6 个月 34 次提交，3 个作者

# Nginx 侧：先把镜像跑起来（响应丢弃，用户无感）
location /api/settlement/ {
    proxy_pass      http://legacy-upstream;
    mirror          /shadow;
    mirror_request_body on;
}
location = /shadow {
    internal;
    proxy_pass      http://new-svc$request_uri;
    proxy_connect_timeout 1;   # fire-and-forget：不等待影子结果
    proxy_send_timeout    1;
    proxy_read_timeout    1;
}

> 实现 `packages/settlement/src/settle.ts`。
> 需求来源只有 `spec/settlement/behavior.md`（你现在读它），
> 验收标准是 `golden/settlement.jsonl`（跑 `npm run golden` 比对）。
>
> 硬性约束：
> - **不要**去读 legacy/ 下的 Java 源码来「对齐实现」。如果你发现 behavior.md
>   有遗漏或自相矛盾，停下来告诉我，我会补 spec，而不是让你自己悟出来。
> - 不确定性的来源必须作为参数注入：`now: Clock`、`random: Random`、`fx: RateProvider`。
>   不允许在函数内部直接调用 Date.now() 或 Math.random()。
> - 输出必须与 golden 里的 shape 完全一致；金额一律用 decimal 库，禁止浮点累加。
> - 完成后跑 `npm run verify`；Stop hook 会替你跑，但你也要自己看一次输出。

// scripts/shadow-diff.js —— 归一化后按 traceID 对齐比对
const normalize = (o) => ({
  ...omit(o, ['requestId','timestamp','latencyMs','serverHost']),
  items: sortBy(o.items ?? [], 'id'),        // 顺序无语义时先排序
  amount: round2(o.amount),
});
for (const [tid, {old: a, new: b}] of aligned) {
  const d = deepDiff(normalize(a), normalize(b));
  if (!d) continue;
  classify(tid, d);
  // 三类：NEW_BUG / UNDOCUMENTED_OLD_BEHAVIOR / EXPECTED_CHANGE
}
report({ total, diffCount, rate: diffCount / total, unexplained });

Section 09

09阶段五 · 数据层：整个迁移里最硬的那块骨头

把 Java 换成 TypeScript 或 Python，最容易被低估的不是语法，而是整套运行时语义的迁移：Spring 的事务传播、ORM 的一级缓存与延迟加载、AOP 切面、拦截器链、以及藏在存储过程里的业务。这一章单独列出这些「结构性无法一一对应」的地方。

先给一条不可违背的顺序

六个「跨语言不天然等价」的点，逐个给对策

过渡期的两面：防腐层 + CDC

在「新旧并存」的那段时间，数据要两边同步。做法是在新侧前面加一层防腐层（Anti-Corruption Layer）——它的职责是把旧系统的数据与操作以干净的现代形态暴露出来，所有新消费者只跟它对话。它是这 24 个月里你要维护最久、也最应该写得无聊的一段代码。

# 数据面：CDC 把旧库的变更实时复制到新侧
# 1. 用 Debezium / Canal 之类抓 binlog，落到 Kafka
# 2. 消费者把变更 UPSERT 到新库，注意保留 __op 与 __ts_ms 以便回溯
# 3. 一致性校验：定期对边比对，不能只靠 CDC 的「我发了」

async function verifyConsistency(sampleRate = 0.01) {
  const keys = await pickSampleKeys(sampleRate);           // 按主键空间均匀抽样
  let mismatch = 0;
  for (const rowPk of keys) {
    const [oldRow, newRow] = await Promise.all([
      legacyRepo.find(rowPk), typedRepo.find(rowPk),
    ]);
    if (canonicalize(oldRow) !== canonicalize(newRow)) {
      mismatch++;
      await driftLog.write({ rowPk, oldRow, newRow });      // 人工判定：CDC 延迟 or 真漂移
    }
  }
  metrics.gauge('drift.rate', mismatch / keys.length);      // 必须长期 < 0.1%
}

Section 10

10阶段六 · 组织怎么排，以及旧系统怎么下线

三种编队，别只用一种

三种循环，第三种最花钱但最必需

第三种循环是「能上线的原型」和「正在服务真实用户的系统」之间的差别。单个智能体每次只盯着一个任务，而「所有功能彼此怎么协调一致」这件事只存在于你的脑子里。所以需要一个位于单个任务之上的层：批量复查已建成的功能，而且每次刻意换角度。两类典型的启动提示：

> 【指定角度】看看 product 表是怎么实现的，然后把后台里所有类似的列表
>   在功能、展示、链接行为上对齐它。列一张不一致清单，逐条处理。

> 【开放角度】检查所有注册场景潜在的错误情况：网络超时、重复提交、
>   第三方返回未知状态、验证码过期。列出目前一处都没处理的场景。

上下文的多样性与「笨区」

一个很反直觉的教训：AI 辅助开发的质量，主要由智能体能访问到的上下文的多样性决定，而不是 Prompt 写得多么精巧。在那个 550K 行系统重建的现场，被允许的上下文远不止旧代码、文档和数据库 schema——还包括让智能体直接查询一份本地的旧数据库副本、让它自己去浏览旧站点的页面；接入不熟悉的外部域时，甚至直接问它「你还需要哪些上下文源」。

下线清单：最后一周要做的事

• 确认旧侧连续 30 天零调用（网关日志 + 应用内计数器双证据）
• 所有 Mic check：定时任务、批处理、报表订阅、数据推送、手工 SQL 入口
• 旧代码的物理删除，包括只为它存在的测试与配置；在 Git 里留最后一个 tag 作为墓碑
• 归档留痕：把最终的 behavior.md 集合、golden set、差异归因记录归档为系统的行为档案——这是这次迁移最持久的资产
• 对外公告与文档更新：给运维、客服、业务方各一份「哪些界面变了」的说明
• 最后再保留旧实例运行 只读 30 天，然后停机。停机前先做一次冷备份

Section 11

11度量体系，和预先写死的止损线

度量要覆盖三层，并且每一层都要能被操纵至失效——所以配套给出反制。

三层指标与它们的反滥用条款

止损线（写在立项书里，而不是事后讨论）

1. 第 3 个切片若在 12 周内未完成生产切换 → 停下复盘。通常是接缝假设错了（边界不该这样切），而不是人手不够
2. 连续两片上线后出现被判定为「新实现缺陷」的生产逃逸 → 回到阶段零，重审验证体系而不是继续迁移
3. 业务交付时长连续两个月劣化超过 30% → 降速，把 Pod 的一部分人挪回维持性工作
4. 关键人员离职且无人接手其负责的 spec → 立即冻结该片的迁移，先把规格补齐
5. 降级路径要提前设计：从「全量绞杀」降到「核心域重写 + 外围沿用」，再降到「原地现代化」。每一级都明确要放弃什么

Section 12

12反模式清单：症状 → 后果 → 修正

Section 13

13附录：可以直接复制的东西

A. 命令速查

B. Prompt 模板库（每张便利贴对应一个固定动作）

C. 每个切片的文件夹骨架

spec/<slice>/
├── README.md          # 七个数：请求量/P99/读写比/数据量/上下游/变更频率
├── behavior.md        # 行为规格，人签字；每条含「判定/溯源/状态」
├── migration-plan.md  # 接缝位置、路由开关名、回滚方式、灰度档位与观察窗
├── diff-log.md        # 双跑差异归因记录，每条有署名解释
└── done.md            # 完成证明：100% 切换日期 + 旧代码删除 commit 号
golden/<slice>.jsonl   # 投影化的 golden master
packages/<slice>/      # 新实现

D. 一句话提醒，写给三个月后的自己

• 如果你没法证明新旧等价，那就还不是迁移，只是重写到了一半
• 验证失败改规格，不改代码
• 每片完成的定义是旧代码被删掉，不是新代码跑起来
• 给 AI 更多上下文和给它更好的上下文是两件事，后者才有用
• 护栏一定是机械化的（hook、CI、门禁），而不是「大家小心一点」——.claudeignore 和权限允许列表都可能被索引绕过，能用 PreToolUse hook 挡的就别指望权限规则