给一个已成型的项目画结构图：不读一行代码，画出「有哪几块、谁用谁、谁在改同一份数据」

0030 秒速览：三句话、起手动作、以及你手上必须有什么

如果只记三句话

起手动作：读完 60 秒内，你要做的第一件事

打开你手上最小的那个半途项目（烂尾的、你看不懂的，都行），让 AI 编程助手（能读你电脑里文件的那种 AI 工具）读一遍它，然后问一句话（你打给 AI 的那段话，行业里叫「提示词」）：

# 这是一段提示词，整段复制，粘给 AI 编程助手
先不要解释任何代码。把这个项目分成 5 到 15 块，每块给我：
1) 一个中文名字，不要用行业词
2) 一句话：它负责什么
3) 它包含哪些文件或目录，列路径
不确定的地方标注「不确定」，不要猜。

但在按下回车之前，先做一个小动作：拿张纸，写下你猜它会列出几块。然后发送，对一下差多少。

为什么要先猜？因为这一猜，就把这件事从「听 AI 汇报」变成了一次实验。你的猜测和它的答案之间的差距，就是这个项目里你还没看见的那部分。第 6 节会把「先猜、再改、后对账」这套动作拆开讲——它是全文最值钱的一段，而你现在做的正是它的第一步。

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

手上没有项目？那这篇文章你照样现在就能练——全篇的例子用的是 ai-teach 这个站本身，也就是你正在读的这个网站。它就在你手上、你天天看、而且它小到你几分钟就能走完一圈（第 5 节）。等拿它练完手，再回去开你那十几个烂尾项目里最小的那一个。

数字先给量级

这篇里会反复出现几个数字，它们都来自这个站自己，而且你随时可以自己数一遍（命令在最后一节）：

注意第一行和第二行，跟第三行的差别：都是「一个东西被很多地方用」，但第一二行只有一处能改，第三行有三十几处能改。这个差别就是这篇文章的全部要害。

01先破一个错想：这件事不是「读懂代码」

你可能已经这样想过了

这个想法非常合理，而且它合理得值得说清楚为什么——因为如果它是个明显的蠢念头，你不会被它挡住这么久。

它有三个看起来很硬的理由：

真相是：你要画的关系，AI 读代码就能给你

把这件事拆开，其实是两个人的活：

这里有个关键区别，值得单独说一句：AI 是从「写下来的文字」推关系，你是从「改一下之后真的发生了什么」看关系。文字会说谎——某个文件里写着「用到了订单模块」，但那段代码可能从来没被执行过。行为不会说谎。

所以你的位置不是「不如 AI」，而是补上了 AI 唯一缺的那一环：AI 给你一张申请的图，你负责验它。验完，这张图才从「AI 说的」变成「你知道的」。

一个类比：这张图像大楼的消防图

为什么「关系」比「代码」更要紧

回到你真实的那个感受：「修 A 出 B，越改越多」。

这件事几乎不会发生在「代码写错了」的时候。代码写错了，你改那一行，它就对了。它发生在你以为你在改一个地方，其实你同时改动了另一个地方的命根子的时候。

而「另一个地方」在代码里通常长得跟你改的东西毫无关系——它可能是另一个文件、另一个页面，甚至另一份配置（存设置的那份文件）。你从字面上看不出它们连着。这就是为什么你需要一张图：图上画的就是那根看不见的线。

02表一 · 有哪几块：把项目分成 5 到 15 块

这张表长什么样

就长这样。没有一行代码，没有一个你听不懂的词，长度不超过一屏。

最容易搞错的一处：文件列表不等于「块」

怎么判断一块划得好不好

这条检验你完全可以自己做，不需要懂代码。你需要的只是「这句话读起来别扭吗」的语感。

块的数量：5 到 15 块

• 少于 5 块：说明一块里塞了太多东西，等于没分。这时候你仍然不知道「改这个会牵动什么」——因为那一块里的东西彼此毫无关系，却被你并成了一块。
• 多于 15 块：说明你在按文件分，不是在按职责分。或者这个项目真的很大——那也别一次画完，只画你现在要动的那一块，和它周围两三层。

这里有个来自画图规范的建议，可以直接拿来用：C4 模型（一套公开的软件结构画法）明确说「你不需要画满所有层」——它建议多数团队画到「系统上下文 + 容器」这两层就够了，再往下是给要改代码的人看的。来源见文末。

翻译成你的判据：画到「再往下画就需要懂代码了」那一层，就停。那一层之上的所有内容，都是你该管、也管得动的。

03表二 · 谁用谁：每块被别人从哪几个口子用

这张表长什么样

为什么要画这张表：它就是「改动的影响半径」——改了它，波及到哪一圈

这张表回答一个问题：我把 B 改了，谁会跟着疼？

行业里管「A 用了 B」叫 A 依赖 B，管两组东西「一处变了、另一处必须跟着变」这种关系叫耦合。这两个词你以后会一直撞见，现在你知道了：它们说的就是这张表上的箭头。箭头指向你的时候，你就在影响半径里。

这张表最大的用处是看方向：

最容易搞错的一处：把「名字出现了」当成「真的用了」

所以在要提示词的时候，得逼 AI 把「确定的」和「疑似但没确认的」分开列——第 7 节的第二段提示词就是干这个的。

这张表要画多细

判据：画到「你改之前能一眼看出该去哪几个地方看一眼」就够了。

不要试图画全。你不需要知道 A 里的第 37 行调用了 B 里的第 12 行——你需要知道的是「我要动 B，所以我得先打开 A 看一眼」。

04表三 · 谁在改同一份数据：最关键的一张

如果这三张表你只画一张，画这张。你感觉到的「修 A 出 B」，绝大多数出在这里。

先把这张表要抓的东西说清楚

它抓的不是「数据」这个词的字面意思——不只是数据库里的东西。它抓的是任何「同一份东西，在项目里存在不止一处」的地方。

这种东西长什么样？举几个你项目里几乎一定有的：

• 网站上显示的联系邮箱，同时写在页面里、配置里、和邮件模板里——三个地方
• 同一条规则（比如「满 200 包邮」）写在结算页面、活动说明、和后端判断里——三处各写了一遍
• 同一段脚本被复制进每一个页面——三十几处，改一处就得记得改其余全部

它的两种形态，必须分开看（这是最容易混的地方）

「同一份被好几处碰」其实有两种完全不同的情况。它们长得很像，坏的方式却不一样，修法也完全相反。把它们混成一件事，你就会用错药。

这个区分背后有一条老规矩，出自 1999 年的《程序员修炼之道》（The Pragmatic Programmer），原文是：「每一条知识，在系统里都只能有一份、明确的、有权威的表述。」行业里把它缩写成 DRY 两个字。来源见文末。

但注意——这条规矩说的是「每一条知识」只留一份，不是「每一段长得像的文字」都该合并。这个区别很重要，第 9 节会专门讲它，因为搞反了会把事情弄得更糟。

这张表长什么样

四列，缺一不可。下面这张表举的例子，是这个站自己——下一节会带你把它完整走一遍，这里先看一眼形态：

现在回头看这张表，注意一件事：第一行和第二三四行的差别，不是「被多少处用」，而是「有多少处能改它」。

为什么这张表的杀伤力最大

回到表一那个「看方向」的说法。共享和复制这两种情况，破坏力之所以大，是因为它们在图上是一条不显眼的线，但在现实里是一整片：

• 它不挑方向。表二的箭头是单向的——A 用 B，你至少知道往哪看。而「同一份数据」是横向的：它把本来毫无关系的几块悄悄地绑在了一起。你的结算页和你的活动说明页在功能上毫无关系，但它们共享同一条规则。
• 它常常不报错。这是最要命的一点。改坏了表二里的一条线，通常当场就报错、页面就打不开。改坏了「复制」型的共享，系统正常运行，只是从某一刻起，两处说的不一样了——而你要到很久以后、以「怎么数据对不上」的形式才发现它。
• 它是你「越改越多」的直接来源。你改完 A，去修 B 的问题，修完 B 发现 C 又不对了——因为 C 和 B 共享着同一条你不知道的规则。你会觉得是自己手笨，其实是这张表你没画。

一个判断题：这张表什么时候算画完了

当你能对着项目里任何一处改动，回答出「这份东西还在别处存着吗」的时候。

答不上来，就继续问。答得上来，这张表就够用了——它不需要完整，它需要的是在你要动手的时候站在你手边。

05最小例子：拿 ai-teach 这个站走一遍三张表

为什么用这个站：你正在读它。它小到几分钟能走完一圈，而且每一处结论你都能自己核对——文末给了核对命令。

先看表一：这个站有哪几块

六块。注意「全站外观」和「交互行为」各只有一份文件——这是好事，先记住，下面会用上。

再看表二：谁用谁

箭头不少。但看方向：它们基本是从上往下的——「生成器」和「校验脚本」站在最上面，读下面所有东西；下面的东西之间只有几条水平线。没有「互相回头指」的死结。

最后看表三：这个站里，谁在改同一份数据

这是全篇的核心。我把这个站里真实存在的三处列出来，按「改一处会牵动几处」从多到少排：

然后，把第四行补上——这个站里不属于这张表的东西：

现在把这两张表并排看——这就是这篇文章想让你亲眼看到的东西：

这个站真的栽过一次

2026-09-16，这个站为了在首页加一张卡片，改完发现要回滚（回滚就是把改动退回去、恢复成改之前的样子）。

表面上看，那只是「加一个卡片」。但按上面这两张表拆开看，加一张卡片要动的是：

「加一个卡片」——本来以为是一处，实际是五处。

这正好是那个信号：一个看起来很小的改动，要动的地方超过三处。出现这个信号的时候，你遇到的不是「一个 bug」（bug 就是程序出错的地方），是「结构问题」——继续埋头改只会越改越多，正确动作是停下来回头看结构。

06不懂代码，怎么知道图画对了：预测 → 扰动 → 对账

这是全文最值钱的一段。前面三张表都是「AI 给你的」——这一段才把它变成「你知道的」。

先说清为什么需要这一步

AI 给你的表，是从文字里推出来的。而文字有两个毛病：

• 它可能写着一段从来不跑的代码（上一节的「那条线是死的」）；
• 它可能漏掉一段绕来绕去的线——两个文件通过第三种方式连在一起，字面上看不出来。

所以「AI 给了三张表」不等于「图上是对的」。而好消息是：验证它，恰恰不需要你懂代码。

方法只有三步：预测 → 扰动 → 对账

对账：三种差，各自说明什么

这个方法为什么不需要你懂代码

这件事在行业里有正式名字，叫影响分析（change impact analysis）。它的标准定义是：「找出一次改动可能带来的后果，或者估计为了完成这次改动还需要改什么。」专业人士用工具做这件事（能自动把所有连线画出来的那种），你用一次真实的改动做。名字一样，问的是同一个问题：改了它，还有什么要跟着改？来源见文末。

把它变成数字：改一处，牵动几处

对账完之后，数一下：为了这一个改动，我一共动了几个地方？

「改一个小东西要动三处以上」——这是你能拿到的最有用的一个信号。它不要求你懂代码，只要求你数数。

现在就能做的一次实验（拿这个站）

这个站里有两处「会喊疼」的耦合，都配了自动检查。你可以直接做一次：

# 第 1 步：先数一下，现在有几处存着同一段脚本
# （"ln-theme" 是那段脚本里独有的一个词，用它来把存了副本的文件全找出来）
grep -l "ln-theme" learn/*.html | wc -l
# 你会看到一个三十几的数字 —— 每一份都是一个页面里存的那段副本

# 第 2 步：只改一处（把某一篇文章的那份改坏一个词）
# （cloudflare-overview.html 是这个站里随便一篇文章，换成你看到的任意一篇都行）
sed -i '' 's/prefers-color-scheme: light/prefers-color-scheme: dark/' learn/cloudflare-overview.html

# 第 3 步：让那个自动检查跑一遍，看它会不会告诉你
bash .agents/skills/learn/check.sh learn/cloudflare-overview.html

# 第 4 步：撤回，把项目恢复到改之前
git checkout learn/cloudflare-overview.html

第 3 步会失败，并且明确告诉你：那段脚本跟首页那份对不上了。

你刚才做的，就是一次完整的「预测 → 扰动 → 对账」：你预测「改这一处会出事」，扰动了一处，检查替你确认了。而你全程没有读一行代码。

验到什么程度可以停

不要想验完整张图——那是不可能的，也没有必要。判据是：

07可复制的提示词：三张表各一段，外加一段追问

下面四段话可以整段复制、粘给 AI 编程助手。注意它们的设计意图——这些句子不是客套，每一句都在堵一个具体的漏洞。

第 1 段：要表一（有哪几块）

先不要解释任何代码，也不要贴代码。把这个项目分成 5 到 15 块。
每块给我四样东西：
1) 一个名字，用中文、用日常说法，不许用「服务层」「中间件」这类行业词
2) 一句话说清它负责什么。这句话里如果必须提到别的块才能说清，请直接标注「和 X 块分不开」
3) 它包含哪些文件或目录，列具体路径
4) 改这一块的时候，通常还要同时动哪几个文件
不确定的地方标「不确定」，不要猜。最后用一句话告诉我：哪一块是最大的。

这几句分别在堵什么：「不要贴代码」堵它甩一堆你没用的东西；「不许用行业词」堵它用行话糊弄；「必须提到别的块就标注」就是你第 2 节那条「一句话检验」的自动化；「改这块还要动哪几个文件」是在逼它按「一起变」来分块，而不是按目录分。

第 2 段：要表二（谁用谁）

列出这个项目里「块与块之间的使用关系」，一行一条，格式是：
A 用了 B —— 从 B 的哪个口子用的（具体到文件名或功能名）

只列你确认存在的关系。如果你只是「在 A 里看到了 B 的名字」
但找不到真的会执行到的地方，不要混进来，
单独列一张「疑似、未确认」的清单给我。

最后额外回答一个问题：这些关系里，有没有互相指的（A 用 B，B 也用 A）？
如果有，单独列出来 —— 这是我最关心的一组。

关键在中间那句：把「确定的」和「疑似没确认的」分开。这正是第 3 节说的那个坑——「名字出现了」不等于「真的用了」。最后那句是让它主动把「互相指」的挑出来，因为那是麻烦最集中的地方。

第 3 段：要表三（谁在改同一份数据）——最重要的一段

停。现在只回答一个问题，不要讲别的：
这个项目里，有哪些「同一份东西存在不止一处」或者「同一份东西被不止一处改写」的地方？

不要只找数据库和配置文件。任何一份"被复制过"或"被好几个地方碰过"的东西都算，
包括：同一段代码被抄进好几个文件、同一个数字写在好几个地方、
同一条规则在前后两端各写了一遍、同一个说明文档里的内容和代码对不上。

每一处给我五行：
1) 这份东西是什么 —— 用人能懂的说法，比如「首页上显示的更新日期」
2) 它总共在几个地方各存了一份 —— 给我一个数字
3) 谁负责写它 —— 是自动生成的，还是人手改的
4) 谁读它 —— 哪些文件或功能依赖它
5) 如果我只改了其中一处、忘了别处，会出什么事 ——
   请明确告诉我是「会报错」还是「不报错、但结果已经不对了」

最后按「改一处会牵动几处」从多到少排序，第一行应该是最危险的那个。
如果一处都没有，直接说没有，不要凑。

这段里有三个地方是故意的：

• 「不要只找数据库和配置文件」——否则 AI 会给你一张标准的数据库表清单，而你真正的麻烦在别处（比如那段被抄了三十几份的脚本）。后面那串举例就是在给它划范围。
• 第 5 行必须回答「报错还是不报错」——这是整段最值钱的一问。会报错的耦合只是烦人；不报错的耦合才是你真正需要知道的那个（第 4 节解释过为什么）。
• 「如果一处都没有，直接说没有」——这句是防它硬编。你问它「有哪些问题」，它天然倾向于给你找出几个来，哪怕没有。

第 4 段：它开始甩代码 / 说行话的时候，用这段

停。不要贴代码，也不要用「解耦」「抽象」「服务层」这类词。
用一句话回答我：这段代码是「谁改了什么」？
如果不能用一句话说清，就告诉我「说不清，因为……」。

这一段你会在整个过程中反复用到。它不是防 AI 犯错，是在防你自己糊弄自己——「我看不懂但好像很专业」这种状态下点下去的那个「好的」，是你后面所有麻烦的起点。允许 AI 说「说不清」，比逼它给一个你听不懂的答案有用得多。

用这些提示词的时候，怎么读它的回答

08画完之后怎么用：改之前看图，改完更新图

改之前：三个问题，答完再动手

这就是这张图存在的全部意义。在你要改任何东西之前，先问三个问题——三张表各出一个：

三个都答得上来，你再动手。答不上来的时候去问 AI——问法就是上一节那四段话。

改完：更新图，而且只改那几行

所以图要跟着改。但更新图不等于重画——那太重了，重到你第二次就不会做。最小动作是：

• 这次改动牵动了哪几条线？只改那几行。
• 如果发现了一条以前图上没有的线（「原来改这里还会影响那里」），把它补上——你刚刚花代价学到的东西，不记下来就白付了。
• 把图上的日期改成今天。

把它放成一份文件，放在项目里

不要留在聊天记录里，也不要只存在脑子里。写成一份文件放进项目目录，名字随便（结构图.md、项目地图.md 都行），内容就是那三张表加一个日期。

两个好处，都很实际：

1. 下次你忘了，能查。你手上有十几个项目，隔两个月回来，你不会记得任何一个的细节。
2. AI 也能读它。下次你让 AI 改这个项目的时候，它自己会看到这份文件——于是它做的判断会带着这些关系，而不是从零重新猜一遍。

09什么时候别做这件事

这一节和前面同等重要。前面教你怎么做，这一节防你做过头——而做过头这件事，会让一张好方法变成新的负担，然后你就再也不会用它了。

四种别做的情况

别做过头：长得像的文字，不等于同一份知识

这是「谁在改同一份数据」这张表最大的误用，值得单独讲。

你学会表三之后，会很想把「所有重复的东西」都合并掉。但其中有一部分不该合。

这个区分不是我编的：前面说的那条「每条知识只留一份」的老规矩，配套就有一条明确的提醒——「巧合的重复」不应该被当成重复来处理，硬合并反而会造出错误的抽象。来源见文末。

还有一个反向的边界

这个方法也有它看不见的地方。它只看「关系」，不看「好坏」。

一张画得完全正确的结构图，可能对应着一个写得很烂的项目，也可能对应着一个写得很好的项目——图上看不出来。所以：

• 它不能回答「我该不该把整体结构翻新一遍（行业里叫重构）」「这个项目的设计好不好」；
• 它不能代替测试——它能告诉你「改这里可能牵动那里」，但不能告诉你「那里现在到底对不对」；
• 它只能回答一个问题：我要动的这个东西，会牵动什么。

知道一个方法管什么、不管什么，你才不会在它失灵的时候以为是自己做错了。

10五个一定会撞上的误解

这五条是你真做的时候会遇到的，不是假想的。

11一页纸速查

三张表，各一句话

验证三步

看到这些信号就停下来

你手上必须有什么（再强调一次）

• 一个已经存在的项目目录（本文不教从零建项目）
• 一个能读你本地文件的 AI 编程助手——不是网页聊天窗口
• 一个能撤销改动的方式（用 git 管着，或者先复制一份整个文件夹）

三样都没有也没关系：拿这个站练。它就在你手上，例子全篇都是它。

12来源与证据边界

外部来源

一手材料：这个站自己

第 5 节里那些数字（三十几份副本、1 份样式、2 处日期）是我在 2026-09-16 当天在这个仓库里实际数出来的。你可以自己复核：

# 有多少个页面，就存着多少份那段「深浅色」脚本的副本
grep -l "ln-theme" learn/*.html | wc -l

# 全站样式有几份？（数出来是 1 —— 这就是"干净的那种"）
ls learn/style.css | wc -l

# 首页卡片上写着的日期，和文章里写的日期，是两处；校验脚本会逐个比
bash .agents/skills/learn/check.sh --index

「三十几」这个说法是故意含糊的，因为它本来就是个会变的数字：它等于「这个站里有多少个页面」。我写这篇的那天数出来是 34 份，而你读到的时候多半已经更多了——每加一篇文章，就多一份副本；你正在读的这一篇，自己也是其中一份。

这正好又是这篇文章在讲的那件事：一个数字存在多处，而且还会各自变化，那么写在文档里的那个版本迟早对不上。所以要准的，别信任何文档里写的数字，用上面的命令现数。

证据边界

• 关于这个站的数字：全部是 2026-09-16 的实测值，命令已给出。项目一改，数字就变。
• 关于那次回滚：第 5 节提到「2026-09-16 为了加一张卡片，改完要回滚」。这件事我是按你知道的情况写的；它具体卡在哪一步我没有逐条核对。但上表列出的「加一张卡片要动五处」是我照着校验脚本的实际检查项数出来的。
• 关于外部来源：C4 官网那一页只说了「不同层级服务不同的人」，没有逐一指定「哪一层给谁看」——所以我没有编造这种对应关系，只取了「画到哪一层为止」这一条。
• 方法本身的边界：这套手工验证法没有经过实证研究检验，它是我从「影响分析」的标准做法推导出来的手工版本。它在小项目上很好用；项目越大，能靠「改一下看会怎样」覆盖到的范围越小，那时需要专业工具。

99一句话总结

留给你自己验的那一条

这篇文章里所有结论我都能替你验，除了这一条——它只能你来。

拿出你手边那个最小的半途项目，试着回答：这个项目里，有哪一份东西是「存了不止一份」的？（提示：先别想代码。想想有没有同一个邮箱、同一个数字、同一句说明文字，你记得自己改过两次。）

然后想一想——它有没有一个自动检查盯着？如果没有，你就知道那个「越改越多」是从哪来的了。