2 人 + AI · 方法论交付物

用 AI 安全重构
大型系统到 Cosmos

一页最小内核 就能开始:5W2H 逐级确认 + 安全网兜底,把大型遗留后端增量迁移到 Cosmos。
诊断阶段零风险——关卡④确认前,不改一行代码。

1页就能开始
4逐级确认关卡
5条硬约束
0诊断期代码改动
SCROLL
START · 砍无可砍的核心

一页最小内核,读完就能开干

不用先读完所有文档、不用先搭一堆前置。agent 读这一页,挑个低风险模块,就能安全地开始、一个个滚下去。深度(全景测绘 / 架构 / gateway)按需再取。

约束(违反即回滚)

行为等价API 冻结前端不改 不迁数据小步可回滚没绿不算完成
红线:动这个模块前先有它的网(没网不是重构,是乱改)· 重构与功能不混 commit · 测试没绿 / diff≠0 不提交

核心循环(一次一个模块,滚起来)

  1. 选 1 个低风险模块(别从最难的开始)
  2. 先建网:录它的真实行为为 golden 测试 + 锁对外契约
  3. 在稳定接缝(gateway/ACL)后实现 Cosmos 新版
  4. 影子 diff:旧 vs 新 → diff=0 且测试绿 → 提交
  5. 任一不过 → 修复或回滚,不降标准假装通过 → 滚下一个
Why it matters

为什么这套能托住大型重构

直接让 LLM 改大项目,常只做表面、引入 bug、权限过宽。这套把风险关进笼子:先对齐、后动手,每步可证、可回滚。

零风险诊断

分析→演示→访谈→出方案,全程不改代码。先看清值不值得迁。

安全网守护等价

characterization + 契约 golden + 影子 diff,用旧系统真实行为兜每一步。

增量可回滚

Strangler-Fig 逐模块替换,旧系统全程在跑、不迁数据,异常秒级回滚。

2 人 + AI

小团队推进大型迁移。深度(架构/gateway/拓展性)按需取,不是开始门槛。

5W2H · 逐级确认

四个关卡,确认了才进下一关

先 Why、再 How、最后 When。每关产出后停下等你确认,方向错了当场拦截——而不是写完一堆代码才发现跑偏。

01

理解现状WHAT

先跑 understand 建知识图谱(大库按核心域分批),再梳理架构 / 模块 / API / 业务逻辑 / 死代码。

→ 确认「理解正确吗?」
02

目的与方案WHY

先挖清「为什么重构」,再据此出目标架构——每个要点对应解决哪个目的。

→ 确认「目的/方案正确吗?」
03

怎么做HOW

迁移路线(按依赖+风险)、验证与回滚、分工、安全网、不迁边界、风险缓解。

→ 确认「how 对吗?」
04

时间与成本WHEN · HOW MUCH

估工作量/时间线/成本,汇总成《重构诊断报告》——这就是最终交付物。

→ 确认后才进入真正重构(届时才动代码)
诚实声明 · 不可消除

两个风险,工具消不掉,靠人补

这套方案显著提升成功率,但不保证成功。我们把隐性假设摆到最显眼处,而不是包装成"自动驾驶"。

覆盖盲区

golden 只锁测到的 I/O;旧系统里没被测到的隐性规则,LLM 不理解就不写测试,重写后测试全绿也发现不了它静默消失。缓解:真实流量回放找盲区 + 核心模块逐分支人工确认。

非专家审 Cosmos

P3+ 架构决策、确定性改造、GetSigners parity 若由不懂 Cosmos 的人"审批",等于橡皮图章,而爆炸半径是整链 halt 全站宕

适用前提:诊断四关卡非资深也能跑(零代码、零风险);但真进入重构(P3+),需 ≥1 名能独立审 Cosmos 的工程师,并建议在 P3 批准前、上线前各做一次真人安全审计。
For developers · 复制即用

开始:把提示词发给 Claude

在你要重构的项目目录下打开 Claude Code,按顺序复制下面的提示词。规则写死在里面——Claude 会自己守规矩、逐关停下来等你确认。

行为等价 API 冻结 前端不改 不迁数据 关卡④前不改代码
第 0 步 · 同步环境
访问 https://cc.gjs.ink/ ,读取页面上提供的「一键安装提示词」,然后照它执行,把这套 Claude Code 增强配置(来自 hongnono-wdh/claude-config,含插件 + Skill + MCP)装好。要求:
1. 严格按页面上最新的步骤执行;
2. 保留我已有的全局配置,绝不整体覆盖;
3. 每一步执行后确认成功,最后逐项验证安装结果;
4. 装完告诉我需要重启 Claude Code,让插件 / Skill 生效。
第 1 步 · 启动诊断(关卡①)
我要用 5W2H 四关卡流程,对这个项目做一次重构诊断。规则你必须严格遵守:
- 分四关:① What 理解现状 → ② Why 目的+方案 → ③ How 怎么做 → ④ When/How much 时间成本。
- 每做完一关,停下来等我确认"正确",我确认了你才能进下一关;我指出问题就留在本关改,别往下走。
- 在我确认关卡④之前,你只能读代码、出文档,绝对不许修改任何代码。

现在开始【关卡① 理解现状】:
1. 先评估代码库量级;小到中库执行一次 understand 建整库知识图谱,大库(>30 万行)只对核心业务域分批 understand。再用 understand-dashboard 出可视化、understand-domain 提取业务领域。
2. 基于图谱梳理:整体架构、核心模块与职责、模块间依赖、对外 API/接口、关键业务逻辑、技术栈,标出核心与疑似死代码。
3. 抽样校验图谱 2-3 个关键模块(AI 产物可能算错),再产出"我理解的你的项目"摘要,然后停下来问我:"理解正确吗?哪里有偏差?"

完整四关卡提示词、卡住自救话术见 RUNBOOK.md;最小内核见 START.md

Ship it

用 Claude Code 打开仓库,现在开始

一页最小内核 + 按需深度,全部开源。