该停下来的信号：怎么判断一次改动是「结构问题」而不是「bug 问题」

0030 秒速览：三句话，然后决定你从哪一节开始

先说清这篇解决的是什么。它不教你怎么写代码，也不给你一套新工具。它只补一个判断：眼前这一次改动（就像「点了没反应」这种没按你想要的样子表现的问题，也就是平常说的 bug），是该继续修，还是该停下来回头看结构。

你以前没有这个判断，所以你只有一个动作——继续修。而「继续修」这条路有个特点：它永远不会自己告诉你该停了。 这篇就是把那个「该停了」的信号，从感觉变成一个你能数出来的数。

如果只记三句话

如果你只有 5 分钟：看这三节

01 · 起手动作（60 秒，立刻能测出你手上这个项目有没有这个问题）→ 04 · 五条信号（对照你现在正卡着的那一次改动）→ 05 · 反面（防止你从此看什么都像结构问题）。

这篇假设你手上有什么

诚实说在前面：这篇需要一个你自己能跑起来的项目，哪怕很烂。没有项目的话，它对你就是一份说明书，读了也用不上。 具体要什么、缺了怎么办，下一节第一段就说清。

01起手动作：读完 60 秒内做的那一件事

上面那三句话你未必信。没关系，你可以现在就测一次——用你自己上次那次「改完还是不对」的经历测，不用信我。

第一个动作：把这句话发给 AI，然后只数一个数

打开你和 AI 的上一次对话。就是那一轮：你说了哪里不对，它改完，你还是觉得不对（或者它说改好了，回头又坏了）。把下面这段原样发过去：

先别动代码。只回答三个问题：
1. 刚才那次改动，你一共动了几个文件？一个一个列出来。
2. 每个文件里你改的，是「同一件事」的哪一份？
3. 这件事在项目里现在一共存在于几个地方？

不确定的地方就说「不确定」，不要猜。

然后你只做一件事：数第 3 问的答案。

做这个动作之前，你手上必须有什么

两样，缺一不可。这一栏比上面那一栏重要——它让你在花时间之前就能判断这篇对你有没有用：

想现在就用上：把同一个问题提前问一次

上面那个动作是回头测。你也可以在让 AI 动手之前先问一遍——只要 30 秒，而且比事后追问更值：

这件事你打算改哪几个文件？先列出来，先别动手。
如果同一件事在项目里存在多处，把它们一并列出来。

这么做的好处是它给你一份预期。等它真的改完，你看到实际改动范围，超没超你一眼就知道——不用读代码，你只需要对比两份清单。这一步解决的是「它顺手改了我没让它碰的东西」，和这篇要解决的结构问题是两件事，但两件都值得做。

02「结构问题」是什么：一个你能数出来的数

先破掉一个误会：它跟代码好不好看没关系

你大概听过「代码乱」「代码丑」「屎山」这类说法。它们听着像同一件事，其实不是。「丑」是审美，「结构问题」是算术。

一份代码可以写得很丑，但同一件事只有一处——那它在改动上是健康的，不是结构问题。反过来，一份代码看起来很整齐（每个文件都短短的很干净），但同一条规则存在四个地方——那它就是结构问题。判据跟美丑无关，只跟「同一件事有几处」有关。

这个区别对你很实际：因为你看不见美丑（你不读代码），但你能数得清处数。这篇从头到尾都在用你能拿到的那一个量。

正向的定义：同一件事被存在了不止一个地方

一句话：同一件事在项目里存在几处，决定了你改一次要付出几倍的力。

当它存在 1 处，「改对」只需要改一次。当它存在 3 处，「改对」就变成了「三处都记得改」——而「记得」不是一种能力，是一种运气。你之前那些「改完还是不对」，绝大多数不是改错了，是漏了一处。

这件事在软件工程里有个名字，也有出处。Martin Fowler 在《重构》第一版（1999 年）第 3 章「代码里的坏味道」里，把它叫做霰弹式修改。（《重构》是一本书的书名，指的是「改变代码的内部组织方式，但外部行为一个字不变」这类做法；「坏味道」= 那些一看就知道不对劲、但还不能算错的征兆。这两个词 06 节还会细讲。）他的原话大意是：每次你想做一种改动，都不得不对很多个地方各做一点小修改；当改动散得到处都是的时候，它们很难被找全，而漏掉重要的一处太容易了。

他在同一节里还给了反面：一个地方因为好几种互不相干的原因被反复修改，叫发散式变化。这一节的收束句值得抄下来——理想状态下，一种常见的改动，应该只对应一个地方。

为什么阈值是「3」，而不是「2」

同一个来源里还有一个经验法则，叫三次法则（Rule of Three）。Fowler 说这是 Don Roberts 给他的，原话大意是：第一次做某件事，你直接做；第二次遇到类似的事，你会为重复皱一下眉，但还是照做一遍；第三次再遇到类似的事，你就该动手整理了。

为什么 2 不够、3 才算：两处相像，可能只是相像。 两个不同页面上的按钮恰好用了同一个颜色，那不是「同一件事」。第三处出现，说明有一条规则被抄了三份——它是个模式，不是巧合。

它和「技术债」「代码烂」是什么关系

那些词是笼统的说法，你没法拿它们做决定——你没法数「有多少债」。这篇给的是一个能数的量：同一件事现在有几个落点。能数出来，才能比较、才能判断该不该停。你以前的困境不是缺判断力，是缺一个可数的东西。

03为什么「再修一次」只会让事情变多

这一节解释的是你最想搞明白的那件事：为什么不管怎么修，问题都会涌现出来。

先把你走过的那个循环写出来

如果你有过这种感觉——发现一个 bug，让 AI 去改，它改完，问题没解决，反而多出来两个；再改，又多出来——这不是你运气差。这是一个稳定的循环，走进去的人都会走到同一个地方：

关键在后面那一步：「加新的」这个动作本身，就在给系统添东西。 你不是在失败，你是在按这套循环的规则正确地运行。所以问题不在意志力，也不在「底子太差」。

机制一：改症状，不改根因 → 错从别的地方冒出来

同一件事存在 3 处，AI 只改了它读到的那 1 处。另外 2 处还按老规矩运行。于是你看到的现象是「修好了 A，B 又不对了」——那个 B 不是新问题，它是同一件事的另一份，一直就在那里，只是你上次没走到那条路上。

机制二：一次改太多处 → 出了新问题，你也不知道是哪一处引起的

很多 AI 会顺手把另外两处也一起改了，有时还顺手改了点别的。这时候它「改好了」，但出了问题你无法定位：你没有「一次只改一件事」这个对照。 三个地方同时变，错在哪一处，只能靠猜。

机制三：它只看得见它读到的文件 → 每次都是局部最优

这是三条里最根本的一条。

AI 手里没有一张「这个系统长什么样」的图。它每次开工，只读到被打开的那几个文件，然后在这几个文件的范围里给出一个最优的修改。只看眼前那几行，它改得是对的；把这几行放回整个系统里，这个修改经常是有害的。

更麻烦的是它分不清两件事：「完成你交代的任务」和「因为它发现了更好的做法、所以重塑这个项目」。 在它那边，继续做看起来就等于进展。一个有经验的开发者知道什么时候不该写代码——这个判断目前还不在它那一侧。所以「该停了」只能由你说。这句话不是推给你，是它真的给不了。

于是「越修越多」不是意外，是算术

把三条合起来看：每修一次，如果落点没有减少，你就多了一处「下次必须记得的地方」。 下一次改动要动的处数只会增加，不会自己减少。这就是为什么修到后来，你的信心比代码先垮——因为你无法预测下一步会不会更好。信心来自「我能预测下一步会发生什么」，而落点数不清，就没法预测。

有一条实证能说明「在乱的地方继续修」这条路成本是往上走的（口径是观察性统计，不是因果证明）：2022 年的一项研究统计了低质量代码与高质量代码的对比——低质量代码里的缺陷数量是高质代码的 15 倍以上；在低质量代码里解决问题，平均要多花 124% 的时间，最长处理周期长 9 倍（Tornhill & Borg, Code Red, arXiv:2203.04374）。

所以这一节要给你的不是安慰，是一个算术结论：你不是在修复，你是在给下一次的「必须记得」名单上加一行。

04五条信号：该停下来的那一刻长什么样

这五条有一个共同点：都是你能亲眼看见的，都不需要你读代码。 按「最容易先撞上」的顺序排——第一条是主信号，后面四条是它的各种变形。

信号 1（主信号）· 同一件事落在 3 处以上

你看见什么：AI 说「我改了 order.ts、cart.ts、checkout.ts」——三个文件（.ts 结尾的是代码文件，一个文件大致相当于一页纸，里面装着一部分代码），而这三个文件里改的是同一条规则，比如「满 199 免运费」。

它说明什么：不是「三个文件」多，是同一条规则有三份。规则本身只有一条，项目里却存了三份，所以你每改一次规则，都要记得三处。

这一刻你该做什么：用 01 节那三问，把第 3 问的数字拿到手。数字 ≥3，停。

别搞错的地方：改了 3 个文件、但改的是 3 件不同的事（比如三个页面各自的文案），不算信号。单位永远是「同一件事」。

信号 2 · 同一处坏了第二次

你看见什么：上个月修过的地方，这个月又坏了；或者你从另一个入口进去，发现它还是坏的。

它说明什么：bug 修好了就不该回来。回来只有两种可能——上次修的是症状（另外几处没动），或者你从另一个入口进去碰到的是同一件事的另一份。两种情况都是结构问题。

重要的数字：第二次就够了。不用等第三次。同一处坏第二次，是这五条里最快能确认的一条，因为它不需要你问 AI 任何问题——你记得，你上次就修过这里。

信号 3 · 修 A 引出 B

你看见什么：你说「按钮点了没反应」，它改完，按钮好了，表单提交坏了。

它说明什么：不是它手笨，是 A 和 B 共用着同一处东西，而那一处只有一份、被两件事同时拉扯。你改那一处，代价由两处一起承担。这个现象在软件工程里被专门研究过，有个名字叫「引发修复的改动」——确实有一类改动，它本身会引出后面的修复（Śliwerski / Zimmermann / Zeller, MSR 2005）。

这一刻你该做什么：先别让它「再修一次 B」。修 B 会让共用那一处继续被拉扯，下一次坏的是 C。先问：「A 和 B 是不是共用同一处东西？如果是，那一处现在有几份？」

信号 4 · 你要把同一条规则交代第二遍

你看见什么：「别忘了订单页也要加」「上次说的那个，这里也适用」。你说过一次，又得说第二次。

它说明什么：你说第二遍的那一刻，就证明了那条规则在项目里没有唯一的存放处——它散着，所以每一次都得重新告知一遍。这条是所有信号里最早出现的，也是最容易被忽略的，因为它不疼：只是多说一句话而已。但它是在替项目记住一件事，而那份记忆不在项目里，在你脑子里。

信号 5 · 你说不清「这个功能在哪几个地方」

你看见什么：有人问「这个功能在代码里在哪」，你答不上来，只能说「AI 知道」。

它说明什么：你答不上来，AI 也只能靠猜（它只读得到被打开的文件）。这一条是其他四条共同的源头：那个「系统长什么样」从来没有存在于任何地方——不在你脑子里，也不在任何文件里。这就是 03 节「机制三」里说的盲区的来源。

这一刻你该做什么：注意，这一条的解法不是「读懂代码」。这个动作对你不成立，也不需要成立。可做的动作是问 AI 要一段文字答案：

这件事（比如「运费怎么算」）现在在项目里存在于几处？
每一处在哪个文件、大概负责什么？
用中文回答，不要贴代码。

你能判断这段文字对不对——那是你的项目，你知道运费是怎么回事。你判断不了的是代码写得好不好，那不需要你判断。

五条信号速查

读第二遍的时候直接查这张表。第三列是这一刻该做的事，和上面的正文不重复：

05反面：哪些是真的 bug，照常修就行

这一节和前面同样重要。这篇的目的不是让你从此看什么都像结构问题。 过度反应和反应不足一样贵，而且过度反应更容易发生——因为它感觉更专业、更有掌控感。你会开始说「这里得重构一下」，而其实只需要改一个错别字。

判据只有一句：下一次同类的事来了，你还要不要走同一遍

这一问的好处是它不需要你懂代码，只需要你回顾：「这种事我以前遇到过吗？以后还会遇到吗？」 这个你答得了。

五类「照常修就行」

另一个方向的警告：别急着「合并重复」

你已经受过一次「重复」的苦，所以很自然会产生一个冲动：一看到两处长得像，就立刻让 AI 把它们合并成一处。这个动作会做错，而且做错了比重复更难拆。

Sandi Metz 在 2016 年写过一篇《错误的抽象》，核心两句：重复远比错误的抽象便宜；而一旦你造出了错误的抽象，最快的出路是往回走——把合并出来的东西再拆回给每个用到它的地方（「调用方」），重新容忍重复。她还给了失灵的信号：合并出来的那份东西上，每次用它要传进去的东西（「参数」）越加越多、里面「如果是 A 就…否则就…」的分岔（「条件分支」）越加越多，就说明它已经不再代表「同一件事」了。

所以当 AI 说「这里有两处重复，我把它提取成一个公共函数吧」（公共函数 = 把几份一样的写法收成一份，让几处都去用它），而你手上还没有第三处证据的时候，你可以直接说：

先别合并。等第三次真的出现再说。

还有一个时机问题：别在「今晚就要用」的时候停

如果你现在正需要它工作——今晚就要用、明天要给人看——那就先打补丁让它能用，把「收落点」排到能用之后。

但有一个条件：延期要写下来。 不写下来的延期，会变成永久的「以后再说」，而「以后」不会自己到来。写一句话就够了：「运费规则现在散在三个文件里，等这版用完要收成一处。」——这句话写在哪儿都行，只要是你下次会看到的地方。

06停下来之后：把 3 个落点收成 1 个

「停下来」这三个字，在你以前的经历里很可能等于「重写」——因为过去你停下来之后的结果，就是项目烂尾。所以你会本能地抗拒停。但停下来不等于重写，这两件事之间差得很远。

先分清「重构」和「重写」

分界线只有一句话：「你能不能在每个中间状态都发布？」（中间状态 = 整理到一半、还没全部做完的那个时候；发布 = 把新版本放出去给人用）能，是重构；不能，是重写。（本站另一篇《用 skill 维护老项目》§05 的「三组最容易搞混的词」把这条讲得更细，可以对着看。）

但对你要补的只有一件：你不需要现在决定要不要重写。 你要做的第一步比这两者都小——小到不构成一个「项目」，只是一次改动顺手做的事。所以它不需要排期，也不需要信心。

第一步：收落点。验收标准是「行为一件都没变」

Kent Beck 在《Tidy First?》（2023）里给过一个很有用的区分：把改动分成结构改动和行为改动。他的说法是：结构改动大体上是可以回退的，行为改动往往不可逆，而把这两者分开，本身就有价值。

这条给你的直接好处是——它给了你一个能验收的标准。 你不需要判断代码写得好不好（那本来就不是你的位置），你只需要判断一件事：

三步做完，以及每步该说的话

先别改。只回答：这件事在项目里现在存在几处？
每一处在哪个文件、写法差在哪？用中文说，不要贴代码。

把这几处收成一处。留下的那一份要改得能覆盖现在所有情况。
要求：外部行为一个字都不变——所有功能的表现必须和现在完全一样。

现在这件事在项目里只剩一处了吗？
如果你不确定，就说「不确定」，不要猜。

下次直接用的话（都收在这里）

先别改。只回答：这件事在项目里现在存在几处？
每一处在哪个文件、写法差在哪？用中文说，不要贴代码。

把这几处收成一处。要求：外部行为一个字都不变——
所有功能的表现必须和现在完全一样。改完告诉我点哪里可以验证。

只改我点名的文件。如果你觉得别的文件也该改，先列出来问我，不要直接动手。

为什么不用专门排一个「整理时间」

一个很有用的提醒，来自 Fowler 在《重构》里谈「什么时候该重构」那一节。他大意说：几乎在所有情况下，我都反对专门腾出时间来做重构。 你不是决定去重构——你是因为要做别的事，而重构能帮你做成那件事，所以顺手做。

对你的意义很直接：不要给「整理」排期。 排期会把它变成一个没有截止日期的大工程，而那正是它一直没发生的原因。正确的时机只有一个：下一次你本来就要改这件事的时候。 那时候你本来就要动它，收落点只是顺手——而且不做的话，你这次又要改三处。

07最小例子：一条运费规则散在三个文件里

这是本篇唯一的完整走查。它演示的就是最要紧的那件事：结构问题一开始长得完全不像结构问题。

事情的经过（注意每一次都「修好了」）

你让 AI 给一个小店后台加一条规则：满 199 免运费。

三次都是「改一处、好一处」。 所以它长得完全不像结构问题——没有一次改动落在 3 处，每一次都干净利落。你甚至会觉得这个项目挺健康的。

现在把 01 节那句话发给它

你问：「这件事在项目里现在一共有几个地方在算？」答案是 3。

然后你让它把这三处贴出来对比。你会看到类似这样的东西：

order.ts      满 199 免运费     →  if (total >= 199)
cart.ts       满 199 免运费     →  if (total >= 199)
checkout.ts   满 199 免运费     →  if (total >= 200)

收落点：留下最符合你意图的那一份

你确认「满 199 免运费」才是你要的（那两处是对的，200 那处是错的）。于是：

收完之后，什么变了

08三个最容易误判的场面

这三处是「反应不足」和「过度反应」各自的高发区。每一条都给一个区分法，区分法都不需要你读代码。

误判一：把「代码丑」当成结构问题

你的感觉：「这一堆乱糟糟的，肯定有问题。」

为什么错：丑和落点数是两件事。一份很难看的代码可能同一件事只有一处，改起来很顺；一份看起来很整齐的代码可能同一条规则存在四处。

区分法：别问「它好不好看」，问「同一件事有几处」。前者你判断不了也不该判断，后者你数得清。

误判二：把「AI 顺手多改了几个文件」当成结构问题

你的感觉：「它动了 5 个文件，肯定是结构问题。」

为什么错：AI 常常顺手改格式、加注释、动一个你根本没提的文件。那叫越界，是范围问题，不是结构问题。它说明的是「你没有把范围框住」，不是「你的代码有结构问题」。

区分法：看这几个文件改的是不是同一件事。不是同一件事 → 那是范围问题，用 06 节第四句话（「只改我点名的文件」）挡回去就行。这也正是为什么 01 节那三问里的第 2 问（每一处改的是「同一件事」的哪一份）不能省。

误判三：把「难修」当成结构问题

你的感觉：「这个 bug 找了好久才修好，说明结构有问题。」

为什么错：难修的意思是找不着；结构问题的意思是找着了，但改一处不够。这两件事的解法完全不同：前者是定位问题（多看几处、把现象描述得更准），后者才是本篇讲的事。

区分法：问自己「找到了以后，改一处就够了吗？」找到了、改一处就够 → 那只是难找，不是结构问题。

三个场面对照

09术语速查：这几个词别混

都是本篇出现过的词。第三列回答的是「什么时候它会帮到你 / 别把它当成什么用」——如果你只需要记一件事，记着别把它们互换着说。

10场景索引：你现在的处境 → 该看哪一节

不用从头读。找到你现在那句话，直接跳：

11来源与证据边界

一手来源

• Martin Fowler《重构：改善既有代码的设计》第一版（1999）第 3 章「代码里的坏味道」——霰弹式修改与发散式变化的定义与收束句、第 2 章「什么时候该重构」里的三次法则（Fowler 注明是 Don Roberts 给他的）、以及「反对专门腾出时间做重构」那段。
  版本提示：引的是一手第一版。第二版（2018）把原理与坏味道两章大改，Fowler 自己在 refactoring-2nd-changes 里说「我猜四分之三变了，但那是感觉不是实测」。两版保留了两个名字与含义，措辞有差异。
  另一个必须说的：refactoring.com 上并没有坏味道目录（那里的 catalog 收的是重构手法），所以这两个 smell 没有「官方在线定义页」，只能引书。网上常见的 refactoring.guru 页面是第三方整理，不要把它当成 Fowler 官方。
• Kent Beck《Tidy First?》（O'Reilly, 2023）——结构改动与行为改动的区分。原话见 Beck 自己的通讯：Distinctions with a Difference（「结构改动大体上可逆」「行为改动往往不可逆」「把行为改动和结构改动分开，本身创造价值」）。
  口径提醒：网上流传的「两者绝不能混在同一次提交里」没能在 Beck 原文里核到，那些都是书评人的转述。本篇写成「Beck 的主张」，没打引号当原话。
• Sandi Metz《The Wrong Abstraction》（2016）——sandimetz.com/blog/2016/1/20/the-wrong-abstraction（「重复远比错误的抽象便宜」「最快的出路是往回走」，以及参数与分支越加越多这个失灵信号）。
  归属提醒：「第三次才抽象」是三次法则（Fowler 转述 Don Roberts），不是 Metz 说的。两条依据独立，本篇分开写。
• Tornhill & Borg《Code Red: The Business Impact of Code Quality》（2022）——arXiv:2203.04374：低质量代码的缺陷数量是高质代码的 15 倍以上；在低质量代码里解决问题平均多花 124% 时间、最长处理周期长 9 倍。
  证据边界：这是观察性统计，支持相关推断，不是因果证明。 它说明的只是「低质量与高成本同时出现」，不能证明「因为质量低所以慢」。
• Śliwerski, Zimmermann, Zeller《When Do Changes Induce Fixes?》（MSR 2005）——st.cs.uni-saarland.de：提出「引发修复的改动」这一概念，用来支撑 04 节信号 3。
• 本站另一篇《用 skill 维护老项目》（ai-legacy-code-maintenance.html）——本篇从它那里借了三样：重构与重写的分界线（§05「三组最容易搞混的词」）、护栏原话「只改我点名的文件」（§03 的 CLAUDE.md 样例）、以及 AI 越界与级联扩大的成套一手 issue 证据（§08）。两篇不重复：那一篇讲的是「装哪几个 skill、按什么阶段调用」，本篇讲的是「在我还没决定要不要动手之前，先判断这是不是结构问题」——正好是那一篇 §09 没有覆盖的一格。

本篇没有核到的东西

• 没有权威一手来源把「反复修同一处 / 修一个引出一个」命名为某个专门术语。 网上流传的说法多半是低质量二手内容，所以本篇没有引它，改用了 MSR 2005 的「引发修复的改动」这个有出版来源的概念来代替。
• 「3」这个阈值没有精确的实验来源。 它来自三次法则这个经验法则，加上实践中反复观察到的现象。本篇把它当「提醒你抬头的闹钟」而不是定律，理由写在 02 节。

时效性

这篇讲的是原理，不引版本号、价格、或者会变的费率，所以它不容易过时。唯一两处版本敏感的地方已经在上面标出来了（《重构》第一版 vs 第二版、Beck 那句话的转述问题）。

99一句话总结

最后一件事：这五条信号你不需要一次全记住。 下次再遇到「改完还是不对」，你只做 01 节那一个动作——把三句话发给它，数第 3 问的答案。数一次，比读十篇都管用。