核心要点：撰写一份清晰的需求说明书，涵盖足够的关键细节（包括结构、风格、测试、边界），以指导AI智能体而不使其不堪重负。将大型任务分解为较小的任务，而不是将所有内容都塞进一个大型提示中。首先在“只读模式”下进行规划，然后持续执行和迭代。
“我听说过很多关于为AI智能体撰写优秀需求说明书的讨论，但还没有找到一个可靠的框架。我可以写一份堪比RFC的需求说明书，但在某些时候，上下文会变得太大，模型就会崩溃。”
许多开发者都有这种挫败感。简单地将一份庞大的需求说明书扔给AI智能体是行不通的——上下文窗口限制和模型的“注意力预算”会成为障碍。关键在于撰写智能的需求说明书：这些文档能清晰地指导智能体，保持在实用的上下文大小内，并随着项目发展而演进。本指南提炼了我使用包括Claude Code和Gemini CLI在内的编码智能体的最佳实践，形成了一个需求说明书撰写框架，能让你的AI智能体保持专注和高效。
我们将介绍优秀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文档所说，提供关于你正在构建什么以及为什么的高层次描述，让编码智能体生成一份专注于用户体验和成功标准的详细需求说明书。从这个大局观开始，可以防止智能体在后续编码时只见树木不见森林。
将你的AI需求说明书视为一份结构化的文档（PRD），包含清晰的章节，而不是一堆松散的笔记。
许多开发者对待智能体的需求说明书就像对待传统的产品需求文档（PRD）或系统设计文档一样——全面、组织良好，便于“字面思维”的AI解析。这种正式的方法为智能体提供了一个蓝图来遵循，并减少了模糊性。
六个核心领域： GitHub对超过2500个智能体配置文件的分析揭示了一个清晰的模式：最有效的需求说明书涵盖六个领域。将其用作完整性的检查清单：
1. 命令： 尽早放置可执行命令——不仅仅是工具名称，而是带有标志的完整命令：npm test、pytest -v、npm run build。智能体将不断引用这些命令。
2. 测试： 如何运行测试、你使用的框架、测试文件的位置以及覆盖率期望。
3. 项目结构： 源代码的位置、测试的位置、文档的位置。要明确：“src/ 用于应用代码，tests/ 用于单元测试，docs/ 用于文档。”
4. 代码风格： 一个展示你风格的真实代码片段胜过三段描述它的段落。包括命名约定、格式化规则和良好输出的示例。