隐喻式需求文档：让AI编程告别幻觉与过度设计

1. 一场"需求文档起义"的缘起：AI给的东西，总是"差点意思"

过去大半年，我一直在跟AI编程工具打交道，尤其是Cursor这类能直接读仓库、读需求文档、跨文件改代码的Agent型工具。坦率说，生产力提升是实打实的，但随之而来一个非常折磨人的现象：AI产出的代码，单看每一段都像模像样，合在一起就"差点意思"。

举个例子。我让AI写一个"订单超时未支付自动关闭"的功能，需求文档里写了"超时后关闭订单、释放库存、通知用户"。它非常勤快地给我建了三张表、两个状态机、一个定时任务、一个消息队列，还贴心地加了个"订单关闭后允许用户申诉"的流程。问题是：我们当时的业务根本不需要申诉；库存也不是下单时锁定的，而是支付时才锁；"通知用户"也只需要APP站内信，不需要短信网关。

为什么AI会跑偏这么多？因为需求文档给了它太多"合理想象"的空间。它读了"关闭订单"，就自动补全了"关闭订单"在互联网场景里最常见的全套周边设计。这是大模型的底层本能：它不是在执行需求，它是在续写一篇关于需求的文章。 在哪句话旁边续什么内容，取决于它见过多少种类似的语料搭配，而不是你的业务到底怎么想的。

我是在连续踩了七八次这样的坑之后，才意识到一个关键问题：我们写需求文档的方式，还停留在"给人类同事看"的思维里。人类同事看了需求，不懂会问，会基于上下文猜你的真实意图，猜错了还能被纠正。但AI不会主动问，它只会极其自信地给出概率最高的那个"续写下文"。所以当你给它一份充满省略、依赖默认假设、靠潜台词沟通的需求文档时，它不是在帮你实现需求，它是在帮你"虚构"需求。

于是我开始尝试另一种写法：在需求文档里植入隐喻，用隐喻给AI设定一个无法逃逸的认知框架，让它从"自由发挥模式"切换到"谨慎对齐模式"。 效果出乎意料地好。我把它叫作"需求文档起义"——因为这样做本质上是把产品定义权、架构解释权从AI手里夺回来，重新攥在写文档的人手里。

这篇文章就是把这套方法论完整拆开。它适合谁看？如果你是产品经理，文档写出来喂给AI但总觉得不是自己想要的东西；如果你是程序员，用Cursor这类工具但经常要花大量时间review和改bug；如果你在尝试AI Agent开发，需要让模型严格按照业务规则执行而不幻觉。那这篇文章应该能省下你不少头发。

需要先说明的是，全文谈的"让AI恐惧"，不是说AI真的有情绪，而是通过文档结构设计，让模型在推理时产生足够的"不确定性警觉"，从而提高它对齐需求的概率。这背后是有原理可循的，下一节就讲这个。

2. AI为什么会"怕"一份写得好的需求文档：从AI幻觉的成因说起

想理解"隐喻式需求文档"为什么有效，得先理解AI为什么会产生幻觉、跑偏、自作主张。这部分我不想讲得太学术，但底层机制还是得说清楚，不然你只会模仿形式，遇到新场景照样抓瞎。

2.1 大模型本质上是一个"合理续写器"，不是一个"需求执行器"

不管是GPT系列还是国产大模型，它们的训练目标核心都是"给定前文，预测下一个最可能的Token"。这意味着模型在生成回答时，天然倾向于输出在训练语料中出现频率最高、语义最通顺、最符合人类写作习惯的后续内容。

问题就在这：一份需求文档写"关闭订单"，模型见过的类似文本里，十有八九后面跟着的都是"订单状态流转、库存回滚、退款流程、用户通知"这些内容。所以它"合理"地续写了一套完整方案。它不知道你所在的业务域里，"关闭订单"可能只是更新一个字段、清掉一张临时表、发一条消息就完事了。

这就是AI幻觉在需求场景下的本质：它不是编造错误信息，它是在用"人类最常见做法"填充你留下的语义空白。 你的需求文档留下的空白越多，它填充得越起劲。它写得越快，你越要警惕——一个需求文档扔进去几秒钟就哗哗生成一大片代码，大概率是在复用模式，而不是在理解业务。

我做了个小测试，把同样的需求用两种方式写出来，交给同一个模型：

核心差异就是一句话：我是否给了模型一个足够具体的"世界模型"。 写"门店预约工具"，模型对"订单"的理解就从"电商订单"切换到了"预约意向"，它续写的方向就完全不同了。

2.2 为什么"想象空间"对AI来说是致命的

人类读需求文档，遇到模糊的地方会脑补，但通常会在脑补的同时标注"这一点需要确认"。因为人类知道自己在猜，会心虚。但AI不会心虚，它对自己生成的内容拥有极高的置信度——因为它生成的每一个词，都是当下概率最高的选择，它根本没有"这份猜测可能是错的"这种内部反馈。

所以，文档里的模糊地带对AI来说不是"待确认"，而是"自由发挥区"。你写"支持多端登录"，它会默认你需要Web、iOS、Android三端；你写"数据要做权限控制"，它会默认你需要RBAC模型，建role表、permission表、user_role中间表。这些默认，都来自它的训练语料，而不是你的业务。

想控制这种默认行为，最直接的手段就是：把AI会"脑补"的假设，一条条显式列出来，提前堵死。 但是干巴巴地列规则有个问题——规则太多，模型容易"顾头不顾尾"；规则之间还有可能互相打架。我试过写十几条"注意：本系统不需要XX功能"，结果模型顾了前三条，后面照样犯。

直到我开始用"隐喻"来压缩这些约束，事情才出现转机。

2.3 隐喻的作用：给AI一个"必须去模仿"的参照系

这里说的隐喻，不是修辞意义上的"爱情像一场马拉松"，而是用一句话给你整个系统设定一个具体的、有明确行为特征的类比对象，让模型在理解需求时始终围绕这个类比展开推理。

比如，你与其写十条规则说"不要走电商那种复杂的订单状态流转"，不如直接写一句：

本系统的订单模型，请参考"餐厅等位小票"来理解：小票打印出来，用户过号视为放弃，不需要支付，不需要退款，不需要物流。

这句话蕴含的信息密度极高。模型看到"餐厅等位小票"这个隐喻，会自动关联一个小而轻的、无支付无物流无售后的业务模型。你再让它写订单超时逻辑，它绝不会给你搞出库存和退款那一套来。

为什么隐喻比规则更有用？因为模型的训练语料里，"餐厅等位小票"这个概念附带了一整套场景特征，调用这个隐喻，等于一次性把"轻量、无支付、无库存、无物流"这些特征全部注入模型，而不是让它逐条读规则再自行组合。

这不是玄学，这是利用了大模型的知识压缩和联想能力。 你给它一个精准的参照系，它就能把你没说出口的几十条隐含规则通过联想补齐。

所以，下一篇需求文档不妨试一下：在最顶部写清楚"本系统像什么"。

3. 方法论：把"隐喻"当作约束建模工具，而不是修辞游戏

"隐喻"听起来很文学，但真要落地，必须把它当成一种工程手段来用。我用了大概三个月，踩了不少坑，最后沉淀出一套分类和写法，下面完整分享。

3.1 三种隐喻：系统隐喻、行为隐喻、惩罚隐喻

我把在需求文档中真正起作用的隐喻分成三类，不同类型的隐喻负责解决不同层面问题：

第一类：系统隐喻。 一句话定义整个系统的气质和复杂度等级。这是最重要的一个，放在文档开头，决定AI对全部需求的理解基调。比如：

• "本系统本质是一个'电子表格'，所有业务实体都像Excel里的一行，字段简单，不需要复杂关联。"
• "本系统本质是一个'银行柜台叫号屏'，只负责展示和排序，不处理任何交易。"
• "本系统本质是一个'自动售货机'，每一个操作都有且只有一个明确的结果，没有中间状态。"

这些隐喻的共同特点是：它们自带复杂度上限。你说"像Excel"，模型就不会去建几十张表；你说"像售货机"，模型就不会设计一堆异步状态流转。系统隐喻是第一道防火墙，也是优先级最高的。

第二类：行为隐喻。 针对某个具体模块，给模型的"行为边界"做约束。比如：

• "推荐功能要像图书管理员，用户没说要什么书，但管理员根据借阅记录默默筛选几本放在桌上，它不推销，不做弹窗，不解释理由。"
• "权限系统要像小区门禁卡，刷卡进去就行，不需要记录谁几点进了哪栋楼。"

行为隐喻的好处是，它给模型提供的不只是一个结果，还有一套"交互姿态"。你在后面补的那句话（不推销、不做弹窗、不解释理由），正是AI最容易过度设计的地方。

第三类：惩罚隐喻。 这名字是我自己起的，它描述的是"当系统出错时，应该以什么样的方式出错"。比如：

• "订单关闭逻辑要像闹钟响铃，到点就响，不需要确认用户是否听到、不需要提供延迟唤醒。"
• "数据校验要像机场安检，安检不合格就是不让登机，没有商量、没有申诉。"

这种隐喻能有效防止AI在错误处理分支上"过度同情用户"，写出各种兜底恢复的复杂度。

3.2 如何写出有信息量的隐喻：错误示范与有效示范对比

隐喻不是写得越形象越好，关键看信息密度。很多新手第一次尝试，会写出"像淘宝一样"或"像微信那样"这种话。这是最典型的反例。因为"淘宝"这个词在模型语料里关联了海量特征，你根本无法控制它到底抽取哪一部分。

错误示范：

本系统的用户积分体系要像支付宝会员一样。

"支付宝会员"关联的关键词可能是：等级、成长值、权益、任务体系、升级门槛、保级规则、勋章、专属客服、生日礼包、抽奖、积分商城……模型从中随便挑三样实现，你可能就会哭出来。

有效示范：

本系统的用户积分是一个"图书馆借阅卡上的盖章"。一次借阅一个章，满十个章换一张图书卡片。没有任务、没有等级、没有权益、没有签到、没有积分商城。

注意这里的写法逻辑：先用一个具象隐喻"图书馆盖章"，再用几个短句把隐喻中可能被放大的特征全部封死。模型读到"图书馆盖章"，联想到的是朴素的线下记录行为，后面的排除句又进一步压缩了它的"发挥空间"。

我反复测试下来，发现有效隐喻的规律有三条：

1. 必须是来自现实生活的常见物体或场景，而不是互联网产品名，因为生活场景的复杂度边界相对稳定，而互联网产品在语料中被讨论了太多变体。
2. 隐喻后面跟几句负向约束，用"没有""不需要""不提供"这类词把常见扩展点封死。
3. 隐喻描述的对象必须足够具体，宁可说"公园长椅上绑的气球"这种细节丰富的东西，也不要说什么"在线服务"这种抽象概念，抽象概念对模型没有任何约束力。

3.3 隐喻必须配套"反模式清单"，不然AI会在隐喻里自由发挥

隐喻是方向性的，它把模型带进了正确的"认知区域"，但模型在这个区域里还是可能走偏。所以我通常会在隐喻之后，接一个"反模式清单"，也就是明确告诉模型哪些类行为是绝对禁止的。

举个例子：

本系统的预约模块采用"理发店排队簿"作为核心模型。在此基础上，以下反模式必须禁止：

• 禁止引入"预约状态机"，不要设计"待确认/已确认/已取消/已完成"的状态流转，一个字段"是否已服务"就够。
• 禁止引入"提醒机制"，不要做短信提醒、Push通知、邮件提醒。
• 禁止引入"爽约惩罚"，用户不来就不来，不需要扣信用分，不需要拉黑。
• 禁止引入"排队等待列表"，如果当前时间段已满，直接告知无空位即可。

为什么要这样写？因为隐喻让模型知道了"大概像什么"，但"理发店排队簿"在模型理解里仍然可以有两三种实现方式。反模式清单的价值在于把模型认知区域内的所有主要歧义出口全部钉死。你只需要写四到五条"禁止"，后面几十个模型可能出现的脑补分支就都堵住了。

我见过有人写需求文档时习惯用"包括但不限于"来列举功能，这个思路如果反过来用，就特别适合AI场景：反模式清单用"禁止但不限于"的逻辑，模型才不敢越界。

3.4 和Curson这类工具搭配时的具体操作细节

如果你用的是Cursor这类可以读文档的AI编程工具，建议把隐喻式需求文档作为"项目级约束文件"放在仓库里，而不是只丢进一次对话。我目前的做法是：

• 根目录放一个PROJECT_CONTEXT.md，开头就是整个系统的系统隐喻，接下来是核心术语表、反模式清单。
• 每次让AI改代码前，不直接说需求，而是先说"先读一下PROJECT_CONTEXT.md，本次改动需要遵循其中的系统隐喻和反模式约束"。
• 在给AI的指令里，涉及具体模块时，再引用对应的行为隐喻。

这样做的效果是：哪怕你今天开新的对话、明天换人接手，AI对系统的基本认知都不会漂移。尤其在做AI Agent开发时，如果不给模型一个稳定的"世界模型"文件，它的行为会在不同会话之间剧烈抖动。隐喻式需求文档天然适合当Agent的"长期记忆锚点"。

4. 一套可以直接抄作业的"抗AI幻觉需求文档"模板

前两节讲的都是思路，接下来给一份可以直接拿去用的完整模板。这个模板我迭代了三个多月，目前在我们团队内部使用，新人拿它写出来的文档喂给AI，产出质量明显比原来高一个量级。

整个模板分六个模块，顺序写在一个文档里。如果项目不大，一页到两页就够，千万别写得像传统PRD那样动辄几十页，AI模型对长文档的注意力会衰减，写得越长的部分它反而越容易忽略。

4.1 模块一：系统隐喻（放在文档最顶部）

这是整个文档的定海神针。要求两句话以内说清楚系统像什么，并且补一句"它不像什么"。

示例（线上预约小程序）：

本系统采用"理发店排队簿"作为系统隐喻。它不像电商平台，没有订单、没有支付、没有物流、没有售后。用户选择时间、填写手机号、完成预约，商家看到名单即可。

就这么简单。这段信息量巨大，后面所有需求描述都应该在这个框架下理解。

4.2 模块二：核心术语表（把关键名词一次性钉死）

专有名词的含义如果不统一，AI会在不同字段和概念之间乱建立关联。这个模块不需要多，把项目里最常用的五到八个核心术语定义清楚就行。

示例：

• 预约：用户选择具体时间段并留下手机号的行为，一次预约对应一名用户。
• 可预约时段：商家在后台设置的开放服务时间，不区分"技师"维度，同一时间段有多个同时可约。
• 空位：该时段总人数减去已预约人数，不等于剩余"库存"，没有超卖概念。

有没有注意到，这里每一个术语定义都在封堵概念边界。别小看这一步，AI幻觉的另一个主要来源就是概念串台——它把"预约次数"理解成"库存"了，整个数据结构就歪了。

4.3 模块三：反模式清单（至少写五条）

把你在以往AI协作中最常碰到的"AI式过度设计"直接列出来。这部分的写法要领是：越具体越好，描述的是行为，而不是原则。

示例：

• 禁止引入"预约状态机"，不要设计"待确认/进行中/已完成/已取消"字段，用"是否已服务"一个布尔值。
• 禁止引入"提醒"相关功能，不要做短信、Push、公众号模版消息。
• 禁止引入"爽约惩罚"机制，不扣分、不拉黑、不设限制。
• 禁止为"同一用户多次预约"建立复杂关系，每次预约都是独立记录即可。
• 禁止设计"商家审核预约"流程，预约即成功，商家不需要操作。

有人会觉得"我写这么细，是不是把AI的创造力限制死了？"——正是在这个点上，我给的建议是：在AI编程场景下，限制创造力的价值远远大于激发创造力。 AI的"创造力"在代码实现层面够用了，在业务设计层面是灾难。

4.4 模块四：隐式假设显式化（把AI会脑补的假设全部写出来）

这一条是从长期调试中总结出来的，专门针对那种"你没写、AI就默认有、然后导致整个设计跑偏"的场景。我的做法是，把AI最容易默认的几个隐含假设列出来，逐个声明"本系统如何处理"。

示例：

• 本系统没有登录注册模块。用户不需要账号体系，手机号就是唯一标识。
• 本系统不区分用户角色，除商家外只有一个用户类型。
• 本系统不涉及支付、退款、发票等资金类功能。

你会发现，这一条在传统需求文档里通常根本不会写，因为"没有登录"这种话对研发同事说一遍对方就记住了，但对AI不行，它在生成代码时默认"系统就应该有用户表、有auth中间件"，因为它见过的代码库百分之九十都这样。你不写，它就开始加。

4.5 模块五：经验法则（给AI一个"自行决策"的判据）

就算你把约束写到极致，AI在处理新需求时还是会遇到文档没覆盖的情况。这时候如果没有判断依据，它会直接按照自己的默认偏好来。所以我会写一条"经验法则"作为所有约束之外的最后仲裁标准。

示例：

当遇到本文档未明确覆盖的设计决策时，请遵循一条判据：所有功能都应该像理发店预约一样，尽可能被一个普通店员用纸笔就能完成。如果某个设计无法在Excel表里实现，说明它过度复杂了，请重新考虑。

这一条比任何"请保持代码简洁"之类的空话都有效。因为模型会真的用"能否在Excel里实现"去衡量它设计方案的必要性——Excel没有的消息队列、定时任务、复杂状态机，在这里全都排除了。

4.6 模块六：验收测试的"恐惧条款"

最后，在文档末尾加上一小段验收测试描述。不需要写完整测试用例，只需要写一两条"核心场景必须满足的行为"。这是AI在实现时不会因为信息不足而偷偷砍掉的部分。

示例：

验收场景：用户选好周六下午3点，输入手机号提交后，可在"我的预约"里看到该预约。商家端在后台能看到当天所有预约列表。当周六下午3点过去后，系统不自动做任何事。预约不需要被确认，不需要被取消。

一个只有三句话的验收场景，却把所有关键行为都钉死了。AI写完代码后，可以用这段话来自检。我甚至会让AI先看这个验收场景，再回头写代码，这样它的实现路径会比"先写功能再对照需求"更贴合。

整个模板整合起来，一页到两页，信息密度极高。喂给AI后，它的输出质量提升非常明显。

5. 实测复盘：给同一个需求，传统写法和隐喻写法的产出差异

方法论讲再多，不如拿实测数据说话。下面分享两组我做过的对照实验。都使用相同的模型和工具，唯一的变量是需求文档的写法。

5.1 实测一："预约时段冲突处理"的两种写法规格对比

第一组测试，我给AI提一个需求：用户在小程序里选择预约时间段，需要处理同一个时间段多人预约的情况。

传统写法：

实现预约时段的选择功能，需要处理时段冲突。一个时段可以被多人选择，达到容量上限后不能再选，前端要提示用户并让用户选择其他时段。

这个写法的表述已经比较清楚了对吧？结果AI生成的内容里，居然出现了"为时段设计可配置容量、为冲突设计排队机制、为已满时段设计自动分配到相邻时段"这些功能。为什么会这样？因为"冲突"这个词在AI语料里太容易关联"并发、锁、排队、抢占"这些概念了。

隐喻写法：

可预约时段像一个理发店里的"时间段格子"，写在黑板上的格子满了就是满了，不需要排队机制，不需要自动分配，用户看到"满"字自然会选别的格子。禁止为已满时段设计替代推荐、排队等候等机制。

同样一个功能，模型这次生成的代码就干净得多：一个字段记录时段最大人数，一个字段记录当前已预约数，前端判断满了就置灰。仅此而已。

5.2 实测二："智能推荐"场景的产出差异

第二个测试更有代表性，因为它涉及的是一个"听起来就应该很智能"的功能。

传统写法：

首页需要展示推荐服务项目和推荐技师，推荐逻辑要满足用户需求，提升转化。推荐算法要综合考虑用户历史记录、项目热度等。

模型拿到这个需求，直接给我生成了基于协同过滤的推荐引擎设计，还画了一张用户兴趣特征表。虽然模型确实"很努力"，但我们的业务阶段根本没有任何用户行为数据，协同过滤设计得再好也只能是空中楼阁。

隐喻写法：

首页推荐功能的定位是"理发店墙上贴的价目表和今日推荐"，不是千人千面的算法引擎。推荐结果可以基于两个信号：项目在最近七天的预约次数，以及商家的手动置顶。禁止引入用户画像、协同过滤、行为序列模型等任何需要离线训练的机制。

这次的输出完全在预期内：一个字段标注置顶优先级，一个字段统计近七天预约量，排序规则几行代码搞定。

5.3 两组对照测试的量化对比

数据不算严谨，但趋势非常明显。最关键的不只是代码量少了，而是代码结构更接近我会手写的方案，review成本大幅下降。 以前用AI改代码，每次review都像在地雷阵里走一圈，现在扫一眼就知道它没越界。

5.4 实践中遇到的坑：隐喻不是越多越好

凡事过犹不及。我在实践初期犯过一个错误：把整篇需求文档写满了隐喻，每个模块配一个，结果AI在模块之间互相引用隐喻时，推理出现混乱。比如一个模块用"银行柜台叫号屏"做隐喻、另一个模块用"图书馆盖章"做隐喻，两个模型之间完全没有耦合关系，AI在整合模块时就不会搭桥。

现在我确定的经验是：一个项目只用一个系统隐喻，它是整个系统最高层的"世界模型"。 系统隐喻之下的行为隐喻，只用在那些容易让AI过度设计的关键模块，数量控制在两到三个。一个隐喻确实能抵十条规则，但十个隐喻会让模型不知道该以哪个为准。

另外还有一个细节：隐喻和反模式清单里的措辞必须非常直接。AI对"建议不要"这种委婉表达的理解能力偏差很大，我后来统一改成"禁止"。试验下来，"禁止"被模型遵守的概率明显更高。这也算是"让AI恐惧"的某种字面含义吧——在措辞层面，它需要的是确定性，不是礼貌。

6. 写在战斗之后：几点反直觉的经验

在折腾这些方法的过程中，我逐渐改变了对"需求文档"这个产物的很多固有认知。有几条心得特别想分享给同行。

第一，用AI写代码之后，需求文档的读者变了，写法就得跟着变。过去需求文档是写给研发看的，研发有问必答，所以文档可以偷懒，可以依赖"大家都有共识"。但AI不跟你共享任何上下文，它唯一的共识来自它训练数据里的普遍模式。所以AI协作时代的需求文档，本质上是一份"提示词工程"级别的文档，它必须比给人写的文档更密、更冗余、更不依赖常识。 这不是文档变差了，而是文档的用途变了。AI下的需求文档不再只是沟通工具，它本身就是产品定义的一部分。

第二，"让AI恐惧"不是真的去吓唬模型，而是让模型"慢下来"。我观察到，当需求文档里的约束足够明确时，AI的生成行为会发生变化——它不再那么快地输出完整方案，而是会先列几个假设，或者直接问你要一些信息。这是好事，这意味着模型从"最大化续写流畅度模式"切换到了"最大程度匹配约束模式"。你的文档约束越强，AI就越不敢自作主张。

第三，这套方法暴露了一个更大的真相：很多过去看起来是AI能力不够的问题，根源是我们给它的输入太模糊了。 一开始以为用AI编程主要靠提示词技巧，后来发现根子是需求表达的颗粒度。提示词只能优化对话层面的交互，而一份好的需求文档，能让AI从源头上减少脑补空间。这两个层面一个是战术，一个是战略。

第四，这套方法不是产品经理一个人的事。我身边做得最好的团队，是把"隐喻式需求文档"当成整个研发团队的公共资产来维护的。后端在review AI代码时发现了新的AI式过度设计，就会往反模式清单里加一条；产品在提新需求时，也会检查新技术点是否符合系统隐喻。写的人多了，这个文档本身就成了团队知识沉淀的容器。哪怕有一天不用AI编程了，这份文档对人工研发的理解成本也是极大的降低。

最后再分享一个实用小技巧：如果你现在手头有已经跑偏的AI项目想纠正，不需要重写全部需求文档，只需要单独写一份AI_PROJECT_CONSTRAINTS.md，把系统隐喻和反模式清单放进去，然后要求AI在每次动手前先读这个文件。实测下来，大多数已经跑偏的AI代码，都会在后续迭代中逐步被引导回正轨。你先别删它的代码，先建立约束，再让它自己意识到哪些地方违背了约束，这样它的自我修正往往比人类手动重构更贴合原设计。

这就是我最近一段时间在"需求文档起义"这条路上的全部实践了。写这份总结的过程，也是我把自己过去三个月踩过的坑重新梳理了一遍的过程。希望这里的经验能让你和AI协作时少一些"它怎么又没听懂"的崩溃，多一些"这次它做得跟我想的几乎一样"的惊喜。