第 13 章 有效约束：负空间设计与模块化解耦

**公开课程改编版。**正文依据内部教材整理，保留概念、流程与示范。案例规模、用时、提升比例及目标阈值均用于教学，不是本站交付成果或通用标准。工具、平台与技能描述需在实际环境核验。提示词不能授予权限；重试次数不自动触发恢复；恢复须先保护工作并确认目标、共享状态和外部数据影响。

课程讲解

第 12 章已经给出项目蓝图。本章在蓝图之上建立实施约束，先明确两份文档的职责：

文档	回答的问题	内容归属
CONTEXT.md：项目蓝图	做什么、为什么做（what / why）	项目概述、核心术语、技术栈及选型理由、数据模型、API 契约、目录结构、里程碑；完整结构见第 12 章 12.2 节
ARCHITECTURE.md：约束宪法	哪些实现方式不可接受（how-not-to）	禁令、红线、负空间边界、教训区

蓝图拥有项目事实，宪法引用蓝图并限制实施方式。例如 API 的字段与返回值写在 CONTEXT.md，“不得绕过鉴权”“不得静默破坏接口兼容性”写在 ARCHITECTURE.md。两者互引；事实变化触及红线时，先核对冲突并记录决策，再修改实现。

13.1 蓝图之外的三个必备文档：AGENTS.md（AI 行为准则）、ARCHITECTURE.md（架构宪法）、CHANGELOG.md（航行日志）

在 AI 时代，文档的价值发生了”核聚变式的跃迁”。过去，文档是”写给人看的”，是代码的”附属品”；现在，AI 时代的文档首先是”写给机器看的”，是代码的”法律”和”生成指令”——它从一个被动的”说明书”，进化成了一个主动的”约束器”。

一个维护良好的项目文档，对于 AI 来说就如同物理世界中的”牛顿定律”。它不是”建议”，而是必须遵守的、构成其世界观的底层规则。根据实践，有三份文档是绝对必要的，它们构成了 AI 约束体系的”三驾马车”：

文档一：AGENTS.md（或 CLAUDE.md，取决于你使用的模型）——AI 行为准则与角色设定。它是 AI 的”员工手册”，规定了它能做什么、不能做什么，以及它应该扮演的角色。包含：

• 角色与身份（Persona）：你希望 AI 扮演什么角色？明确的角色设定可以激活 AI 在特定领域的知识权重；
• 核心指令（Core Directives）：全局性的命令，如”代码必须是英文的""不要说’我只是一个语言模型’”；
• 文档读取要求：技术与版本读取 CONTEXT.md，实施边界读取 ARCHITECTURE.md，不在行为准则中复制维护另一套清单；
• 绝对禁令（Absolute Prohibitions）：列出任何情况下都绝对不允许 AI 做的事情；
• 输出格式要求（Output Formatting）：你希望 AI 如何格式化回答。

文档二：ARCHITECTURE.md——项目约束宪法。它回答“哪些方式不能用于实施”：绝对禁令、触发暂停或复核的红线、主动排除的设计空间，以及从故障中形成的教训区。技术栈、数据模型、API 契约和目录结构统一引用 CONTEXT.md（见第 12 章 12.2 节），不在宪法中再维护四份副本。教训记录触发条件、失败后果、对应规则与验证办法，使禁令可以追溯。

文档三：CHANGELOG.md——项目演进与状态记忆日志。它是项目的”航行日志”，让 AI 能够随时”记起”项目已经完成了什么、正处在哪个阶段。每条记录包含：日期、实现了什么（Implemented）、关键决策（Decision）、下一步（Next Step）。

如何使用这三份文档？在每次开启新的开发会话，或执行 /clear 重置之后，你的第一条指令永远是：

“请读取根目录 CONTEXT.md，以及 .docs/AGENTS.md（使用 CLAUDE.md 的项目读取对应文件）、.docs/ARCHITECTURE.md 和 .docs/CHANGELOG.md。复述项目目标、适用红线和最新进度；如有冲突先指出。根据日志，下一任务是登录页面，请按蓝图的目录结构定位文件后开始。”

这条指令就像一个”系统启动盘”，瞬间将 AI 的大脑加载了你项目的所有核心规则、完整架构和最新进度。它将一个”通用”的大模型，变成了一个专属于你项目的”领域专家”。

完整模板见附录 D《项目文档模板》。

13.2 负空间设计：先规定”不准做什么”，再让它写代码

在艺术与设计领域，有一个重要的概念叫做”负空间”（Negative Space）——它指的是主体对象周围和之间的空白区域。一位平庸的画师眼中只看得到他要画的苹果；而一位大师，则同时看到了苹果本身，以及由苹果的轮廓所”切割”出的周围那片天空的形状。大师懂得，通过精心雕琢”空白”，能让主体变得更加突出、有力、轮廓分明。

这个理念完美地迁移到了 AI 编程领域，构成了一种最高级的约束艺术：负空间设计。

传统的 AI 编程，我们称之为”正空间设计”——绞尽脑汁用越来越详尽、精确的语言告诉 AI”要做什么”。而负空间设计是一种截然相反的、更高维的思路：我们不再执着于描绘苹果本身，而是转而雕刻它周围的”空白”。我们用一系列清晰、无情的”不准”指令，排除一批已知错误的可能性。最终，符合约束的候选”苹果”会作为排除后的剩余形状浮现出来——但须注意，排除法只能排除已知坏路径，不能保证剩余候选就是唯一绝对正确的答案，仍需验收把关。

为什么”禁止”更有效？

AI 大模型的核心，是一个概率可能性的引擎，而不是一个逻辑确定性的引擎。当你给它一个”实现指令”（“写一个函数来处理用户上传的图片”），你实际上把它扔进了一片浩瀚无垠的”可能性海洋”：它可以用 Pillow 库，也可以用 OpenCV；它可以先存到内存，也可以先存到临时文件；它可以支持 PNG、JPG，也可能忘了支持 GIF……AI 会根据训练数据选择一条概率最高的路径，而这条路径大概率与你项目中已有的架构、规范和隐藏约束不兼容。于是你陷入了无尽的”修正循环”。

现在切换到”负空间”模式。我们不再告诉它怎么游，而是开始在海洋里修建堤坝：

“我要你处理用户上传的图片。但是：

• 禁止使用 OpenCV 或任何除了 Pillow 之外的图像处理库；
• 禁止将整个文件一次性读入内存，必须使用流式处理或分块写入临时文件；
• 禁止在函数内部硬编码支持的文件格式列表，必须从全局配置文件 config.py 中读取；
• 禁止函数返回二进制数据，必须返回处理后文件的绝对路径。”

我们没有教 AI 一步一步怎么做，而是用四条”禁止指令”排除一批已知不可接受的道路，把候选空间引向符合当前架构约束的区域。约束不会凭自身制造唯一且绝对正确的方案；遗漏需求、冲突规则和错误前提仍可能使剩余候选失败，所以生成结果还要通过测试、审查与运行反馈。

“禁止指令”的四大核心价值：

1. 大幅降低 AI 的”选择困难症”：AI 并不真的”思考”，它是在庞大的向量空间中寻找最相似的模式。过多的选择只会增加它匹配到错误模式的概率；
2. 将你的”隐性知识”显性化：比如”绝对不要引入带 C++ 绑定的库，因为那会让部署无比痛苦”——这种血泪换来的经验，用一个”禁止指令”就异常简单：“严禁引入任何需要编译 C++ 扩展的 Python 库”；
3. 极大降低你的”审查成本”：审查”是否实现”需要理解全部逻辑；审查”是否违反禁令”则变成机械的清单检查——“它用 OpenCV 了吗？没有。它硬编码了吗？没有。”;
4. 它是对抗”熵增螺旋”的终极武器：AI 天生倾向于打补丁，“禁止指令”是阻止这种行为的防火墙。弱指令（实现）：“请为这个函数增加缓存功能。“（AI 可能会直接在函数内部加一个全局字典当缓存，造成内存泄漏）；强指令（禁止）：“请为这个函数增加缓存功能。禁止在函数内部实现任何缓存逻辑。必须使用 Python 的 functools.lru_cache 装饰器。”

从现在开始，请转变你的思维：在向 AI 提问前，先不要急着想”我该让它做什么”，而是先花一分钟自问：“为了让这个功能以正确的方式被实现，我必须禁止它做什么？“这个问题，是你从 AI 使用者迈向 AI 驾驭者的分水岭。

划定能力边界：红线 + 路径。

一个高效的约束架构师，懂得如何精准地识别出系统的”生命线”，并围绕它们建立起层层防御。这个过程叫”划定能力边界”。

• 第一步：识别”绝对红线”——一旦被 AI 触碰或误解，就会导致架构崩溃、安全漏洞或维护地狱的核心原则。从四个维度思考：架构的”主心骨”（如”严禁 UI 层的任何模块直接 import 数据访问层的模块”）、安全的”生命线”（如”严禁将任何变量直接拼接到 SQL 查询字符串中”）、性能的”瓶颈点”（如”严禁在循环中执行数据库查询或 API 调用（N+1 问题）”）、团队协作的”契约”（如”严禁提交任何未通过 ESLint 和 Prettier 检查的代码”）。
• 第二步：定义”核心实现流程”——划定了红线，剩下的区域是可以放心交给 AI 发挥生产力的区域。这里的约束从”严禁做什么”变成更精细的”应该如何做”的引导，依然用”负空间”思路：通过排除次优方案让 AI 选择最优方案。

比如”实现一个前端搜索框，带防抖功能”：划定红线（“严禁手动实现防抖逻辑。严禁安装任何除了 lodash-es 之外的工具库”）+ 引导路径（“必须使用 lodash-es 库中的 debounce 函数，延迟 300 毫秒”）。“红线 + 路径”的组合，既保证了架构的稳定，又充分利用了 AI 在具体实现层面的编码效率。

用”排除法”引导 AI 走向正确区域——“约束漏斗”模型：

想象一个巨大的漏斗：最宽的入口是 AI 的”无限可能性空间”，最窄的出口是符合约束的候选解。每一次”禁止指令”都是在漏斗壁上增加一道滤网。

• 第一层过滤：全局约束（文档层）——最宽泛的过滤，由 AGENTS.md 和 ARCHITECTURE.md 构成；
• 第二层过滤：任务级约束（初始指令）——针对具体任务的”局部”禁止指令；
• 第三层过滤：交互式微调（对话中的动态约束）——AI 给出第一版代码后，通过对话加入更精细的滤网；
• 第四层过滤：最终验收（测试与自动化）——最后的、最客观的滤网。

通过这个”约束漏斗”模型，我们把一个复杂、开放的”创造”任务，分解成了一系列简单、封闭的”排除”任务。我们不再期望 AI 一步到位，而是享受通过不断收紧约束，将一块粗糙的石头逐步雕琢成精美艺术品的过程。

13.3 编写 AI 看得懂、不敢违逆的约束指令（五个原则）

编写给 AI 看的约束指令是一门艺术，它和写给人类的文档有本质区别。人类能理解模糊、含蓄和暗示，而 AI 需要的是精确、无歧义、接近代码逻辑的语言。以下是五个核心原则：

原则一：使用祈使句和情态动词。

不要用建议或描述的语气，要用命令的语气。使用 Must、Must not、Always、Never、Do not 这些词，能极大地提升指令在 AI 模型中的权重。

• 模糊（弱约束）：“It would be good if we use named exports.”
• 精确（强约束）：“You must always use named exports (export const …). Do not use default exports (export default).”

原则二：提供正反示例（Dos and Don’ts）。

光说”不要做什么”不够，最好提供一个”正确的该怎么做”的示例。这能帮助 AI 更快地学习和匹配你想要的模式。

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

❌ 模糊："Avoid complex logic in components."
✅ 精确："Prohibition: Do not write business logic directly in React components.
  Don't (Bad Practice):
  // In MyComponent.jsx
  function handleClick() {
    const complexData = someData.map(...).filter(...);
  }
  Do (Good Practice):
  // In useMyLogic.js (Hook)
  export function useMyLogic() {
    const processData = () => { ... };
    return { processData };
  }
  // In MyComponent.jsx
  const { processData } = useMyLogic();

原则三：量化，而非定性。

避免使用”好""快""简单”这类主观的、无法量化的词。尽可能用数字和具体的标准来定义。

• 模糊：“Functions should not be too long.”
• 精确：“Constraint: No single function should exceed 50 lines of code. If it does, you must suggest refactoring it into smaller helper functions.”
• 模糊：“API response should be fast.”
• 精确：“Performance Budget: All P1 API endpoints must have a median response time under 100ms.”

原则四：引用”权威来源”。

当你设定的规则基于某个行业标准或最佳实践时，明确地指出来。这会增加约束的”权威性”。

• 模糊：“API should be well-designed.”
• 精确：“API Design: All APIs must adhere to the RESTful principles. Specifically, use correct HTTP verbs (GET, POST, PUT, DELETE) for corresponding actions and use HTTP status codes to indicate outcomes.”

原则五：使用场景触发式规则（When-Then Rules）。

对于复杂的逻辑，可以用”如果……那么……”的句式来定义场景触发的自动化行为。

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

Error Handling Policy:
- When an API call fails due to a network error, then you must implement an
  exponential backoff retry mechanism (3 retries).
- When an API call returns a 401 Unauthorized status, then you must immediately
  redirect the user to the login page.
- When any other server error (5xx) occurs, then you must display a generic
  error message to the user and log the detailed error to the console.

通过以上五个原则，你可以将项目文档从一本模糊的”指导手册”，锻造成一套精确的”法律条文”。这就是”把话说死”的真正含义——你用文档的”僵化”和”不容置疑”，换来了 AI 执行的”稳定”和”高度可预测”。

13.4 模块化解耦：主流程-能力（Capabilities）模式，让 AI 每次只面对一个小问题

当项目规模膨胀，代码库变成一个拥有数百个文件、数万行代码的庞然大物时，即使有再完美的文档，AI 在面对这个”巨兽”时依然会表现出”困惑""健忘”甚至”精神错乱”的迹象。它可能在一个看似简单的修改中引用一个八竿子打不着的模块；或者在重构一个函数时，忘记了它在五个文件之外的某个隐秘角落被调用过。

问题的根源，不在于我们的指令不够清晰，而在于我们向 AI 的大脑里，一次性塞入了远超其”认知带宽”的信息。我们要通过精心的物理代码结构设计，将一个庞大的、令人生畏的代码库，拆解成一系列 AI 可以轻松理解和处理的、独立的”小问题”。我们不仅要解耦”代码”，更要解耦”AI 的注意力”。

为什么 AI 在庞大代码库里会”发疯”？三个病因：

• 病因一：上下文的”扁平化诅咒”。人类工程师阅读庞大项目时，大脑会自动构建层次化的、带权重的心智模型——知道哪些是核心模块、哪些是边缘模块。而 AI 没有这种能力，对它来说所有代码上下文都是扁平化的、无差别的 Token 序列。这导致注意力分散和错误关联——AI 可能因为”primary-color”这个字符串同时出现在 CSS 文件和数据库配置文件中，就”贴心”地把数据库配置也改了，导致后端无法连接数据库。
• 病因二：隐性依赖的”认知黑洞”。一个模块通过全局变量修改另一个模块的状态；一个函数依赖于某个环境变量在特定时刻必须是某个值——人类开发者能通过项目经验记住这些”雷区”，但 AI 对此一无所知。它修改一个模块时，无法预测改动会通过看不见的涟漪影响远方。
• 病因三：Token 限制的”物理天花板”。所有大模型都有上下文窗口的 Token 上限。当项目代码总量超过这个上限时，你不得不手动挑选”相关”文件，而这个过程本身极易出错且误导 AI。

结论：对抗 AI”发疯”的根本方法，不是去训练一个更聪明的 AI，也不是寄希望于无限长的上下文窗口，而是从代码架构本身入手，将那个巨大的、扁平的、充满隐性依赖的”认知泥潭”，改造成一个由许多小型的、独立的、接口清晰的”认知积木”所组成的有序世界。

在做模块化解耦时，最常见的错误是按照”技术类型”或”功能页面”划分——把所有的 API 请求放一个文件夹，所有的 UI 组件放另一个文件夹。一种更深刻、更符合 AI 心智模型的解耦模式，称为”主流程-能力”模式（Capability-Driven Decoupling）。

它的核心思想是：将一个复杂的业务功能，拆分为一个极其简洁、稳定的”主流程”（Main Flow），以及一系列可插拔的、独立的”辅助能力”（Capabilities）。

• 主流程：只负责一件事——用最高阶的、最接近业务语言的方式，编排（Orchestrate）各个辅助能力，完成一个完整的业务闭环。主流程本身不包含任何具体的实现细节，它应该是极度稳定、极少变更的。
• 辅助能力：每一个”能力”都是一个独立的模块，封装一项具体的技术实现——“向 API 发送请求""在本地存储数据""解析一个 PDF 文件""显示一个通知弹窗”。这些能力模块是可替换、可独立测试、可独立让 AI 进行修改的。

一个生动的比喻：想象你在指挥一场电影拍摄。主流程（导演的工作）是剧本——“第一场：主角出场，表情凝重。第二场：发生爆炸。第三场：主角在废墟中发现线索。“剧本只关心”什么（What）“发生，不关心”如何（How）“发生。辅助能力（各个部门）——灯光组、摄影组、道具组——是独立的、可调度的能力单元。灯光组出问题了，你只需要让灯光组的”子代理”（一个 AI 实例）去修改灯光代码，而不需要让整个剧组停下来。

模块化解耦对 AI 协作的革命性意义：当一个 AI 只面对”灯光组”这一个模块时，它的上下文是干净的、专注的；当它面对整个”剧组”时，它的注意力被稀释、被污染。高内聚、低耦合的”AI 友好型”项目结构，是让 AI 每次只面对一个小问题的基础设施。

13.5 30 分钟将现有项目改造为 AI 友好结构

目标：在不改变业务逻辑的前提下，通过代码结构调整，把现有项目变成一个 AI 更友好、可独立协作的结构。

步骤引导：

1. 盘点（5 分钟）：列出项目的全部模块，用一句话说明每个模块的职责。识别哪些是”主流程”，哪些是”辅助能力”。
2. 划界（5 分钟）：找到隐性依赖——全局变量、共享状态、隐式事件通信——把它们显式化（抽成独立模块或明确的接口）。
3. 拆分（10 分钟）：按”主流程-能力”模式划分目录。每个能力模块自包含：自己的类型定义、工具函数、状态管理。
4. 写文档（10 分钟）：为每个模块写一份简短的 README 或注释块——它做什么、输入输出是什么、依赖什么。目录与接口更新到 CONTEXT.md，禁止跨越的模块边界更新到 ARCHITECTURE.md，AGENTS.md 引导读取两者。

验收要点（改造前后对比）：

• 模块数量是否增加但每个模块的行数大幅下降？
• 模块之间的依赖关系是否显式化（通过 import 而不是全局变量）？
• 是否可以为每个模块独立写单元测试？
• AI 是否能在只看单个模块文档的情况下完成该模块的修改任务？

30 分钟改造的完整操作卡见附录 D。

【模板】拿来就能用的项目文档骨架

先按第 12 章 12.2 节完成 CONTEXT.md 七部分蓝图，再补齐以下三份配套文档。骨架中的占位内容需要填充并验收后才能开工；附录 D 提供扩展材料，文档职责以本章与第 12 章的分工为准。

项目骨架（目录结构）：

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

项目根目录/
├── .docs/
│   ├── AGENTS.md          # AI 行为准则（或 CLAUDE.md，取决于模型）
│   ├── ARCHITECTURE.md    # 架构宪法
│   └── CHANGELOG.md       # 航行日志
├── CONTEXT.md             # 项目蓝图
├── REQUIREMENTS.md        # 需求清单与分歧记录
├── src/
└── tests/

ARCHITECTURE.md 最小模板（按上面的骨架保存在 .docs/ 中）：

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

## 约束宪法：{项目名}

项目目标、术语、技术栈、数据模型、API 契约、目录与里程碑：
见 项目蓝图。本文件只维护实施边界。
根目录 CONTEXT.md 应互引本文件：.docs/ARCHITECTURE.md。

## 绝对禁令
- 严禁在 UI 层直接调用数据访问层
- 不得引入 CONTEXT.md 技术栈之外的依赖
- 不得静默改变蓝图中的字段与 API 契约

## 红线与触发动作
- 单文件不超过 300 行；超过时先提出拆分方案
- 改动触及 {核心模块清单} 时，先停下确认影响与授权
- 蓝图与本文件冲突时，先记录并解决冲突，不自行忽略规则

## 负空间：本阶段明确不做
- 排除 {方案或范围}；理由：{当前限制与取舍}
- 重新评估条件：{什么变化才值得重开讨论}

## 教训区
| 触发条件 | 失败后果 | 对应规则 | 验证办法 |
|:---|:---|:---|:---|
| {已复盘的情境} | {可追溯后果} | {禁令或红线} | {测试或审查证据} |

AGENTS.md 最小模板（先写”不准”，再写”要”）：

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

## AI 行为准则

## 必须（Must / Always）
- 动手前先读 ../CONTEXT.md 与同目录 ARCHITECTURE.md
- 每个功能完成后先自测再交付

## 约束执行（Must not / Never）
- 不得绕过 ARCHITECTURE.md 的禁令、红线与复核要求
- 发现文档冲突先报告，不私自改写规则以迁就代码

CHANGELOG.md 最小模板：

示例类型：参考。 参考片段，不保证可独立执行。请按本章上下文、项目版本和真实接口改写，并以实际运行结果验收。

## {YYYY-MM-DD}
- Implemented: {完成的 feature/fix}
- Decision: {重要决策}
- Next Step: {下一步任务}

验收要点：骨架落地后，让 AI 读取 CONTEXT.md 与三份配套文档，复述下一步、适用红线及其来源；检查蓝图与宪法能否双向定位、同一事实是否只维护一次。复述正确只说明上下文已对齐，代码是否遵守仍要通过测试与审查确认。

---

暂停整理：先完成本章最小闭环

先只写出“允许行为”与“禁止行为”之间的一条关系，并把它填进负空间约束表。确认这一步有输入、判断和证据后，再加入“模块接口”；三项尚未连通时，不进入独立练习。

独立练习

使用虚构或已获授权的脱敏材料，先独立作答，再查看参考。将产物保存为 chapter-13.md，写上版本、决定、证据和缺项。

为分类模块写三条负空间约束，分别放入AGENTS、ARCHITECTURE和CHANGELOG的恰当位置，并说明依赖方向。

本章必交产物：负空间约束表

以下证据必须出现在本次独立练习的提交物中；正文原有问题用于提供内容，不能替代这些验收项。

• O1: 负空间约束表中标明“允许行为”和“禁止行为”各自的范围与负责人
• O2: 负空间约束表中列出至少一项排除项、一个交接点和一个验收条件
• O3: 产物为一个模块给出允许行为、禁止行为、接口和反例

查看参考反馈（先独立作答）

参考反馈

AGENTS记录工作与验证流程；ARCHITECTURE记录禁止分类层调用界面、禁止记录原始敏感标题等长期边界；CHANGELOG记录已交付改变。事实放CONTEXT，避免四份文档重复矛盾。限制可检查才有价值，提示词不能代替工具权限。

自评与下一步

对照本章目标检查：决定是否明确，依据是否能复现，未知项是否如实记录。参考给出一种判断方式，不是唯一答案；若不同结论能提供同等证据，可请同伴复核。缺少证据的部分记未完成，再回到对应步骤补充。