实践1｜用 Claude Code 逆向了一个陌生业务模块

实践1｜用 Claude Code 逆向了一个陌生业务模块

昨天下午干了件以前要花两天的事：把手里一个从没读过的业务模块的完整调用链摸清楚，配上时序图、代码位置、发现的问题，最后整理成一份 20 页左右的文档发到了团队知识库。

写这篇是因为踩了几个坑，怕过两周自己就忘。

背景

工作区不小：5 个子仓库并排放着，前后端加起来几十万行。后端是 Spring Cloud 的一大套，商城那边做了 DDD 四层拆分（领域中心 / 平台支撑 / 聚合 / BFF 应用层）；前端更杂，原生 App、H5、几个小程序、B 端后台。

我要读的这块业务，是一个售后类增值服务的下单闭环。链路挺长：H5 页面点一下，先过商城 BFF，再走 connector 出到 open-api 网关，再 Feign 调到权威域服务，同时还要往一个外部系统推数据；用户支付成功之后还有一段 MQ 驱动的异步履约。

以前干这种事我的路数很土：grep 几个关键词，打开 IDE 一层层跳，跳一会儿就得画个草图不然容易乱，再跳，再画。小半天到一天出个大概轮廓。

这次全程 Claude Code，实际投入大概三个小时。

一、让它先"选题"

一开始差点栽了。上来一句"帮我分析这个模块的代码"，结果给我输出一大段模块结构、包名、类的职责。看起来专业，仔细一看全是废话——这些东西看目录名就能知道。

第二次改了思路：让它先列几条候选链路，我来挑一条。原话大概是：

这个仓库里有若干业务域，列出你觉得"业务流程最复杂、跨模块最多、值得单独写一篇文档"的候选链路，每条一句话说清楚：入口在哪、经过哪几个服务、终点是什么。别挑简单 CRUD。

它列了 7 条，我扫一眼就知道选哪个。挑的那条特别典型：前端一个动作、后端要过 4 层、还要调外部系统、支付完还有异步分支。这种链路适合写时序图——一眼能读完的功能没什么可写。

如果让它自己挑，八成会挑最容易分析的那条，写出来没什么营养。选题这一步得我自己做。

二、拆成三段问

选定链路之后，我没让它一次给我全套东西，分成了三段：

第一段是找入口。让它从某个前端页面开始追，把这个页面调用的所有 HTTP 请求、每个请求打到哪个 Controller 的哪个方法，用表格列出来。这里有个关键的要求——给我文件路径加行号。这个一开始没要求，它就写"在 XX 服务的 Controller 里"这种糊弄话。加了行号之后就能验证，不能瞎编。

第二段是画时序图。基于第一段的信息画 mermaid，参与者用真实类名，箭头上标注方法和关键参数。第一版基本都有漏——不是漏了一个缓存查询，就是把某个分支的兜底逻辑漏了。回问：“这个方法内部还调了什么？把源码给我看看。” 两三轮下来就完整了。

第三段：让它挑错。让它扮演一个挑刺的 code reviewer，找 bug、找前后端不一致的地方、找被注释掉但看起来该生效的代码、找 TODO/FIXME，每条给位置和影响。

这一步产出比较意外，翻出来 6 条问题：某个错误码分支的前端弹窗被注释掉了（用户命中会白屏）、另一个错误码前端根本没写处理分支、一个枚举字段前后端定义不一致、还有几处遗留的 FIXME。这些我自己一天可能都翻不出来。

分三段的好处是每段结束都有个可验证的东西——表格、图、清单。跑歪了我马上能看出来；一大团糊在一起就没办法了。

三、几个不太顺的地方

第一版时序图容易错。长得挺漂亮，逻辑上错的。比如把一个 Feign 同步调用画成了 MQ 异步，或者把 try-catch 里的兜底路径画到了主线上。看图的时候我给自己定了个习惯：当它是别人给我的第一稿代码，别当结论。

让它解释代码不如让它引用代码。让 AI 解释代码在做什么，它会自然语言描述一通，容易加戏、脑补。让它把原文的 20 行贴出来、再一句话点评就管用——贴出来的代码不会骗人，我自己能判断它有没有理解偏。

东西一定要落盘，别信对话历史。上下文窗口再长也有限，换个会话就没了。我的做法是每讨论完一段就让它写成一节 markdown 追加到项目里的 docs 目录下。这个 md 就变成了我们俩共同的工作记忆，下次开始之前让它先读一遍，比从零开始快十倍不止。

Claude Code 有个 memory 机制，可以把"这份文档在哪里"记一条进索引里。我就写了一条，指向那份 md。下次谁再问这个模块，AI 会先看文档再动手，不用重新梳理一遍。

分层写，一份文档给两种人看。这次的文档产品和研发都拿去用了，因为我写的时候故意分了两半：前半给业务同学，3 张 flowchart，讲流程和决策规则，不出现类名；后半给研发，3 张时序图、错误码分支表、代码位置速查、问题清单。这一步 Claude Code 不会主动做，得在 prompt 里明确说"两种读者、两种视角"。

四、最后一公里

写完只是一半。文档在我本地放着，只有我一个人能看到。

以前发文档到公司协同平台是全手工的：本地 md 复制过去、粘贴、发现 mermaid 变成了一堆代码块、手动改成绘图块、调表格、加目录、加权限。半小时起步，还容易漏。

昨天顺手装了 Claude Code 的文档平台 MCP 插件——在~/.claude/settings.json里加一段 MCP server 配置，装完重启，AI 就能直接调那个平台的 open API。之后的流程变成：让它读本地 md、调 MCP 建文档、内容写进去、挂到指定空间下。mermaid、表格、标题层级它自己处理。

第一次装踩了两个坑，都不是插件的问题：

• 平台应用的权限没勾全。新建文档、写入 block、读写指定空间三个都要勾，我第一次只勾了"写入"，AI 报 permission denied，我还以为是它的问题，回头看应用后台才发现是我自己没配好。
• 空间 ID 没告诉它。协同平台 URL 里那段就是空间 ID，我第一次没给，它默认扔到了我个人的"我的文档"下，同事根本看不到，白发一次。

装好之后，一句话就能发过去：把docs/xxx.md发到某某空间，作为一篇新文档，标题用一级标题。30 秒，格式基本 1:1。

发布成本降下来之后，我更愿意写文档了。以前技术文档在本地烂掉是常态——不是不想写，是发布这一步太恶心，写完发不出去就懒得动，一直堆到自己都懒得看。现在发布几乎不算工作量，那就更愿意从一开始就好好写。

时间账

三个小时怎么花的：

同样的活全手工做估计一天半到两天，而且大概率没这次系统。发布这一步以前手工半小时，现在几乎不计时。