如何为AI智能体撰写一份优秀的需求说明书

核心要点：撰写一份清晰的需求说明书，涵盖足够的关键细节（包括结构、风格、测试、边界），以指导AI智能体而不使其不堪重负。将大型任务分解为较小的任务，而不是将所有内容都塞进一个大型提示中。首先在“只读模式”下进行规划，然后持续执行和迭代。

“我听说过很多关于为AI智能体撰写优秀需求说明书的讨论，但还没有找到一个可靠的框架。我可以写一份堪比RFC的需求说明书，但在某些时候，上下文会变得太大，模型就会崩溃。”

许多开发者都有这种挫败感。简单地将一份庞大的需求说明书扔给AI智能体是行不通的——上下文窗口限制和模型的“注意力预算”会成为障碍。关键在于撰写智能的需求说明书：这些文档能清晰地指导智能体，保持在实用的上下文大小内，并随着项目发展而演进。本指南提炼了我使用包括Claude Code和Gemini CLI在内的编码智能体的最佳实践，形成了一个需求说明书撰写框架，能让你的AI智能体保持专注和高效。

我们将介绍优秀AI智能体需求说明书的五项原则，每项都以一个加粗的要点开始。

1. 从高层次愿景开始，让AI起草细节

用一份简洁的高层次需求说明书启动你的项目，然后让AI将其扩展为详细计划。

与其一开始就过度设计，不如从一个清晰的目标陈述和几个核心要求开始。将其视为一份“产品简报”，然后让智能体从中生成更详细的需求说明书。这利用了AI在细节阐述方面的优势，同时你保持对方向的控制。除非你一开始就感觉有非常具体的技术要求必须满足，否则这种方法效果很好。

为什么有效： 基于LLM的智能体在获得坚实的高层次指令时，擅长充实细节，但它们需要一个明确的使命以避免偏离轨道。通过提供一个简短的提纲或目标描述，并要求AI生成完整的规范（例如 spec.md），你就为智能体创建了一个持久的参考。预先规划对于智能体来说甚至更重要——你可以先迭代计划，然后将其交给智能体来编写代码。这份需求说明书成为你和AI共同构建的第一个工件。

实用方法： 通过提示开始一个新的编码会话：“你是一个AI软件工程师。为[项目X]起草一份详细的需求说明书，涵盖目标、功能、约束和分步计划。”保持你的初始提示是高层级的——例如，“构建一个用户可以跟踪任务（待办事项列表）的Web应用，包含用户账户、数据库和简单的UI”。智能体可能会回应一份结构化的草案需求说明书：概述、功能列表、技术栈建议、数据模型等等。这份需求说明书随后成为你和智能体都可以参考的“唯一事实来源”。GitHub的AI团队推广基于需求说明书的开发，其中“需求说明书成为共享的唯一事实来源……随着项目演进而发展的、可执行的工件”。在编写任何代码之前，审查并完善AI的需求说明书。确保它与你的愿景一致，并纠正任何幻觉或偏离目标的细节。

使用“规划模式”强制执行规划优先： 像Claude Code这样的工具提供了规划模式，该模式限制智能体只能进行只读操作——它可以分析你的代码库并创建详细计划，但在你准备好之前不会编写任何代码。这对于规划阶段来说是理想的：在规划模式下启动（在Claude Code中按Shift+Tab），描述你想要构建的内容，让智能体在探索你现有代码的同时起草一份需求说明书。通过询问计划来要求它澄清模糊之处。让它审查计划的架构、最佳实践、安全风险和测试策略。目标是完善计划，直到没有误解的余地。只有到那时，你才退出规划模式，让智能体执行。这种工作流程避免了在需求说明书不完善之前就直接跳入代码生成的常见陷阱。

将需求说明书作为上下文使用： 一旦获得批准，保存这份需求说明书（例如保存为 SPEC.md），并根据需要将相关部分提供给智能体。许多使用强大模型的开发者正是这样做的——需求说明书文件在会话之间持续存在，每当项目恢复工作时，都能锚定AI。这可以缓解当对话历史过长或必须重启智能体时可能发生的遗忘问题。这类似于团队如何使用产品需求文档（PRD）：一个每个人（人或AI）都可以查阅以保持正轨的参考。正如一位工程师所观察到的，有经验的人经常“先写好文档，模型可能仅凭该输入就能构建出匹配的实现”。需求说明书就是那份文档。

保持目标导向： AI智能体的高层次需求说明书应侧重于“是什么”和“为什么”，而不是“如何做”的细枝末节（至少在最初阶段）。将其视为用户故事和验收标准：用户是谁？他们需要什么？成功是什么样子？（例如，“用户可以添加、编辑、完成任务；数据持久保存；应用响应迅速且安全”）。这使AI的详细需求说明书扎根于用户需求和结果，而不仅仅是技术待办事项。正如GitHub Spec Kit文档所说，提供关于你正在构建什么以及为什么的高层次描述，让编码智能体生成一份专注于用户体验和成功标准的详细需求说明书。从这个大局观开始，可以防止智能体在后续编码时只见树木不见森林。

2. 像专业PRD（或SRS）一样构建需求说明书

将你的AI需求说明书视为一份结构化的文档（PRD），包含清晰的章节，而不是一堆松散的笔记。

许多开发者对待智能体的需求说明书就像对待传统的产品需求文档（PRD）或系统设计文档一样——全面、组织良好，便于“字面思维”的AI解析。这种正式的方法为智能体提供了一个蓝图来遵循，并减少了模糊性。

六个核心领域： GitHub对超过2500个智能体配置文件的分析揭示了一个清晰的模式：最有效的需求说明书涵盖六个领域。将其用作完整性的检查清单：

1. 命令： 尽早放置可执行命令——不仅仅是工具名称，而是带有标志的完整命令：npm test、pytest -v、npm run build。智能体将不断引用这些命令。

2. 测试： 如何运行测试、你使用的框架、测试文件的位置以及覆盖率期望。

3. 项目结构： 源代码的位置、测试的位置、文档的位置。要明确：“src/ 用于应用代码，tests/ 用于单元测试，docs/ 用于文档。”

4. 代码风格： 一个展示你风格的真实代码片段胜过三段描述它的段落。包括命名约定、格式化规则和良好输出的示例。

5. Git工作流程： 分支命名、提交消息格式、PR要求。如果你明确说明，智能体可以遵循这些。

6. 边界： 智能体永远不应触及的内容——密钥、供应商目录、生产配置、特定文件夹。在GitHub的研究中，“永不提交密钥”是最常见的有用约束。

明确你的技术栈： 说“React 18 with TypeScript, Vite, and Tailwind CSS”，而不是“React项目”。包括版本和关键依赖项。模糊的需求说明书会产生模糊的代码。

使用一致的格式： 清晰为王。许多开发者使用Markdown标题甚至XML风格的标签来划分需求说明书中的章节，因为AI模型处理结构良好的文本比自由形式的散文更好。例如，你可以将需求说明书结构化为：

# 项目需求说明书：我的团队任务应用

## 目标
- 构建一个供小团队管理任务的Web应用...

## 技术栈
- React 18+、TypeScript、Vite、Tailwind CSS
- Node.js/Express后端、PostgreSQL、Prisma ORM

## 命令
- 构建：`npm run build`（编译TypeScript，输出到dist/）
- 测试：`npm test`（运行Jest，提交前必须通过）
- 代码检查：`npm run lint --fix`（自动修复ESLint错误）

## 项目结构
- `src/` – 应用程序源代码
- `tests/` – 单元和集成测试
- `docs/` – 文档

## 边界
- ✅ 始终：提交前运行测试，遵循命名约定
- ⚠️ 先询问：数据库模式更改、添加依赖项
- 🚫 永不：提交密钥、编辑node_modules/、修改CI配置

这种组织水平不仅有助于你清晰思考，也有助于AI查找信息。Anthropic的工程师推荐将提示组织成不同的部分（如 <background>、<instructions>、<tools>、<output_format> 等），正是出于这个原因——它给模型提供了关于哪些信息是哪些的强烈提示。记住，“简洁不一定意味着简短”——如果细节重要，不要回避在需求说明书中包含细节，但要保持专注。

将需求说明书集成到你的工具链中： 将需求说明书视为与版本控制和CI/CD绑定的“可执行工件”。GitHub Spec Kit使用一个四阶段、有门控的工作流程，使你的需求说明书成为工程过程的中心。不是写一份需求说明书然后放在一边，而是需求说明书驱动实现、检查清单和任务分解。你的主要角色是掌舵；编码智能体负责大部分的编写工作。每个阶段都有特定的工作，在当前任务完全验证之前，你不会进入下一个阶段：

1. 明确需求： 你提供关于你正在构建什么以及为什么的高层次描述，编码智能体生成一份详细的需求说明书。这不是关于技术栈或应用设计——而是关于用户旅程、体验以及成功的样子。谁将使用它？它解决了什么问题？他们将如何与之交互？将其视为映射你想要创建的用户体验，并让编码智能体充实细节。这成为一个随着你了解更多而演进的活文档。

2. 规划： 现在你进入技术层面。你提供期望的技术栈、架构和约束，编码智能体生成一份全面的技术计划。如果你的公司标准化了某些技术，就在这里说明。如果你正在与遗留系统集成或有合规要求，所有这些都放在这里。你可以要求多个计划变体以比较方法。如果你提供内部文档，智能体可以直接将你的架构模式集成到计划中。

3. 任务： 编码智能体获取需求说明书和计划，并将其分解为实际的工作——小的、可审查的块，每个块解决一个特定的难题。每个任务应该是你可以独立实现和测试的东西，几乎就像为你的AI智能体进行测试驱动开发。不是“构建身份验证”，而是得到具体的任务，如“创建一个验证电子邮件格式的用户注册端点”。

4. 实现： 你的编码智能体逐个（或并行）处理任务。不是审查数千行的代码转储，而是审查解决特定问题的专注更改。智能体知道构建什么（需求说明书）、如何构建（计划）以及做什么工作（任务）。关键的是，你的角色是在每个阶段进行验证：需求说明书是否捕捉了你想要的东西？计划是否考虑了约束？AI是否遗漏了边缘情况？该过程内置了检查点，让你在继续前进之前进行批评、发现差距并调整方向。

这种有门控的工作流程防止了Willison所说的“纸牌屋代码”——在审查下崩溃的脆弱AI输出。Anthropic的Skills系统提供了类似的模式，让你定义可重用的基于Markdown的行为，供智能体调用。通过将你的需求说明书嵌入这些工作流程，你可以确保智能体在需求说明书被验证之前无法继续，并且更改会自动传播到任务分解和测试中。

考虑为专门角色使用agents.md： 对于像GitHub Copilot这样的工具，你可以创建agents.md文件，这些文件定义了专门的智能体角色——用于技术写作的@docs-agent、用于QA的@test-agent、用于代码审查的@security-agent。每个文件都充当该角色行为、命令和边界的专注需求说明书。当你想要为不同任务使用不同的智能体，而不是一个通用助手时，这特别有用。

为智能体体验（AX）设计： 就像我们为开发者体验（DX）设计API一样，考虑为“智能体体验”设计需求说明书。这意味着干净、可解析的格式：智能体将使用的任何API的OpenAPI模式、总结文档以供LLM使用的llms.txt文件，以及明确的类型定义。Agentic AI Foundation（AAIF）正在标准化像MCP（模型上下文协议）这样的协议以进行工具集成——遵循这些模式的需求说明书更容易被智能体可靠地使用和执行。

PRD与SRS思维模式： 借鉴已建立的文档实践是有帮助的。对于AI智能体需求说明书，你经常会将这两者融合到一个文档中（如上所述），但涵盖这两个角度对你很有好处。像PRD一样编写它确保你包含以用户为中心的上下文（“每个功能背后的原因”），这样AI就不会为错误的事情进行优化。像SRS一样扩展它确保你确定了AI实际生成正确代码所需的细节（比如使用什么数据库或API）。开发者发现，这种额外的前期努力通过大幅减少后续与智能体的沟通误解而获得回报。

使需求说明书成为“活文档”： 不要写了就忘了。当你和智能体做出决定或发现新信息时，更新需求说明书。如果AI不得不更改数据模型，或者你决定削减一个功能，在需求说明书中反映出来，使其保持为基本事实。将其视为版本控制的文档。在基于需求说明书的工作流程中，需求说明书驱动实现、测试和任务分解，在需求说明书被验证之前，你不会进入编码阶段。这个习惯保持了项目的连贯性，特别是如果你或智能体离开并稍后回来。记住，需求说明书不仅仅是为了AI——它帮助你作为开发者保持监督，并确保AI的工作满足真实的需求。

3. 将任务分解为模块化提示和上下文，而不是一个大型提示

分而治之：一次给AI一个专注的任务，而不是一个包含所有内容的一体化提示。

经验丰富的AI工程师已经了解到，试图将整个项目（所有需求、所有代码、所有指令）塞进一个单一的提示或智能体消息中，是导致混乱的秘诀。你不仅有可能触及令牌限制，还可能因为“指令诅咒”而使模型失去焦点——太多指令导致它无法很好地遵循任何一条。解决方案是以模块化的方式设计你的需求说明书和工作流程，一次处理一个部分，并且只拉入该部分所需的上下文。

过多上下文/指令的诅咒： 研究证实了许多开发者从经验中看到的情况：随着你在提示中堆积更多的指令或数据，模型遵守每条指令的性能显著下降。一项研究称此为“指令诅咒”，表明即使是GPT-4和Claude在被要求同时满足许多需求时也会挣扎。在实际意义上，如果你呈现10个详细规则的要点，AI可能会遵守前几个，然后开始忽略其他。更好的策略是迭代式聚焦。行业指南建议将复杂需求分解为顺序的、简单的指令作为最佳实践。一次让AI专注于一个子问题，完成后再继续。这保持了高质量和可管理的错误。

将需求说明书划分为阶段或组件： 如果你的需求说明书文档非常长或涵盖了很多内容，考虑将其分成几部分（物理上分开的文件或清晰分开的章节）。例如，你可能有一个“后端API需求说明书”部分和另一个“前端UI需求说明书”部分。当AI在处理后端时，你不需要总是将前端需求说明书提供给AI，反之亦然。许多使用多智能体设置的开发者甚至为每个部分创建单独的智能体或子进程——例如，一个智能体处理数据库/模式，另一个处理API逻辑，另一个处理前端——每个都有相关的需求说明书片段。即使你使用单个智能体，你也可以通过仅将相关的需求说明书章节复制到该任务的提示中来模拟这一点。避免上下文过载：不要在一次操作中混合身份验证任务和数据库模式更改，正如DigitalOcean AI指南所警告的那样。保持每个提示紧密围绕当前目标。

大型需求说明书的扩展目录/摘要： 一个聪明的技术是让智能体为需求说明书构建一个带有摘要的扩展目录。这本质上是一个“需求说明书摘要”，将每个部分浓缩为几个关键点或关键词，并引用可以找到详细信息的地方。例如，如果你的完整需求说明书有一个关于“安全要求”的部分，长达500字，你可以让智能体将其总结为：“安全：使用HTTPS，保护API密钥，实现输入验证（参见完整需求说明书§4.2）”。通过在规划阶段创建分层摘要，你可以获得一个鸟瞰图，可以保留在提示中，而细节则保持卸载状态，除非需要。这个扩展目录充当索引：智能体可以查阅它并说“啊哈，有一个安全部分我应该看看”，然后你可以根据需要提供该部分。这类似于人类开发者如何浏览提纲，然后在处理特定部分时翻到需求说明书文档的相关页面。

要实现这一点，你可以在编写需求说明书后提示智能体：“将上面的需求说明书总结成一个非常简洁的提纲，包含每个章节的关键点和引用标签。”结果可能是一个章节列表，每个章节有一两句话的摘要。该摘要可以保存在系统或助手消息中，以指导智能体的焦点，而不会占用太多令牌。这种分层摘要方法已知可以帮助LLM通过专注于高层次结构来维持长期上下文。智能体携带了需求说明书的“心智地图”。

为不同的需求说明书部分利用子智能体或“技能”： 另一种高级方法是使用多个专门的智能体（Anthropic称之为子智能体，或者你可能称之为“技能”）。每个子智能体都配置用于特定的专业领域，并给予与该领域相关的需求说明书部分。例如，

---

AI拉呱，🤖 大厂 P8级别 资深算法研究员 / 某双一流硕导🎖️ 政府领军创新人才 | 资深 AI 实战家

专注于 AI 前沿技术洞察与技术脉络梳理。主张“从算法深度到应用价值”的闭环思考。在这里，分享硬核干货与 AI 效率工具。💡 关注我一起交流，在 AI 浪潮中迭代成长💡 。

AI拉呱介绍：连接前沿算法与商业落地的深度桥梁。

我们立足于全球 AI 技术爆发的最前沿，不仅致力于深度拆解 AI 技术底层脉络，更专注于将复杂的算法演进转化为可落地的商业决策参考。

• 前沿洞察： 追踪生成式 AI、大模型架构及多模态技术的最新动态，提供极具深度的行业分析。
• 咨询服务： 依托大厂资深实战背景，为企业与个人提供定制化的 AI 转型方案与项目技术指导。
• 效能革命： 严选全球尖端 AI 效率工具，助力用户实现从“体力劳动”到“智能创作”的范式迁移。

AI拉呱，让技术不再悬浮，让创新触手可及。