怎么给一个模块定边界

01速览、起手动作、以及这篇假设你有什么

读完这一篇，你能做到一件事：拿你手上任意一个已经乱掉的项目，挑出一块该收口的东西，把它变成"负责一件事、别人只从一个口子进"的样子——而且知道怎么验证你没收错、没收过头。

"口子"到底指什么：别人找它的时候，必须穿过的那几样东西——它叫什么名字、你递给它什么、它还你什么、用它的先后顺序、出错时它会怎样。§02 会用一家饭馆把这件事讲透。这篇里你只要记住这一个词就够，不需要任何别的术语。

如果你只有 5 分钟

只看两处：§04 那个判断法（怎么数口子），和 §05 的动作一、动作二（怎么选一块、怎么在动它之前先钉住它）。其余部分是你真动手那天回来查的。

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

不要读代码（你不读代码），也不要先想"我的项目该怎么整理结构"。你就打开一个项目，把下面这段话原样发给你的 AI（这段要发给 AI 的话，下文都叫"提示词"——就是你要打给 AI 的那段字）：

# 起手提示词（原样复制，把"这个项目"换成你的项目文件夹）
看一遍这个项目。列出被最多地方用到的 5 样东西。
对每一样，写清楚三件事：
1) 它是什么（一句话，用日常话，不要用专业词）
2) 哪些文件用到它
3) 用到它的每一处，各自从它身上"拿了什么"
   （是整块拿去用？只拿走里面某一项内容？只调用了它的某个动作？还是依赖它的文件名/格式？）
最后告诉我：这 5 样里，哪一样的"用法种类"最多、最杂。

你只需要看最后那一句的答案。那一样东西，就是你今天要划边界的那一块。（为什么是"用法种类最多"而不是"被用得最多"，§04 会讲。）

这篇不适合谁

放在这里说，不占开头的位置：如果你手上还没有任何"写了一半、还想继续改"的项目，这一篇你读完也用不上——它是给"手上有一堆烂摊子、还得继续在上面加东西"的人写的。另外，如果你现在正打算把某个项目推倒重写，也不用划边界：推倒重来是另一条路（而且多半更贵，见 §08）。

02边界长什么样：两句话，不是一个词

先破一个误会。边界不是一个你能"设计"出来的东西，也不是"把东西分分层""让两块互不依赖""设计一套接口"这类说法（接口就是"口子"的正式叫法；这些说法各自都在讲同一件事，只是换了词——§10 有一张对照表）。它是一个能被你肉眼验证的状态——验证方式就是那两句话。

先说"一块"是什么

这篇里说的"一块"，不一定是别人嘴里那个"模块"（模块：一块能单独拿出来说的东西）。它可能是：

• 一个文件（比如网页里管"导航栏"的那个文件）
• 一个页面上的东西（比如首页那排文章卡片）
• 一个能被单独调用的动作（比如"把文章发布出去"这一整套）
• 一个后台服务（比如专门管用户登录的那个）

判断标准只有一条：你能把它当成一个东西来说吗？"这块管的是文章卡片"——能这么说，它就能是一块。你不需要先学会技术上的分类，只要认出"这一块"就行。

用一家店来理解"边界"

你见过的小饭馆，几乎都有边界，而且你从来没觉得那是个"设计"：

把这张图搬到代码上，"口子"具体是什么？就是别人找它的时候，必须穿过的那几样东西。包括：

• 它叫什么名字（别人靠名字找到它）
• 你递给它什么、它还给你什么
• 用它的先后顺序（必须先做 A 再做 B 这类规矩）
• 出错的时候它会怎样（是直接停，还是还你一个"失败"）

这四样加起来，就是这个口子的全部。其中任何一样变了，用到它的地方就可能坏。换句话说——"口子"就是你改它之前必须通知的那些人。这句定义比什么术语都好用，后面全靠它。

所以"有边界"就是三个状态

03没有边界，你已经在付什么钱

你可能觉得"边界"是个讲究人的事。不是。没有边界，你此刻正在为它付四种账，而且每一笔你都以为是自己的问题。

这四笔账有一个共同的来源

同一份东西，被好几处同时改。这正好是你如果做过 01（画结构图）时会画出的第三张表——"谁在改同一份数据"。那张表上连到同一个点最多的那些线，就是这篇文章要处理的那些块。

这件事不是新问题：1972 年就有人给出了答案

这正是开头那个"1972"的来历。那一年，一位叫 David Parnas 的人写了一篇论文，专门回答"该怎么把一个系统拆成几块"（出处见文末）。

他的结论跟直觉相反：不要按"先做什么、后做什么"来拆，也不要按"哪几块看起来像一类"来拆。要按"哪些决定以后最可能被改"来拆——把最可能变的那部分收进一块里，只留一个口子露在外面。（他的原话大意是：每个模块负责把一个"以后最可能变的设计决定"藏起来，不让别的模块知道；而它露出来的那个"接口"，要尽量少透露里面怎么做的。本文说的"口子"，就是他说的"接口"。）

五十多年过去，这条结论没变过——你手上那些项目犯的毛病，也还是同一个。

04判断法：这东西别的地方从哪几个口子用它？

这是全文唯一一个你需要背下来的东西。把它写在一张纸上贴显示器上，比记住任何术语都有用。

先看你会得到哪种答案

最后一行值得停一下。很多人以为"没边界"的意思是"结构不好"。不是。没边界的意思是"没人知道它和谁连着"——包括你，包括 AI。在这种状态下改它，不是勇敢，是赌。

最容易搞错的一处：数"种类"，不是数"次数"

这是全文最值钱的一句区分，请慢一点读。

所以"被引用得多"根本不是问题。被引用得多、但用法只有一种，是好事——那叫好用，所有人都在用同一个口子。真正的问题是"用法有几种"。一种 = 一个口子 = 有边界。三种 = 三个口子 = 你得改三处、通知三个人。

怎么数：一条可以原样复制的提示词

# 数口子（把 X 换成你上一步圈出来的那一样东西）
我要给 X 定边界，先要知道它现在有几个"口子"。
请在项目里找出所有"用到 X"的地方（除了定义 X 本身的那一处）。

对每一处，写清楚三件事：
1) 是哪个文件、大概哪一段
2) 它从 X 身上拿了什么：是整块拿去用？只读了其中某一项？改了其中某一项？
   只调用了它某个动作？还是依赖了它的名字/顺序/文件位置？
3) 如果 X 改一个名字、或者把内部结构换个顺序，这一处会不会坏？

最后按第 2 问的答案分组（不是罗列），告诉我一共分成几组、每组有几个地方。
# 关键：它分出来的"组数"，就是口子的数量。组数 > 2 就要收口。

怎么读这个结果：不要看它列了多少个地方，直接跳到最后一行的"分成几组"。几组就是几个口子。如果它只给你一个总数没分组，就回一句："请按第 2 问的答案分组，不要给我总数。"

没有图也能开始（补 01 那条路）

如果你还没做过 01，手上没有那张图，用下面这条提示词，10 分钟能拿到这次需要的最小版：

# 最小版结构图（没做过 01 就跑这条）
看一遍这个项目，回答我三个问题，每个都尽量短：
1) 这个项目大致分成哪几块？每块用一句日常话说它在管什么。
2) 哪几块会用到别块？谁用谁？
3) 有没有哪一样东西，是好几块都在读、或者都在改的？列出来。

不要给我代码，不要给我建议，只要这三条的答案。

拿到第 3 问的答案之后，把里面"被好几块同时读或改"的那几样排个序——选其中你最常碰到的那一样，进 §05。

05从一堆乱代码出发：四步

先把话说死：这一篇讲的不是从零设计。你手上的项目都是已经存在的、一半还跑着、你也不想推倒重来的。所以下面四步的顺序，跟教科书里的顺序是反的：

教科书：先想清楚这块该负责什么 → 设计好口子 → 再写。
你：先把口子收窄（外面改动最小）→ 再让里面慢慢变干净 → 最后才写"它负责什么"那句话。

为什么反着来才对：因为你的目标不是"得到一份好设计"，是下一次改它的时候别出事。而下一周就要改，等不到你先想清楚。

动作一：选出血点，不要选整个项目

你想划的那个东西，几乎一定是"整个项目太乱了"。那就一定做不完。所以第一步是砍范围。

动作二：先钉住它现在是什么样，再动它

这是最容易跳过、也最贵的一步。跳过它，前面省下的两小时，会在两周后以"不知道哪儿坏了"的形式还给你。

为什么必须先钉住

改结构的时候，最常发生的失败不是"改坏了"，是"改坏了你不知道"。它可能三周后才在某个页面上露出来，那时候你已经改了十几个别的地方，根本不知道是谁干的。

所以要做的是一件很朴素的事：在动它之前，先把"它现在是什么样"记下来。记下来之后，你改完再验一遍，两次结论一样 = 你没改坏行为，只改了结构。

# 动作二：钉住现状（把 X 换成动作一里写下的那个名字）
请给 X 写一组"只描述现状"的检查。
要求：
1) 不要修正任何看起来像毛病的地方，现在是什么样就记什么样。
2) 至少覆盖 3 个正常情况 + 2 个边界情况（空的时候、特别多的时候、缺东西的时候）。
3) 每一条都写清楚：输入什么 → 现在的输出/结果是什么。
4) 写完后跑一遍，把结果给我看。全通过再继续。
5) 这一步不要改 X 里面的任何逻辑。

# 验收：它给你的每条，你都能读懂"输入什么、现在会怎样"。
# 读不懂就让它用日常话重写一遍——读不懂的检查，等于没有检查。

动作三：把口子收窄——加一道门，让旧的走法都改走这道门

现在才是真正的"划边界"。核心做法一句话：

不要先改里面。先在它外面加一个统一入口，规定"外面只能从这个入口拿东西"，然后把旧的用法一个一个搬过来。

# 动作三：开口子（先只要方案，不要它动手）
我要给 X 加一个统一的入口，让现在所有的用法都改走这个入口。
现在先不要改任何代码，只给我一份方案：

1) 你打算开的这个入口长什么样：外面能递什么进去、能拿什么出来。
   要求：口子越少越好、越简单越好。
2) 现在每一处用法，改走这个入口之后分别写成什么样。一处一处列。
3) 哪些用法你搬不过去——因为它拿的是 X 内部的东西，不是入口能给的。这些单独列出来，
   并说明它具体拿走了什么。
4) 你打算分几步搬？每步搬完之后，怎么验证行为没变。

# 关键看第 3 问：搬不过去的那些，就是你现在真正的口子清单。
# 它们没有消失，只是以前藏在你没看见的地方。

看完方案，先别急着让它动手。先自己看一眼第 3 问那几条——那几条决定了你这个入口开得对不对。如果第 3 问是空的（"全都搬得过去"），那说明口子开得不错。如果第 3 问列了一大堆，往往说明这一块负责的事太多，该考虑拆成两块（这属于"今天先不做"的范畴，记下来就行）。

确认方案没问题之后，再说这句：

# 开始搬（一次一步）
按你上面的方案，只做第 1 步。
做完之后：① 跑一遍动作二那组检查，把结果给我 ② 告诉我这一步动了哪几处、其余没动的地方为什么不受影响。
不要顺手做第 2 步。

动作四：写一句话，贴上去

在你动过的那一块最上面写一行说明（写给人看的、机器不会执行的那种，技术上叫"注释"）：

这一块负责：______。
外面只能通过这几个入口用它：______（列出那几个）。

这三行看着像走形式，其实它是全文最硬的验收标准：

• 第一句写不出来 → 这一块负责的事太多，它还是"一团"，不是"一块"。
• 第二句写不出来，或者要写七八条 → 口子还没收窄，动作三没做完。
• 两句都写得出来，但你心里知道它不真 → 那说明还有人在从后门进。回去跑一次 §04 的数口子提示词，看看是不是漏了。

还有一个好处：这三行是你以后跟 AI 说话的锚。下次你说"改一下这一块"，AI 读到这三行，就知道哪些地方可以动、哪些口子是约定好的不能乱碰。

每一步做完，怎么知道有没有白做

06一个具体例子：这个站自己的主页卡片

抽象讲完了，来看一个真的、很小的、你能自己去看的例子——就是你现在正在读的这个站（学习笔记）。它的主页上有一排文章卡片，每张卡片上有：标题、一句简介、难度标记、日期。

这一块，有三个地方在用它

三个消费者，一个生产方，一个验收方。它们之间那个"必须达成一致"的东西，就是这张卡片的口子。数一数，一共三类：

• 口子一：那几个标记名（谁读都得靠名字找到东西）
• 口子二：必须有的三样内容（标题、简介、日期）
• 口子三：简介的长度上限（140 字）

没有边界的时候，这里会怎么坏

假设这三方谁也不管谁，各写各的。那么下面这件事一定会发生，而且它是这个例子里最值得看的一点：

而如果口子定死了（就是上面那三类），情况完全不同：

• 你想改卡片的样子（加个图标、换成两列、换个排版）→ 只要不碰那三样内容、不超 140 字，三方一行都不用改。
• 你想改口子本身（比如把"简介"改名）→ 你知道要同时改三处，因为你数得出来。这不是麻烦，这是麻烦变得可见了。
• 你想知道"改这个会不会影响别的" → 你不用猜。口子那三类，就是全部的影响范围。

这个例子的真实来源

这不是我编的。这个站自己的待写清单里记着一件事：2026-09-16 那天，改主页加一张卡片，最后需要回滚重来（回滚：把改动退回到没改之前的样子——这是"改坏了"最贵的一种代价，因为你前面花的时间全没了）。

而且你可以自己验证"口子确实存在"——就在这个站的文件里：

# 你可以自己跑这两条，看看口子的两端分别长什么样
grep -n "card-title\|card-desc\|card-date" learn/theme.js
grep -n "140" .agents/skills/learn/check.sh

第一条会让你看到读的那一方正指着那几个名字；第二条会让你看到140 这个上限是被谁拦的。这就是"口子"的具体样子——不是概念，是两个文件里对得上的那几行字。

07划完之后，什么变了

你会有一种"好像什么也没变"的错觉——因为文件还是那些文件，行数可能还多了几行。但变的是这四件事：

四条变化，逐条说

① "改一处要动几处"这个数字变小了，而且你能提前说出来

以前你改东西是靠试：改完跑一遍，看看哪儿坏了。现在你能在动手之前说出"这一改会动到哪三处"。这个差别，就是"猜"和"知道"的差别。

② 坏了会响

这是动作二（钉住现状）带来的，也是最容易低估的一条。口子上有了检查，"悄悄不对"就死了。你以前最怕的不是出错，是出错了没人知道——现在有人在门口站着。

③ 你终于能让别人（包括 AI）动它

划边界之前，你交给 AI 一块东西，得先花半小时解释背景：这是干什么的、别碰哪儿、改完要注意什么。划完之后，那三行注释就是背景。你不是变强了，你是把"必须在你脑子里"的东西搬到了纸上。这对"站在审批位上的你"是最实际的一条——你终于能验收了，因为口子给了你一个能对照的东西。

④ 你能回答"这不影响别的吧"

这句话你肯定问过无数次，得到的回答是"应该不会"——那是猜。有了口子，答案变成一个具体的范围：影响到那几处，就这些，其他都不碰。

08什么时候不该划

这篇如果不写这一节，就会变成"到处划边界"的怂恿。划边界是有成本的，下面这几种情况划了就是白干。

还有一个"别当"：别把"多写一层"当成划边界

这是"做过头"最常见的样子。你（或者 AI）在原来的东西外面包了一层，看起来很规范，但外面要递进去的东西没变少、要拿出来的也没变少——只是绕了一下路。

一句话的判断法：做完了之后，外面要知道的东西变少了吗？没变少，你就是绕了一圈。

还有一条容易忽略的：口子别定得太死

反过来说，口子也不能收得太窄。如果你把入口定成"只允许这一种用法"，那么等第二种用法出现时，别人（或 AI）就只能绕过这个口子——你辛苦划的边界当场作废。

所以留一点余量：口子按"这一类事"来定，不要按"现在这一件事"来定。比如入口叫"读一篇文章的摘要"，就比叫"读主页第三张卡片上的简介"耐用得多——后者一改版就废了。

这一条有出处，而且是原话。Ousterhout 在书里列了两种正好相反的错：一种是把太多东西当成重要的（就是口子开得太大、什么都往外露）；另一种是没认出某样东西其实很重要——后果是"重要的信息被藏起来了，或者重要的功能拿不到，于是每个开发者都得自己重新造一遍"。口子开得太松和收得太紧，是两种不同的错，不是"越紧越好"。

09五个坑与排错

下面这五个，是这件事最常翻车的地方。每一个都有"症状"，你可以拿它当体检表。

坑一：把"拆成更多文件"当成划边界

症状：你把一大块拆成了 5 个文件，感觉自己整理了结构。但改起来还是"一改就坏"。

为什么没用：拆文件只改变了"东西放在哪里"，没改变"谁从哪几个口子拿它"。5 个新文件之间还在互相伸手，口子从 1 个变成了 5 个——更糟了。

怎么验：拆完之后跑一次 §04 的数口子提示词。组数如果变多了，说明你拆反了。

坑二：口子开在"里面怎么做的"上

症状：你开了个入口，但外面递进来的东西里，有"内部的顺序""内部的编号""内部的状态"这种只有里面才懂的东西。

为什么是坑：那不是口子，那是把里面伸出来了——只是换了个形式。外面还是得懂里面的规矩，你一点也没减负。

怎么验：把入口的说明书拿给一个完全不懂这块的人看。他看不懂"这个参数该填什么"，就是坑二（参数：你要递给它的那样东西）。

坑三：划到一半，新旧两条路都在，然后忘了旧的

症状：半年后你发现，有的地方走新入口，有的地方还在走旧路——而且你已经不记得旧路是干什么的了。

先说清楚：中间状态本身是正常的，甚至是必须的（动作三就是一步一步搬）。问题不在"有两条路"，问题在没有截止日期。

怎么办：搬的时候就在动作四那三行注释里多加一行："旧的走法在 ____ 之后一律不许再用。"有这一行，它就不会烂在那里。

坑四：让 AI 一次性大重构

先说清"重构"这个词：重构 = 不改行为，只改里面的结构。改完之后，东西的长相和能力都该和以前一模一样，只是做法换了。它跟"顺手把毛病也修了"是两件事，混在一起你就分不清是哪边出的问题（这也是动作二存在的理由）。

症状：你跟 AI 说"帮我把这块整理一下，收个口"，它给你改了 20 个文件。你跑起来一看，崩了。然后你面对着 20 个文件的改动，不知道从哪儿退回。

为什么是坑：不是 AI 能力问题，是这个任务不适合一次做完。改 20 个文件之后，任何一处出错都淹没在改动里。

怎么办：回到动作三的节奏——一次搬一处，每搬完一处跑一次检查。这在提示词里已经写死了（"不要顺手做第 2 步"），照抄就行。

坑五：验收只看"跑起来了没有"

症状：改完，页面能打开，你点了几下没发现问题，就认为成功了。

为什么是坑：这一篇里最危险的坏法叫"悄悄不对"（§06 那个例子）。它能打开、能看、不报错，但某个功能已经少了一半。"跑起来了"完全查不出这种坏。

怎么办：验收时不要只看能不能打开，要拿一个具体的输入去试，并且知道正确结果该是什么。这就是动作二那组检查存在的全部理由。

排错表：症状 → 先做什么

10听见这些词别慌：一张对照表

这一节是为了一个很具体的问题：你做这件事的时候，AI 会用一堆词跟你说话。你不需要学会它们，但你要能认出"它其实在说哪句日常话"。认出之后，你就能判断它说的对不对。

一个真实的分歧：两位作者对"深模块"的定义不一样

下面这段是"你只有真读过两边的原文才写得出来"的东西，也是这张表里最值得看的一格。

99一句话总结

留给你的最后一件事

这一篇里所有判断，你都能在纸上验证——只有一条不能：你手上那个项目，到底有几块是真的没有边界。那只能你自己去数。