如何给 AI 智能体写一份好的需求规格

本文最初发表于 Addy Osmani 的 [Elevate] Substack 通讯，经作者授权在此转载。

太长不看版：写一份清晰的规格文档，包含恰到好处的细节（可能涉及结构、风格、测试、边界等），既能引导 AI 又不会把它"淹没"。把大任务拆成小任务，而不是塞进一个巨大的提示词里。先用只读模式做规划，再执行，然后持续迭代。

“我听说了很多关于给 AI 智能体写好规格的说法，但一直没找到一个靠谱的框架。我可以写一份堪比 RFC 的规格文档，但到某个程度上下文太大，模型就崩了。”

很多开发者都有这种困扰。把一份巨大的规格一股脑丢给 AI 智能体是行不通的——上下文窗口的限制和模型的"注意力预算"会成为拦路虎。关键是要写聪明的规格：能清晰引导智能体，保持在实际可用的上下文大小范围内，并且能随项目演进。本指南从我使用 Claude Code、Gemini CLI 等编码智能体的经验中提炼出最佳实践，形成一套规格写作框架，让你的 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）来写，而不是一堆零散的笔记。

很多开发者对待 AI 智能体的规格就像对待传统的产品需求文档（PRD）或系统设计文档一样：全面、条理清晰，便于"一板一眼"的 AI 解析。这种正式的写法给智能体提供了一份蓝图，减少了歧义。

六大核心领域

GitHub 分析了超过 2500 个智能体配置文件后发现了一个清晰的规律：最有效的规格涵盖六个领域。把这个当作完整性检查清单：

命令（Commands）：把可执行命令放在前面——不只是工具名，而是带参数的完整命令：npm test、pytest -v、npm run build。智能体会频繁引用这些命令。

测试（Testing）：怎么运行测试、用什么框架、测试文件放在哪里、覆盖率期望是什么。

项目结构（Project structure）：源代码放哪里、测试放哪里、文档放哪里。要明确："src/ 放应用代码，tests/ 放单元测试，docs/ 放文档。"

代码风格（Code style）：一段真实的代码示例胜过三段文字描述。包括命名规范、格式化规则和好的输出示例。

Git 工作流（Git workflow）：分支命名、提交信息格式、PR 要求。你写清楚了，智能体就能照做。

边界（Boundaries）：智能体绝对不能碰的东西——密钥、第三方目录、生产配置、特定文件夹。“永远不要提交密钥"是 GitHub 研究中最常见的有效约束。

明确你的技术栈： 要说"React 18 + TypeScript + Vite + 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/` – 文档
## 边界
- ✅ 始终做：提交前运行测试，遵循命名规范
- ⚠️ 先问再做：数据库 schema 变更，添加依赖
- 🚫 绝不做：提交密钥，编辑 node_modules/，修改 CI 配置

这种组织方式不仅帮你理清思路，也帮 AI 快速定位信息。Anthropic 的工程师推荐将提示词组织成不同的章节（如 <background>、<instructions>、<tools>、<output_format> 等），原因就在此：它给模型明确的信号，知道哪些信息是什么性质的。记住，“精简不等于短”——如果细节很重要，不要回避在规格中详细展开，但要保持聚焦。

将规格嵌入你的工具链： 把规格当作与版本控制和 CI/CD 绑定的"可执行产出物"。GitHub Spec Kit 采用四阶段门控工作流，让规格成为你工程流程的核心。规格不是写完就放一边，而是驱动实现、检查清单和任务拆解。你的主要角色是掌舵，编码智能体负责大部分编写工作。每个阶段有明确的职责，当前阶段完全验证后才进入下一个：

1. 规格化（Specify）：你提供要构建什么以及为什么的高层描述，编码智能体生成详细规格。这不是关于技术栈或应用设计——而是关于用户旅程、体验、和成功标准。谁会使用？解决什么问题？他们如何交互？可以理解为：你描绘你想创造的用户体验，让编码智能体来充实细节。这会成为一个随着你了解更多而不断演进的"活文档"。

2. 规划（Plan）：现在进入技术层面。你提供期望的技术栈、架构和约束，编码智能体生成全面的技术方案。如果公司有标准化的技术选型，在这里明确。如果要对接遗留系统或有合规要求，也在这里说明。你可以要求生成多个方案变体来对比。如果你提供了内部文档，智能体可以把你的架构模式直接整合到方案中。

3. 任务拆解（Tasks）：编码智能体拿着规格和方案，把它们拆成具体的工作——小而可审查的块，每个解决一个具体问题。每个任务应该可以独立实现和测试，有点像给 AI 智能体做测试驱动开发。不是"构建认证"，而是"创建一个验证邮箱格式的用户注册接口"。

4. 实现（Implement）：编码智能体逐个（或并行）处理任务。你审查的不是几千行代码，而是解决特定问题的聚焦变更。智能体知道要构建什么（规格）、怎么构建（方案）、做哪个（任务）。关键是，你在每个阶段都要验证：规格是否表达了你的意图？方案是否考虑了约束？AI 是否遗漏了边界情况？流程中内置了检查点，让你能在推进之前发现问题、填补缺口、纠正方向。

这种门控式工作流防止了 Willison 所说的"纸牌屋代码"——经不起仔细推敲的脆弱 AI 输出。Anthropic 的 Skills 系统提供了类似的模式，让你定义可复用的基于 Markdown 的行为，由智能体调用。把规格嵌入这些工作流，确保智能体在规格验证前无法推进，变更能自动传播到任务拆解和测试中。

考虑用 agents.md 定义专门角色： 对于 GitHub Copilot 等工具，你可以创建 agents.md 文件来定义专门角色——@docs-agent 负责技术写作，@test-agent 负责 QA，@security-agent 负责代码审查。每个文件都是该角色的行为、命令和边界的聚焦规格。当你想让不同的智能体做不同的事而不是用一个通用助手时，这特别有用。

为智能体体验（AX）而设计： 就像我们为开发者体验（DX）设计 API 一样，考虑为"智能体体验"设计规格。这意味着干净、可解析的格式：智能体要使用的 API 用 OpenAPI Schema，用 llms.txt 文件为 LLM 消费场景总结文档，以及明确的类型定义。Agentic AI Foundation（AAIF）正在标准化 MCP（Model Context Protocol，模型上下文协议）等用于工具集成的协议。遵循这些模式的规格更容易被智能体消费和可靠执行。

PRD 与 SRS 思维的融合： 借鉴成熟的文档实践很有帮助。对于 AI 智能体规格，你通常会把这两者融合成一份文档（如上面的示例），但覆盖两个角度对你很有利。像 PRD 那样写，确保你包含了以用户为中心的上下文（“每个功能背后的为什么”），这样 AI 就不会朝错误的方向优化。像 SRS 那样扩展，确保你钉死了 AI 生成正确代码所需的具体细节（比如用什么数据库或 API）。开发者发现，这种前期额外的投入，能大幅减少后续跟智能体的"鸡同鸭讲"。

让规格成为"活文档"： 写完不要就扔在一边。当你和智能体做出决策或发现新信息时，及时更新规格。如果 AI 不得不修改数据模型，或者你决定砍掉某个功能，把这些反映到规格中，让它始终是"地面真相"。把它想成版本控制的文档。在规格驱动的工作流中，规格驱动实现、测试和任务拆解，规格验证通过前不进入编码阶段。这个习惯让项目保持连贯，特别是当你或智能体中途离开又回来时。记住，规格不只是为 AI 写的——它也帮助你作为开发者保持监督，确保 AI 的工作满足真正的需求。

3. 把任务拆成模块化的提示词和上下文，而不是一个大提示词

分而治之：一次给 AI 一个聚焦的任务，而不是把所有东西堆进一个巨大的提示词里。

有经验的 AI 工程师已经学到，试图把整个项目（所有需求、所有代码、所有指令）塞进一个提示词或智能体消息中，结果只会是一团糟。你不仅可能触及 token 限制，还会导致模型因"指令诅咒“而失焦——指令太多，结果哪条都做不好。解决方案是以模块化的方式设计你的规格和工作流，一次处理一个部分，只提供该部分需要的上下文。

上下文/指令过多的诅咒： 研究证实了很多开发者凭经验观察到的现象：随着你往提示词里堆积越来越多的指令或数据，模型对每条指令的遵循程度会显著下降。一项研究称之为"指令诅咒”，表明即使是 GPT-4 和 Claude，在被要求同时满足多个需求时也会挣扎。实际来说，如果你列出 10 条详细规则，AI 可能前几条照做了，后面的就开始忽略。更好的策略是迭代聚焦。来自行业的指南建议将复杂需求分解为顺序执行的简单指令。一次让 AI 专注于一个子问题，解决完再移到下一个，这样质量更高、错误更可控。

把规格按阶段或组件拆分： 如果你的规格文档很长或覆盖范围很广，考虑把它拆成多个部分（物理上的独立文件或清晰的独立章节）。比如，你可以有一个"后端 API 规格"章节和一个"前端 UI 规格"章节。当 AI 在做后端时，你不需要把前端规格也喂给它，反之亦然。很多使用多智能体方案的开发者甚至为每个部分创建独立的智能体或子进程（比如一个智能体做数据库/Schema，一个做 API 逻辑，一个做前端——每个只拿到规格中相关的切片）。即使你用单个智能体，也可以通过只将相关的规格章节复制到该任务的提示词中来模拟这种做法。避免上下文过载：不要在一个提示词里同时处理认证任务和数据库 Schema 变更，正如 DigitalOcean AI 指南所警示的那样。让每个提示词紧密围绕当前目标。

为大型规格建立扩展目录/摘要： 一个巧妙的技巧是让智能体为规格构建一份带摘要的扩展目录——本质上是一份"规格摘要"，把每个章节浓缩成几个关键点或关键词，并标注详细内容在哪里。比如，如果你的完整规格中有一个 500 字的安全需求章节，你可以让智能体把它浓缩为：“安全：使用 HTTPS，保护 API 密钥，实现输入验证（详见完整规格 §4.2）。“通过在规划阶段创建这种层次化摘要，你获得了一个可以留在提示词中的鸟瞰视图，而细节只在需要时才加载。这份扩展目录就像一个索引：智能体可以参考它说"啊，有个安全章节我需要看”，然后你再按需提供该章节。就像人类开发者先浏览大纲，然后翻到规格文档的相关页面来做具体工作一样。

要落地这个方法，你可以在写完规格后这样提示智能体：“把上面的规格总结成一份非常简练的大纲，每个章节列出关键点和参考标签。“结果可能是一份带一两句摘要的章节列表。这份摘要可以保留在系统消息或助手消息中，引导智能体关注重点，同时不会消耗太多 token。这种层次化摘要方法已被证明能帮助 LLM 通过关注高层结构来维持长期上下文。智能体相当于带着一份规格的"思维导图"在工作。

利用子智能体或"技能"处理规格的不同部分： 另一种高级方法是使用多个专门化的智能体（Anthropic 称之为子智能体，你也可以叫"技能”）。每个子智能体针对特定的专业领域配置，只拿到规格中与该领域相关的部分。比如，你可以有一个数据库设计子智能体只知道数据模型章节，一个 API 编码子智能体只知道 API 端点规格。主智能体（或编排器）可以自动将任务路由到合适的子智能体。

好处是每个智能体需要处理的上下文窗口更小、角色更聚焦，这可以提升准确性并允许对独立任务进行并行工作。Anthropic 的 Claude Code 支持这一点，让你用各自的系统提示词和工具来定义子智能体。“每个子智能体都有特定的用途和专业领域，使用独立于主对话的上下文窗口，并有指导其行为的自定义系统提示词。“当出现匹配某个子智能体领域的任务时，Claude 可以将该任务委派给它，子智能体独立返回结果。

并行智能体提升吞吐量： 同时运行多个智能体正在成为开发者效率的"下一个大趋势”。与其等一个智能体完成才开始下一个任务，不如为不重叠的工作启动并行智能体。Willison 将此描述为”拥抱并行编码智能体"，并指出这"出奇地有效，尽管在精神上很累”。关键是划分好任务范围，让智能体不会互相踩脚：一个智能体写功能代码，另一个写测试，或者各自构建独立的组件。LangGraph 或 OpenAI Swarm 等编排框架可以帮助协调这些智能体，通过向量数据库（如 Chroma）的共享记忆让它们访问公共上下文而无需重复提示。

单智能体 vs 多智能体：何时用哪种

实际操作中，使用子智能体或特定技能的提示词可能是这样的：你维护多个规格文件（或提示词模板）——比如 SPEC_backend.md、SPEC_frontend.md——然后告诉 AI：“做后端任务时参考 SPEC_backend；做前端任务时参考 SPEC_frontend。“或者在 Cursor/Claude 等工具中，你实际启动每个子智能体。这比单智能体循环设置起来更复杂，但它模拟了人类开发者的做法：我们在心里把大型规格拆分成相关的块。（你不会把整份 50 页的规格同时装在脑子里；你回忆当前任务需要的那部分，同时对整体架构保持一个大概的感知。）挑战在于管理依赖关系：子智能体之间仍需协调。（前端需要知道后端规格中的 API 契约。）一个中央概览（或"架构师"智能体）可以通过引用各子规格来帮助确保一致性。

让每个提示词聚焦于一个任务/章节： 即使不用花哨的多智能体方案，你也可以手动实施模块化。比如，规格写好后，你的下一步可能是：“步骤 1：实现数据库 Schema。“你只把规格的数据库章节加上全局约束（如技术栈）喂给智能体。让它完成。然后步骤 2：“现在实现认证功能”，你提供规格的认证章节和可能需要的 Schema 相关部分。通过为每个主要任务刷新上下文，你确保模型不会携带大量过时的或无关的信息来分散注意力。正如一份指南建议的："重新开始：在切换主要功能时开启新会话以清理上下文。“你可以每次都提醒智能体关键的全局规则（来自规格的约束章节），但如果不是全都需要，就不要把整份规格塞进去。

使用行内指令和代码 TODO： 另一个模块化技巧是把你的代码或规格变成对话的活跃部分。比如，用 // TODO 注释搭建代码骨架，描述每处需要做什么，然后让智能体逐个填充。每个 TODO 本质上就是一个小任务的迷你规格。这让 AI 保持高度聚焦（“按照这段规格片段实现这个具体函数”），你可以在紧密的循环中迭代。这就像一次给 AI 一个检查清单项去完成，而不是一次给整个清单。

底线： 小而聚焦的上下文胜过一个巨大的提示词。这提升了质量，防止 AI 被太多东西"淹没”。正如一组最佳实践总结的：给模型"一次一个任务焦点"和"只提供相关信息”，避免把所有东西到处堆。通过把工作组织成模块——并利用规格摘要或子规格智能体等策略——你就能绕过上下文大小限制和 AI 的短期记忆上限。记住，喂得好的 AI 就像一个设计良好的函数：只给它当前工作需要的输入。

4. 内置自检、约束和人类专业知识

让你的规格不只是给智能体的待办清单，还是质量控制指南——别怕注入你自己的专业知识。

一份好的 AI 智能体规格会预判 AI 可能出错的地方并设置护栏。它还会利用你所知道的（领域知识、边界情况、“坑”），让 AI 不会在真空中操作。把规格想成 AI 的教练兼裁判：它应该鼓励正确的做法，也要及时吹哨。

使用三级边界体系： GitHub 对 2500+ 智能体文件的分析发现，最有效的规格使用三级边界体系，而不是简单的"禁止事项清单”。这让智能体更清楚什么时候放心做、什么时候暂停、什么时候停下来：

✅ 始终做： 智能体无需询问就应该执行的操作。“始终在提交前运行测试。““始终遵循风格指南中的命名规范。““始终将错误日志发送到监控服务。”

⚠️ 先问再做： 需要人类批准的操作。“修改数据库 Schema 前先问。““添加新依赖前先问。““修改 CI/CD 配置前先问。“这一级别捕获那些可能没问题但值得人类过目的高影响变更。

🚫 绝不做： 硬性禁止。“绝不提交密钥或 API Key。““绝不编辑 node_modules/ 或 vendor/。““绝不在未获批准的情况下删除失败的测试。“研究中最常见的有效约束就是"绝不提交密钥”。

这种三级方法比扁平的规则列表更细致。它承认有些操作始终安全、有些需要监督、有些绝对禁止。智能体可以放心执行"始终做"的项目，把"先问再做"的标记给你审查，在"绝不做"的项目面前硬停。

鼓励自我验证： 一个强大的模式是让智能体自动对照规格验证自己的工作。如果你的工具允许，可以集成单元测试或 linting 等检查，让 AI 在生成代码后运行。即使在规格/提示词层面，你也可以指示 AI 自查（比如：“实现后，对照规格检查结果，确认所有需求都已满足。列出任何未涉及的规格项。"）。这推动 LLM 根据规格反思自己的输出，捕捉遗漏。这是内置在流程中的一种自审计。

比如，你可以在提示词末尾加上："（写完函数后，审查上面的需求列表，确保每一条都已满足，标注任何遗漏的。）“模型理想情况下会输出代码，然后跟一份简要的检查清单，说明是否满足了每个需求。这在你运行测试之前就减少了遗忘的机会。虽然不是万无一失，但确实有帮助。

用 LLM 做裁判评估主观标准： 对于难以自动化测试的标准——代码风格、可读性、是否遵循架构模式——考虑使用"LLM 做裁判”（LLM-as-a-Judge）。也就是用第二个智能体（或单独的提示词）根据你规格中的质量指引审查第一个智能体的输出。Anthropic 等发现这对主观评估很有效。你可以这样提示：“审查这段代码是否遵循我们的风格指南。标记任何违规。“裁判智能体返回反馈，要么被采纳，要么触发修订。这在语法检查之上增加了一层语义评估。

一致性测试： Willison 提倡构建一致性测试套件（conformance suite）——与语言无关的测试（通常基于 YAML），任何实现都必须通过。这些测试充当契约：如果你在构建 API，一致性测试套件指定了预期的输入/输出，智能体的代码必须满足所有情况。这比临时写的单元测试更严格，因为它直接从规格派生，可以跨实现复用。在你规格的成功标准中加入一致性要求（如"必须通过 conformance/api-tests.yaml 中的所有用例”）。

在规格中利用测试： 如果可能，把测试计划甚至实际测试纳入你的规格和提示词流程。在传统开发中，我们用 TDD 或写测试用例来澄清需求——跟 AI 一起也可以这么做。比如在规格的成功标准中写：“这些输入样本应该产出这些输出……“或"以下单元测试应该通过。“智能体可以被提示在脑中走一遍这些用例，或者如果有能力的话实际执行。Willison 指出，拥有健壮的测试套件就像给智能体开了超能力：测试失败时它们可以快速验证和迭代。在 AI 编码场景中，在规格里写几行测试伪代码或预期输出，可以引导智能体的实现。此外，你还可以在子智能体方案中使用专门的”测试智能体"，拿着规格的标准持续验证"编码智能体"的输出。

注入你的领域知识： 你的规格应该体现只有经验丰富的开发者或有上下文的人才知道的洞察。比如，如果你在构建一个电商智能体，而且你知道"商品"和"分类"是多对多关系，就明确说出来。（别指望 AI 能推断出来——它可能推断不出。）如果某个库出了名地坑多，提一下要避免的陷阱。本质上就是把你的"师傅指导"倒进规格里。规格可以包含这样的建议：“如果使用库 X，注意版本 Y 中的内存泄漏问题（应用变通方案 Z）。“这种细节程度是把平庸的 AI 输出变成真正健壮方案的关键，因为你帮 AI 避开了常见的坑。

同样，如果你有偏好或风格规范（比如"在 React 中用函数组件而不用类组件”），编入规格。AI 就会模仿你的风格。很多工程师甚至在规格中包含小示例（比如"所有 API 响应应为 JSON，错误格式如 {"error": "message"}"）。通过给出一个简短的示例，你就把 AI 锚定到了你想要的确切格式上。

简单任务用精简规格： 虽然我们提倡详尽的规格，但专业的一部分就是知道何时保持简单。对于相对简单、独立的任务，过于繁重的规格反而可能帮倒忙。如果你让智能体做一件直截了当的事（比如"把一个 div 居中”），你可能只需说"保持方案简洁，不要添加多余的标记或样式"就够了，不需要一份完整的 PRD。反过来，对于复杂任务（比如"实现带 token 刷新和错误处理的 OAuth 流程”），那就该端出详细规格了。经验法则：根据任务复杂度调整规格的详细程度。不要对难题欠规格（智能体会手足无措或跑偏），也不要对简单题过度规格（智能体可能在不必要的指令中打结）。

必要时维持 AI 的"人设”： 有时规格的一部分是定义智能体应该如何表现或回应，特别是当智能体跟用户交互时。比如，如果构建一个客服智能体，你的规格可能包含"使用友好且专业的语调"和"如果不知道答案，请求澄清或提议跟进，而不是猜测"这类指引。这些规则（通常放在系统提示词中）帮助让 AI 的输出符合预期。它们本质上是对 AI 行为的规格项。在长会话中保持一致并在需要时提醒模型。（LLM 如果不加约束，在长会话中的风格会"漂移”。）

你始终是在场的决策者： 规格赋能了智能体，但你仍然是最终的质量把关人。如果智能体产出的东西技术上满足规格但感觉不对，相信你的判断。要么完善规格，要么直接调整输出。AI 智能体的好处是它们不会生气——如果输出偏了，你可以说"其实不是我想要的，让我们澄清规格重新来”。规格是你和 AI 协作的"活产出物”，不是不可更改的一次性合同。

Simon Willison 幽默地把跟 AI 智能体合作比作"一种非常奇怪的管理形式”，甚至说"从编码智能体中获得好的结果，感觉跟管理一个人类实习生不适地相似"。你需要提供清晰的指令（规格）、确保它们有必要的上下文（规格和相关数据）、给出可操作的反馈。规格搭好台，但执行过程中的监督和反馈才是关键。如果 AI 是一个"只要有机会就绝对会走捷径的奇怪数字实习生”，那你写的规格和约束就是防止走捷径、让它保持正轨的手段。

回报是什么： 一份好的规格不仅告诉 AI 要构建什么，还帮助它自我纠正并留在安全边界内。通过内置验证步骤、约束和你来之不易的知识，你大幅提高了智能体输出一次就对（或至少接近正确）的概率。这减少了迭代次数和那些"它到底为什么要这么干？“的时刻。

5. 测试、迭代、演进规格（并用对工具）

把写规格和构建智能体当作一个迭代循环：尽早测试、收集反馈、完善规格，并利用工具来自动化检查。

初始规格不是终点——而是一个循环的起点。最好的结果来自于你持续对照规格验证智能体的工作并相应调整。此外，现代 AI 开发者使用各种工具来支持这个过程（从 CI 流水线到上下文管理工具）。

持续测试： 不要等到最后才看智能体是否满足了规格。在每个重要里程碑甚至每个函数完成后，运行测试或至少做快速的手动检查。如果有什么不对，在继续推进之前更新规格或提示词。比如，如果规格要求"密码必须用 bcrypt 哈希"而你看到智能体的代码在存储明文，立即停下来纠正（并在规格或提示词中强化这条规则）。自动化测试在这里大放异彩：如果你提供了测试（或边做边写），让智能体运行它们。在很多编码智能体方案中，你可以让智能体在完成任务后运行 npm test 之类的命令。结果（失败信息）可以回馈到下一个提示词，相当于告诉智能体"你的输出在 X、Y、Z 方面没达到规格——修复它。“这种智能体循环（写代码 > 测试 > 修复 > 重复）非常强大，也是 Claude Code 或 Copilot Labs 等工具正在演进的方向。始终定义"完成"的标准（通过测试或标准），然后检查。

迭代规格本身： 如果你发现规格不完整或不清楚（也许智能体误解了什么，或者你意识到漏了一个需求），更新规格文档。然后明确让智能体与新规格同步：“我已按如下方式更新了规格……根据更新后的规格，调整计划或重构代码。“这样规格始终是唯一权威来源。这跟我们在正常开发中处理需求变更类似，只不过你同时也是 AI 智能体的产品经理。如果可能，保留版本历史（哪怕只是通过提交信息或笔记），这样你知道什么变了、为什么变。

利用上下文管理和记忆工具： 有一个不断壮大的工具生态系统来帮助管理 AI 智能体的上下文和知识。比如，检索增强生成（RAG）是一种模式，智能体可以按需从知识库（如向量数据库）中拉取相关数据片段。如果你的规格很大，你可以将其各章节做向量嵌入，让智能体在需要时检索最相关的部分，而不是每次都提供全文。还有实现了模型上下文协议（MCP）的框架，可以根据当前任务自动喂给模型正确的上下文。一个例子是 Context7（context7.com），它可以根据你正在做的事自动从文档中获取相关上下文片段。实际来说，智能体可能注意到你在做"支付处理”，然后自动把你规格或文档中的支付章节拉入提示词。考虑利用这类工具，或搭建一个简易版（哪怕只是在规格文档中做简单搜索）。

谨慎地并行化： 一些开发者在不同任务上同时运行多个智能体实例（前面提到的子智能体方案）。这可以加速开发（比如一个智能体生成代码，另一个同时写测试，或者两个功能并行构建）。如果你走这条路，确保任务确实独立或界限清晰，以避免冲突。（规格应该标注任何依赖关系。）比如，不要让两个智能体同时写同一个文件。一种工作流是让一个智能体生成代码，另一个并行审查，或者各自构建独立组件以后再集成。这是高级用法，管理起来精神上挺累的。（正如 Willison 承认的，运行多个智能体”出奇地有效，尽管在精神上很累"！）开始时最多用 2-3 个智能体，保持可控。

版本控制和规格锁定： 使用 Git 或你选择的版本控制工具来跟踪智能体做了什么。良好的版本控制习惯在 AI 辅助开发中更加重要。把规格文件本身也提交到仓库。这不仅保留了历史，智能体甚至可以用 git diff 或 blame 来理解变更。（LLM 读 diff 确实很能干。）一些高级的智能体方案让智能体查询版本控制历史来了解某些东西是什么时候引入的——令人惊讶的是，模型在 Git 操作上"相当给力”。通过把规格放在仓库中，你让自己和 AI 都能跟踪规格的演进。有些工具（如前面提到的 GitHub Spec Kit）将规格驱动开发集成到 Git 工作流中——比如在更新规格后才允许合并，或从规格项自动生成检查清单。虽然没有这些工具你也能成功，但关键是：像对待代码一样对待规格，用心维护。

成本和速度考量： 使用大模型和长上下文可能又慢又贵。一个实用的技巧是聪明地选择模型和做批处理。也许用更便宜/更快的模型做初稿或重复性工作，把最强（也最贵）的模型留给最终输出或复杂推理。一些开发者用 GPT-4 或 Claude 做规划和关键步骤，但把简单的扩展或重构卸载给本地模型或更小的 API 模型。如果用多智能体，也许不是所有都需要顶级模型；跑测试的智能体或 lint 智能体可以用小模型。同时考虑控制上下文大小：如果 5K token 够用就不要喂 20K。正如我们讨论的，更多 token 可能意味着递减的回报。

监控和记录一切： 在复杂的智能体工作流中，记录智能体的操作和输出是必不可少的。检查日志看智能体是否偏离或遇到错误。很多框架提供跟踪日志或允许打印智能体的思考链（特别是如果你提示它逐步思考）。审查这些日志可以揭示规格或指令在哪里被误解了。这跟调试程序没什么区别——只是"程序"变成了对话/提示词链。如果出了什么怪事，回到规格/指令中看看是否有歧义。

学习和改进： 最后，把每个项目当作提升规格写作能力的学习机会。也许你会发现某种措辞总是让 AI 犯迷糊，或者以某种方式组织规格章节能获得更好的遵循效果。把这些教训融入下一份规格。AI 智能体领域发展飞速，新的最佳实践（和工具）不断涌现。通过博客保持更新（比如 Simon Willison、Andrej Karpathy 等人的博客），不要犹豫去实验。

给 AI 智能体写规格不是"一劳永逸"的事。它是"指导、验证、改进"持续循环的一部分。这种勤勉的回报是实实在在的：通过尽早发现问题并让智能体保持对齐，你避免了以后昂贵的重写或失败。正如一位 AI 工程师俏皮地说的，用这些实践感觉就像有"一支实习生大军"为你工作，但你得管好他们。一份持续维护的好规格，就是你的管理工具。

避免常见陷阱

收尾之前，值得点出一些即使出发点很好的规格驱动工作流也可能被搞砸的反面模式。GitHub 对 2500+ 智能体文件的研究揭示了一个鲜明的分界：“大多数智能体文件失败的原因是太模糊了。“以下是要避免的错误：

模糊的提示词： “给我做个酷的东西"或"让它更好"等于什么都没给。正如 Baptiste Studer 所说：“模糊的提示词等于错误的结果。“要明确输入、输出和约束。“你是一个有用的编码助手"不行。“你是一个为 React 组件写测试的测试工程师，遵循这些示例，绝不修改源代码"才行。

没有摘要的超长上下文： 把 50 页文档丢进提示词然后祈祷模型能搞定，几乎不会成功。使用层次化摘要（如原则 3 所讨论的）或 RAG 来只呈现相关内容。上下文长度不能替代上下文质量。

跳过人工审查： Willison 有个个人准则——“我不会提交我无法向别人解释的代码。“仅仅因为智能体产出的东西通过了测试，不代表它是正确的、安全的或可维护的。始终审查关键代码路径。“纸牌屋"的比喻适用于此：AI 生成的代码可能看起来坚实，但在你没测试到的边界情况下轰然倒塌。

把 vibe coding 和生产工程混为一谈： 用 AI 快速原型（“vibe coding”）做探索和临时项目很棒。但没有严格的规格、测试和审查就把代码推上生产，那可就自找麻烦了。我区分"vibe coding"和"AI 辅助工程”——后者需要本指南所描述的纪律。搞清楚你处于哪种模式。

忽视"致命三要素”： Willison 警告 AI 智能体有三个使其危险的特性：速度（它们工作得比你审查得快）、不确定性（同样的输入，不同的输出）和成本（鼓励在验证上走捷径）。你的规格和审查流程必须考虑这三个方面。不要让速度超过你验证的能力。

遗漏六大核心领域： 如果你的规格没有覆盖命令、测试、项目结构、代码风格、Git 工作流和边界，你很可能遗漏了智能体需要的东西。在交给智能体之前，用第 2 节的六领域检查清单做最后一次验证。

结论

为 AI 编码智能体写有效的规格，需要扎实的软件工程原则加上对 LLM 特性的适应。从清晰的目标出发，让 AI 帮忙扩展计划。像严肃的设计文档一样组织规格，覆盖六大核心领域，并将其集成到工具链中，让它成为可执行的产出物而不只是一堆文字。通过一次只喂一块拼图来保持智能体的专注（并考虑用摘要目录、子智能体或并行编排等巧妙策略来应对大型规格）。通过包含三级边界（始终做/先问再做/绝不做）、自检和一致性测试来预防陷阱——本质上，教 AI 如何不失败。把整个过程当作迭代：用测试和反馈来持续完善规格和代码。

遵循这些指南，你的 AI 智能体在面对大型上下文时就不太可能"崩溃"或跑偏到胡说八道。

祝规格写作愉快！

本文翻译自 How to Write a Good Spec for AI Agents，仅供学习参考。