如何撰写AI智能体范围文档

2026年8月发布。

TL;DR： 范围文档是把「我想为我的业务做一个AI智能体」变成一个可以报价、客户也能签字确认的数字的关键。它需要六个部分：触发条件、输入、输出、涉及的工具、明确排除的内容，以及一份书面的验收测试清单。要在报出构建费之前写好它，而不是之后。我把它定价为500–1,000美元的固定审计交付物，与构建费分开收取。

【运营者视角】 我在一个咨询品牌和Pickleland（德克萨斯州普夫卢格维尔的匹克球场馆）之上运行着30多个生产环境智能体，也在这份经验的基础上为客户的智能体构建项目做过范围界定。一个智能体项目出问题，最常见的原因从来都不是代码本身——而是在开票之前，没有人写下「完成」到底意味着什么。一份范围文档能在一次会谈里就解决这个问题。它是我出品的交付物里最不起眼的一个，却也是最能省掉争执的一个。

目录

为什么是范围文档，而不是一封提案邮件

一封提案邮件描述的是你将要做什么。一份范围文档定义的是「完成」看起来是什么样子——具体到你和客户都能对照完成的智能体逐条核对，并且不需要再讨论就能一致判定它是否通过。

这个区别很重要，因为AI智能体定价只有在构建费依附于某个固定对象时才成立。对着一个未定义的范围报出固定价格，你报出的就是一个你实际上无法交付的数字——客户对「为我的业务做一个AI智能体」的想象会一直免费膨胀下去，直到你出面反对为止，而在收了定金之后再去反对，比在一开始就划清边界要难谈得多。

我为每一个构建项目都写一份，包括小项目。单一工作流的智能体只需要半页的版本。多智能体系统需要完整的文档。格式不变——变的只是篇幅。

一份范围文档需要的六件事

1. 触发条件。 是什么启动了智能体的运行——表单提交、定时任务、一封收到的邮件、来自另一个工具的webhook。要写出确切的触发条件，而不是一个触发条件的类别。「当线索表单被提交时运行」是范围。「处理入站线索」不是。

2. 输入。 智能体接收什么数据，数据来自哪里。要列出具体字段，而不只是来源——是「姓名、邮箱、公司规模，以及Typeform提交内容里的自由文本留言字段」，而不是「表单数据」。

3. 输出。 智能体产出什么，产出的内容送到哪里去。同样的规则：写清楚目的地和格式。「把草拟的回复发到#leads这个Slack频道，等待人工批准」是范围。「回复线索」不是。

4. 涉及的工具和集成。 智能体调用的每一个API、数据库或平台。这里也是你要写清楚自己明确不集成什么的地方——一个只在发现会谈里提过一次CRM、就默认它被包含在内的客户，是我见过最常见的范围蔓延来源。

5. 明确排除的内容。 一份简短、明确的清单，列出智能体不会做的事情，哪怕听起来沾边。如果你在构建一个线索分类智能体，就写下「不发送出站消息」，哪怕这看起来是显而易见的——对你来说显而易见的事，对一个从未做过软件范围界定的客户来说未必如此。

6. 验收测试清单。 在最终付款到期之前，完成的智能体必须通过的实际测试用例清单。不是「运行良好」——而是具体的、可核查的用例：「在提供的数据集中，正确分类10个样本线索中的9个」「成功发布到已连接的Slack频道，无需人工干预」「遇到格式错误的提交（缺少邮箱字段）时不崩溃」。这是文档中最重要的一个部分，因为它是双方以后都能直接指向的东西，而不必再重新争论当初到底是什么意思。

模板

这是我实际使用的结构。复制它，填好这六个部分，你就有了一份可以据此定价的文档。

AGENT SCOPE DOCUMENT — [Client name] / [Project name]
Date: [date]

1. TRIGGER
   [What starts this agent running]

2. INPUTS
   [Exact data fields and their source]

3. OUTPUTS
   [What the agent produces, in what format, sent where]

4. TOOLS & INTEGRATIONS
   Included: [every API/platform/database touched]
   Explicitly excluded: [anything adjacent that is NOT built]

5. EXCLUSIONS
   [What this agent will not do, even if related]

6. ACCEPTANCE TESTS
   [ ] [Specific, checkable test case]
   [ ] [Specific, checkable test case]
   [ ] [Specific, checkable test case]
   ...

BUILD FEE: $[amount], due [payment terms]
MAINTENANCE RETAINER: $[amount]/month, starting [date]
CHANGE REQUESTS: priced separately, quoted before work starts

Signed: _______________  Date: _______

构建费和维护费这两行的存在，是为了让价格直接锚定在上面的范围之上——如果你还没为一个构建项目定过价，可以参考我如何确定这两个数字。客户签署这份文档时，是在同一个动作里对范围和价格都签字确认，这正是它的意义所在。

我如何进行产出这份文档的那通电话

我把范围界定会谈本身定价为500–1,000美元的固定审计费，与构建费分开收取——从不并入构建费，哪怕客户最终会继续推进。原因有两个：一是让范围界定环节不至于沦为无偿的销售工作，二是让客户认真对待这通电话，而不是把它当成一次免费咨询。

这通电话本身持续30–45分钟，按上面六个部分的顺序展开。我不会让谈话跑偏到「一个AI智能体理论上能为你的业务做些什么」——那是另一场更昂贵的谈话，也是那种产出没人能定价的文档的谈话。我会先问触发条件，因为一个说不清楚流程从哪里开始的客户，通常还没有一个足够稳定的工作流程可以被自动化——这一点值得在你们任何一方承诺构建之前就浮出水面。

交出提示词，而不是空白页

我不会手写这份文档的初稿。我会把通话笔记——往往只是一段杂乱的要点——粘贴进Claude：

Here are my raw notes from a scoping call for an AI agent build. Turn them
into a scope document with exactly these six sections: Trigger, Inputs,
Outputs, Tools & Integrations, Exclusions, Acceptance Tests. For each
section, flag anything the notes don't specify clearly enough to build
against, rather than guessing or filling the gap yourself. The acceptance
tests need to be specific and checkable — reject vague criteria like
"works correctly" and either sharpen them into a concrete test case or
flag them for me to clarify with the client.

[paste raw notes]

最后那条指令——标记出空白而不是自行填补——才是关键所在。模型很乐意编造一条听起来合理的验收测试来把文档补完整，而一条听起来合理、却和客户实际意思对不上的测试，比一个需要你回去询问的空白更糟糕。

我仍然常见的一些错误

把排除事项部分放到最后写，或者干脆跳过它。 排除事项部分是大多数人认为可有可无的那一部分。它却是最能防止争议的一部分。要在验收测试之前写它，而不是之后。

描述行为而不是结果的验收测试。 「智能体应该理解客户的语气」是行为。「智能体草拟的回复在10个样本用例中有7个无需修改就被批准」是结果。只有结果是可核查的。

只凭一次谈话、没有书面笔记就做范围界定。 如果范围文档是这次合作的第一份书面产物，那你是在几天后凭记忆重建那通电话的内容。在通话中按六个部分的顺序做笔记，文档基本上就自己写出来了。

让客户来写范围。 客户用自己的话描述他们想要什么，是文档的输入，而不是文档本身。他们的语言通常是「功能形状」的（「我希望它能处理我的线索」），而不是「测试形状」的。把这些转化成可核查的验收标准，才是范围界定会谈真正的价值所在——这也是为什么它是一项付费交付物，而不是一张客户自己填的表格。

我用来完成这项工作的工具

Claude 用上面的提示词，把原始通话笔记起草成文档，并标记出空白而不是自行猜测。

Notion 是最终范围文档存放的地方，在收取任何定金之前就与客户共享——也是我保存这次合作其余书面记录的同一个地方。

Airtable 追踪哪些项目处于范围界定阶段、哪些已签约、哪些正在构建中，一个客户一行记录，这样就不会有范围文档悄悄躺在那里几周无人签字而没人发现。

常见问题

一份范围文档应该写多长？

写到能让每一条验收测试都可核查为止，不需要更长。单一工作流的智能体可能只需要半页。带有多个集成的多智能体系统可能要写到两三页。篇幅不是目标——客户和开发者各自独立阅读验收测试、并对是否通过达成一致，才是目标。

如果客户在签字之后想要修改范围怎么办？

那属于变更请求，单独定价，并在开始工作之前先报价——把这一条写进文档本身，就像上面模板里那样。一份签字之后还能被悄悄扩大的范围文档，其实算不上一份真正的范围文档。

非常小的自动化项目也需要范围文档吗？

需要，只是一份简短的版本。价值不在于篇幅——而在于在开始构建之前就有一份书面的验收测试清单，这样「完成」就是一张清单，而不是一种感觉。正因为如此，我见过一些非正式界定范围的小项目，反而比那些范围界定得当的大项目拖得更久。

范围文档本身归谁所有——它算交付物的一部分吗？

无论客户是否最终推进到构建阶段，我都把它当作客户可以保留的东西，因为他们已经为产出它的那次审计付了费。我保留的是底层的模板和提示词，就像我在各个项目之间保留可复用的脚手架一样——文档的结构是我的，其中关于他们具体业务的填写内容是他们的。

下一步： 我的AI Agents for Beginners课程涵盖了构建这类范围文档所描述的智能体的方法。协作项目面向想要在结构化环境中练习范围界定和构建这类工作的运营者。如果你更希望有人为你写好范围文档，预约一次30分钟的会谈。