How to write a good spec for AI agents
APIHug Protocol：基于Protobuf的合约优先开发框架 - FYR
撰写优秀 AI 代理规范指南
TL;DR：目标是制定一份清晰的规范，涵盖足够的细节（可能包括结构、风格、测试、边界），以引导 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 规范工具包文档 所述，提供你正在构建的内容及其原因的高层描述，让编码代理生成一份专注于用户体验和成功标准的详细规范。从这种大局观出发，可以防止代理在后续编码时只见树木不见森林。
2. 像专业的 PRD（或 SRS）一样构建规范
将你的 AI 规范视为一份结构化文档（PRD），包含清晰的章节，而不是一堆松散的笔记。
许多开发者对待代理的规范就像对待传统的产品需求文档（PRD）或系统设计文档一样——全面、组织良好，并且易于“字面思维”的 AI 解析。这种正式的方法为代理提供了可遵循的蓝图，并减少了歧义。
六大核心领域： GitHub 对超过 2,500 个代理配置文件的分析揭示了一个清晰的模式：最有效的规范涵盖了六个领域。将其作为完整性的检查清单：
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, 提交前必须通过)
- Lint: `npm run lint --fix` (自动修复 ESLint 错误)
## 项目结构
- `src/` – 应用程序源代码
- `tests/` – 单元和集成测试
- `docs/` – 文档
## 边界
- ✅ 始终: 提交前运行测试, 遵循命名约定
- ⚠️ 先询问: 数据库模式更改, 添加依赖项
- 🚫 绝不: 提交机密信息, 编辑 node_modules/, 修改 CI 配置
这种级别的组织不仅有助于你清晰思考，也有助于 AI 查找信息。Anthropic 的工程师建议将提示组织成不同的部分（如 <background>、<instructions>、<tools>、<output_format> 等），原因正是如此——它为模型提供了关于哪些信息属于哪一类的强烈线索。并且记住，“精简并不一定意味着简短”——如果细节很重要，不要在规范中回避，但要保持聚焦。
将规范集成到你的工具链中： 将规范视为与版本控制和 CI/CD 绑定的“可执行产物”。GitHub 规范工具包使用一个四阶段、门控的工作流，使你的规范成为工程流程的核心。与其编写规范后将其搁置一旁，不如让规范驱动实现、清单和任务分解。你的主要角色是引导；编码代理则完成大部分编写工作。每个阶段都有特定的任务，在当前任务完全验证之前，你不会进入下一个阶段。
1. 规范（Specify）： 你提供所构建内容及其原因的高层描述，编码代理生成详细规范。这并非关于技术栈或应用设计，而是关于用户旅程、体验以及成功的标准。谁将使用它？它解决了什么问题？他们将如何与之交互？将其视为绘制你想要创建的用户体验地图，并让编码代理充实细节。这将成为一个随着你了解更多信息而演变的活产物。
2. 计划（Plan）： 现在进入技术层面。你提供所需的技术栈、架构和约束，编码代理生成全面的技术计划。如果你的公司对某些技术有标准化要求，就在这里说明。如果你要集成遗留系统或有合规要求，所有这些都要放在这里。你可以要求提供多个计划变体以比较方法。如果你提供内部文档，代理可以直接将你的架构模式整合到计划中。
3. 任务（Tasks）： 编码代理根据规范和计划将其分解为实际工作——小的、可审查的块，每个块都解决一个特定的问题。每个任务都应该是你可以独立实现和测试的内容，几乎就像为你的 AI 代理进行测试驱动开发。与其说“构建身份验证”，不如得到像“创建一个验证电子邮件格式的用户注册端点”这样的具体任务。
4. 实现（Implement）： 你的编码代理逐个（或并行）处理任务。你无需审查数千行的代码转储，而是审查解决特定问题的聚焦变更。代理知道要构建什么（规范）、如何构建（计划）以及要处理什么（任务）。至关重要的是，你的角色是在每个阶段进行验证：规范是否捕捉到了你想要的内容？计划是否考虑了约束？AI 是否遗漏了边缘情况？该流程内置了检查点，让你在继续前进之前进行批评、发现差距并及时纠正。
这种门控工作流可以防止 Willison 所说的“纸牌屋代码”——在审查下崩溃的脆弱 AI 输出。Anthropic 的技能系统提供了类似的模式，允许你定义基于 Markdown 的可重用行为，供代理调用。通过将你的规范嵌入这些工作流，你可以确保代理在规范得到验证之前无法继续，并且变更会自动传播到任务分解和测试中。
为专用角色考虑 agents.md： 对于 GitHub Copilot 等工具，你可以创建 agents.md 文件，定义专用的代理角色——用于技术写作的 @docs-agent、用于 QA 的 @test-agent、用于代码审查的 @security-agent。每个文件都充当该角色行为、命令和边界的聚焦规范。当你希望为不同任务使用不同的代理，而不是一个通用助手时，这尤其有用。
为代理体验（AX）而设计： 正如我们为开发者体验（DX）设计 API 一样，考虑为“代理体验”设计规范。这意味着干净、可解析的格式：代理将使用的任何 API 的 OpenAPI 模式、为 LLM 消费而汇总文档的 llms.txt 文件以及显式类型定义。代理 AI 基金会（AAIF）正在标准化 MCP（模型上下文协议）等工具集成协议——遵循这些模式的规范更容易被代理可靠地消费和操作。
PRD 与 SRS 思维模式： 借鉴既定的文档实践会有所帮助。对于 AI 代理规范，你通常会将两者融合成一份文档（如上所示），但涵盖两个角度对你很有帮助。像写 PRD 一样写，确保包含以用户为中心的上下文（“每个功能背后的原因”），这样 AI 就不会为错误的事情优化。像写 SRS 一样扩展，确保你敲定 AI 实际生成正确代码所需的细节（比如使用什么数据库或 API）。开发者发现，这种额外的前期努力通过大幅减少后期与代理的沟通失误而获得了回报。
让规范成为一份“活文档”： 不要写完就忘。随着你和代理做出决策或发现新信息，请更新规范。如果 AI 不得不更改数据模型，或者你决定削减某个功能，请在规范中反映出来，使其保持为事实依据。将其视为版本控制的文档。在规范驱动的工作流中，规范驱动实现、测试和任务分解，并且在规范得到验证之前，你不会进入编码阶段。这个习惯能保持项目的连贯性，特别是当你或代理离开后又回来时。记住，规范不仅仅是为了 AI——它还能帮助你作为开发者保持监督，确保 AI 的工作满足真实需求。
3. 将任务分解为模块化的提示和上下文，而非一个庞大的提示
分而治之：一次只给 AI 一个聚焦的任务，而不是一个包含所有内容的单一庞大提示。
有经验的 AI 工程师已经了解到，试图将整个项目（所有需求、所有代码、所有指令）塞进一个提示或代理消息中，只会导致混乱。你不仅有触及令牌限制的风险，还可能因“指令诅咒”而导致模型失去焦点——过多的指令会导致它无法很好地遵循其中任何一个。解决方案是以模块化的方式设计你的规范和工作流，一次只处理一个部分，并仅为该部分拉取所需的上下文。
太多上下文/指令的诅咒： 研究证实了许多开发者凭经验看到的现象：当你在提示中堆砌越来越多的指令或数据时，模型在遵守每一项指令方面的表现显著下降。一项研究将此称为“指令诅咒”，表明即使是 GPT-4 和 Claude 在被要求同时满足多项要求时也会挣扎。在实践中，如果你列出 10 个详细规则的要点，AI 可能会遵守前几个，然后开始忽略其他规则。更好的策略是迭代聚焦。行业指南建议将复杂需求分解为顺序的、简单的指令作为最佳实践。一次只让 AI 专注于一个子问题，完成后再继续下一个。这能保持高质量并使错误易于管理。
将规范划分为阶段或组件： 如果你的规范文档非常长或涵盖大量内容，请考虑将其拆分为多个部分（物理上分离的文件或清晰分离的章节）。例如，你可能有一个“后端 API 规范”部分和另一个“前端 UI 规范”部分。当代理在后端工作时，你不需要总是提供前端规范，反之亦然。许多使用多代理设置的开发者甚至为每个部分创建单独的代理或子进程——例如，一个代理处理数据库/模式，另一个处理 API 逻辑，另一个处理前端——每个代理都拥有规范的相关切片。即使你使用单个代理，也可以通过仅将相关规范部分复制到该任务的提示中来模拟这一点。避免上下文过载：正如 DigitalOcean AI 指南所警告的那样，不要在一个操作中混合身份验证任务和数据库模式更改。让每个提示都紧密围绕当前目标。
大型规范的扩展目录 / 摘要： 一种巧妙的技术是让代理为规范构建一个扩展的目录，并附带摘要。这本质上是一个“规范摘要”，将每个部分浓缩为几个关键点或关键词，并引用可以在哪里找到详细信息。例如，如果你的完整规范有一个跨越 500 字的“安全要求”部分，你可能会让代理将其总结为：“安全：使用 HTTPS，保护 API 密钥，实施输入验证（参见完整规范 §4.2）”。通过在规划阶段创建这种分层摘要，你就能获得一个可以保留在提示中的鸟瞰图，而精细细节则在需要时才加载。这个扩展的目录充当索引：代理可以查阅它并说“啊哈，有一个安全部分我应该看一下”，然后你可以按需提供该部分。这类似于人类开发者浏览大纲，然后在处理特定部分时翻到规范文档的相关页面。
要实现这一点，你可以在编写规范后提示代理：“将上述规范总结成一个非常简洁的提纲，包含每个部分的关键点和参考标签。” 结果可能是一个带有单句或两句摘要的章节列表。该摘要可以保留在系统或助手消息中，以在不消耗太多令牌的情况下引导代理的注意力。这种分层摘要方法已知有助于 LLM 通过关注高层结构来维持长期上下文。代理会携带规范的“心理地图”。
利用子代理或“技能”处理规范的不同部分： 另一种高级方法是使用多个专业代理（Anthropic 称之为子代理，或者你可能称之为“技能”）。每个子代理都为其特定领域的专业知识进行配置，并获得与该领域相关的规范部分。例如，你可能有一个数据库设计器子代理，它只知道规范的数据模型部分，以及一个 API 编码器子代理，它知道 API 端点规范。主代理（或协调器）可以自动将任务路由到适当的子代理。其好处是每个代理要处理的上下文窗口更小，角色更专注，这可以提高准确性并允许对独立任务进行并行工作。Anthropic 的 Claude Code 通过允许你为子代理定义自己的系统提示和工具来支持这一点。“每个子代理都有特定的目的和专业领域，使用与主对话分开的自己的上下文窗口，并有一个自定义系统提示指导其行为，”正如其文档所述。当出现与子代理领域匹配的任务时，Claude 可以将该任务委托给它，子代理会独立返回结果。
并行代理以提高吞吐量： 同时运行多个代理正成为“开发者生产力的下一个大趋势”。与其等待一个代理完成后再启动另一个任务，不如为不重叠的工作同时启动并行代理。Willison 将其描述为“拥抱并行编码代理”，并指出它“出奇地有效，尽管在精神上令人疲惫”。关键是划定任务范围，以免代理相互干扰——一个代理编写功能，另一个编写测试，或者并发构建独立的组件。LangGraph 或 OpenAI Swarm 等编排框架可以帮助协调这些代理，而通过向量数据库（如 Chroma）共享内存可以让它们在没有冗余提示的情况下访问公共上下文。
单代理 vs. 多代理：何时使用
| 方面 | 单代理 | 并行/多代理 |
|---|---|---|
| 优势 | 设置更简单；开销更低；更易于调试和跟踪 | 吞吐量更高；处理复杂的相互依赖关系；每个领域都有专家 |
| 挑战 | 大型项目上的上下文过载；迭代较慢；单点故障 | 协调开销；潜在冲突；需要共享内存（例如，向量数据库） |
| 最适合 | 独立模块；中小型项目；早期原型设计 | 大型代码库；一个编码 + 一个测试 + 一个审查；独立功能 |
| 技巧 | 使用规范摘要；每次任务刷新上下文；经常开始新会话 | 最初限制为 2-3 个代理；使用 MCP 进行工具共享；明确定义边界 |
在实践中，使用子代理或特定于技能的提示可能看起来像这样：你维护多个规范文件（或提示模板）——例如 SPEC_backend.md、SPEC_frontend.md——然后你告诉 AI，“对于后端任务，请参考 SPEC_backend；对于前端任务，请参考 SPEC_frontend。” 或者在 Cursor/Claude 等工具中，你实际上为每个任务启动一个子代理。这当然比单代理循环更复杂，但它模仿了人类开发者所做的——我们在心理上将大型规范分解为相关块（你不会一次把 50 页的规范全部记在脑子里；你会回忆起手头任务所需的部分，并对整体架构有大致的了解）。正如所指出的，挑战在于管理相互依赖关系：子代理仍必须协调（前端需要知道来自后端规范的 API 合约等）。一个中央概览（或一个“架构师”代理）可以通过引用子规范并确保一致性来提供帮助。
让每个提示专注于一个任务/部分： 即使没有花哨的多代理设置，你也可以手动强制执行模块化。例如，在规范写好之后，你的下一步可能是：“步骤 1：实现数据库模式。” 你只向代理提供规范的数据库部分，以及规范中的任何全局约束（如技术栈）。代理就此展开工作。然后对于步骤 2，“现在实现身份验证功能”，你提供规范的身份验证部分，如果需要，可能还会提供相关的模式部分。通过为每个主要任务刷新上下文，你可以确保模型不会携带大量陈旧或无关的信息，这些信息可能会分散它的注意力。正如一份指南所建议的：“重新开始：在切换主要功能时开始新会话以清除上下文”。你始终可以提醒代理每个关键的全局规则（来自规范的约束部分），但如果并非全部都需要，就不要塞入整个规范。
使用内联指令和代码 TODO： 另一种模块化技巧是将你的代码或规范作为对话的活跃部分。例如，用 // TODO 注释搭建你的代码，描述需要完成的内容，并让代理逐一填充它们。每个 TODO 本质上都是一个小任务的微型规范。这能让 AI 保持高度聚焦（“根据此规范片段实现此特定功能”），并且你可以在一个紧密的循环中进行迭代。这类似于给 AI 一个待办事项清单中的单项来完成，而不是一次性给出整个清单。
底线是：小而聚焦的上下文胜过一个巨大的提示。这能提高质量，并防止 AI 因一次处理太多内容而“不堪重负”。正如一套最佳实践所总结的那样，向模型提供“单一任务焦点”和“仅相关信息”，并避免到处倾倒所有内容。通过将工作构建成模块——并使用规范摘要或子规范代理等策略——你将绕过上下文大小限制和 AI 的短期记忆容量。记住，喂养得好的 AI 就像喂养得好的函数：只给它手头工作所需的输入。
4. 内置自检、约束和人类专业知识
让你的规范不仅是给代理的待办事项清单，也是质量控制指南——并且不要害怕注入你自己的专业知识。
一份优秀的 AI 代理规范会预见到 AI 可能出错的地方，并设置防护栏。它还利用了你所知道的知识（领域知识、边缘情况、“陷阱”），这样 AI 就不会在真空中操作。将规范视为 AI 的教练和裁判：它应该鼓励正确的方法并指出犯规行为。
使用三层边界： GitHub 对 2,500 多个代理文件的分析发现，最有效的规范使用三层边界系统，而不是简单的禁止列表。这为代理提供了更清晰的指导，告诉它何时继续、何时暂停以及何时停止：
✅ 始终执行： 代理无需询问即可采取的行动。“提交前始终运行测试。”“始终遵循风格指南中的命名约定。”“始终将错误记录到监控服务。”
⚠️ 先询问： 需要人工批准的行动。“修改数据库模式前先询问。”“添加新依赖项前先询问。”“更改 CI/CD 配置前先询问。”这一层捕捉了那些可能没问题但值得人工检查的高影响力变更。
🚫 绝不执行： 硬性停止。“绝不提交机密信息或 API 密钥。”“绝不编辑 node_modules/ 或 vendor/。”“未经明确批准，绝不移除失败的测试。”“绝不提交机密信息”是该研究中最常见的有用约束。
这种三层方法比简单的规则列表更细致入微。它承认有些行动总是安全的，有些需要监督，有些则是绝对禁止的。代理可以自信地在“始终”事项上继续，为“先询问”事项标记审查，并在“绝不”事项上硬性停止。
鼓励自我验证： 一种强大的模式是让代理根据规范自动验证其工作。如果你的工具允许，你可以集成单元测试或 linting 等检查，AI 可以在生成代码后运行。但即使在规范/提示层面，你也可以指示 AI 进行双重检查：例如，“实现后，将结果与规范进行比较，并确认所有要求都已满足。列出任何未解决的规范项。”这促使 LLM 将其输出与规范进行反思，从而发现遗漏。这是内置到流程中的一种自审形式。
例如，你可能会在提示末尾附加：“（编写完函数后，请回顾上述要求列表，并确保每项都已满足，标记任何缺失的项。）”模型随后（理想情况下）会输出代码，然后附上一个简短的清单，表明它是否满足了每项要求。这减少了在你运行测试之前它就忘记某些内容的机会。虽然并非万无一失，但确实有帮助。
将 LLM 作为主观检查的评判者： 对于难以自动测试的标准——代码风格、可读性、对架构模式的遵循——考虑使用“LLM 作为评判者”。这意味着让第二个代理（或一个单独的提示）根据你的规范质量指南审查第一个代理的输出。Anthropic 等公司发现这对主观评估很有效。你可能会提示：“根据我们的风格指南审查此代码。标记任何违规行为。”评判者代理返回的反馈要么被采纳，要么触发修订。这增加了一层语义评估，超越了语法检查。
一致性测试： Willison 主张构建一致性套件——与语言无关的测试（通常是基于 YAML 的），任何实现都必须通过。这些测试充当一种契约：如果你正在构建一个 API，一致性套件会指定预期的输入/输出，代理的代码必须满足所有情况。这比临时的单元测试更严格，因为它直接从规范派生，并且可以在不同实现之间重用。在规范的成功部分包含一致性标准（例如，“必须通过 conformance/api-tests.yaml 中的所有案例”）。
在规范中利用测试： 如果可能，在你的规范和提示流程中加入测试计划，甚至是实际的测试。在传统开发中，我们使用 TDD 或编写测试用例来澄清需求——你也可以对 AI 做同样的事情。例如，在规范的成功标准中，你可能会说“这些示例输入应该产生这些输出……”或“以下单元测试应该通过。”如果代理有能力，可以提示它在脑海中运行这些案例，或者实际执行它们。Simon Willison 指出，拥有一个健壮的测试套件就像赋予代理超能力——当测试失败时，它们可以快速验证和迭代。在 AI 编码环境中，在规范中为测试或预期结果编写一些伪代码可以指导代理的实现。此外，你可以在子代理设置中使用一个专门的“测试代理”，它接收规范的标准并持续验证“代码代理”的输出。
发挥你的领域知识： 你的规范应反映只有经验丰富的开发者或有上下文的人才知道的见解。例如，如果你正在构建一个电子商务代理，并且你知道“产品”和“类别”是多对多关系，请明确说明（不要假设 AI 会推断出来——它可能不会）。如果某个库特别棘手，请提及要避免的陷阱。本质上，将你的指导融入规范中。规范可以包含这样的建议：“如果使用库 X，请注意 Y 版本中的内存泄漏问题（应用变通方案 Z）。”这种细节水平能将普通的 AI 输出转变为真正稳健的解决方案，因为你已经引导 AI 避开了常见陷阱。
此外，如果你有偏好或风格指南（比如，“在 React 中使用函数组件而非类组件”），请在规范中编码。AI 随后会模仿你的风格。许多工程师甚至在规范中包含小例子，例如，“所有 API 响应都应为 JSON。例如，错误时为 {“error”: “message”}。”通过给出一个快速示例，你就能将 AI 锚定到你想要的确切格式上。
简单任务的极简主义： 虽然我们提倡详尽的规范，但专业知识的一部分在于知道何时保持简单。对于相对简单、孤立的任务，过于繁重的规范实际上会造成更多混淆而非帮助。如果你要求代理做一些简单的事情（比如“将一个 div 居中在页面上”），你可能只需说，“确保解决方案简洁，不要添加多余的标记或样式。”对于这种任务，不需要完整的 PRD。相反，对于复杂任务（比如“使用令牌刷新和错误处理实现 OAuth 流程”），这才是你需要拿出详细规范的时候。一个好的经验法则是：根据任务复杂度调整规范细节。不要对难题规范不足（代理会不知所措或偏离轨道），但也不要对琐碎任务过度规范（代理可能会被缠住或在不必要的指令上浪费上下文）。
如有需要，保持 AI 的“角色”： 有时，你的规范的一部分是定义代理应该如何行为或回应，特别是当代理与用户交互时。例如，如果构建一个客户支持代理，你的规范可能包括这样的指南：“使用友好而专业的语气”，“如果你不知道答案，请要求澄清或主动跟进，而不是猜测。”这类规则（通常包含在系统提示中）有助于使 AI 的输出符合期望。它们本质上是 AI 行为的规范项。保持它们的一致性，并在长时间会话中必要时提醒模型（LLM 随着时间的推移可能会“漂移”风格，如果不加以约束的话）。
你仍然是环路中的执行者： 规范赋予了代理能力，但你仍然是最终的质量过滤器。如果代理产生的东西在技术上满足了规范，但感觉不对，请相信你的判断。要么完善规范，要么直接调整输出。与 AI 代理合作的好处在于它们不会生气——如果它们交付的设计偏离了，你可以说，“实际上，那不是我的本意，让我们澄清一下规范并重做。”规范是你与 AI 协作的活产物，而不是一份你无法更改的一次性合同。
Simon Willison 幽默地将与 AI 代理的合作比作“一种非常奇怪的管理形式”，甚至“让编码代理取得好结果的感觉 uncomfortably close to managing a human intern”。你需要提供清晰的指示（规范），确保他们拥有必要的上下文（规范和相关数据），并给予可操作的反馈。规范设定了舞台，但在执行过程中的监控和反馈是关键。如果 AI 是一个“如果你给它机会就绝对会作弊的奇怪数字实习生”，那么你编写的规范和约束就是你防止它作弊并使其保持正轨的方式。
这就是回报：一份好的规范不仅告诉 AI 要构建什么，还能帮助它自我纠正并保持在安全边界内。通过内置验证步骤、约束和你来之不易的知识，你大大增加了代理输出第一次就正确的可能性（或者至少更接近正确）。这减少了迭代次数和那些“它到底为什么会那样做？”的时刻。
5. 测试、迭代并演进规范（并使用合适的工具）
将规范编写和代理构建视为一个迭代循环：尽早测试，收集反馈，完善规范，并利用工具自动化检查。
初始规范不是终点——而是循环的起点。当你持续根据规范验证代理的工作并相应调整时，才能获得最佳结果。此外，现代 AI 开发者使用各种工具来支持这一过程（从 CI 管道到上下文管理实用程序）。
持续测试： 不要等到最后才看代理是否满足了规范。在每个主要里程碑之后，甚至在每个函数之后，都要运行测试或至少进行快速手动检查。如果出现问题，请在继续之前更新规范或提示。例如，如果规范说“密码必须使用 bcrypt 进行哈希”，而你看到代理的代码存储的是明文——立即停止并纠正它（并提醒规范或提示中的规则）。自动化测试在这里大放异彩：如果你提供了测试（或在进行过程中编写），就让代理运行它们。在许多编码代理设置中，你可以在任务完成后让代理运行 npm test 或类似命令。结果（失败）可以反馈到下一个提示中，有效地告诉代理“你的输出在 X、Y、Z 方面未达到规范——修复它。”这种代理循环（代码 -> 测试 -> 修复 -> 重复）非常强大，也是 Claude Code 或 Copilot Labs 等工具不断发展以处理更大任务的方式。始终定义“完成”的含义（通过测试或标准）并进行检查。
迭代规范本身： 如果你发现规范不完整或不清晰（可能是代理误解了某些内容，或者你意识到自己遗漏了需求），请更新规范文档。然后明确地与代理重新同步新规范：“我已经按如下方式更新了规范……鉴于更新后的规范，请相应地调整计划或重构代码。”这样，规范就保持为单一事实来源。这类似于我们在正常开发中如何处理需求变更——但在这里，你也是你 AI 代理的产品经理。如果可能，请保留版本历史（即使是通过提交消息或笔记），这样你就知道什么发生了变化以及为什么。
利用上下文管理和记忆工具： 有一个不断增长的工具生态系统，旨在帮助管理 AI 代理的上下文和知识。例如，检索增强生成（RAG）是一种模式，代理可以根据需要从知识库（如向量数据库）中即时拉取相关的数据块。如果你的规范非常庞大，你可以嵌入其部分，并让代理在需要时检索最相关的部分，而不是总是提供全部内容。还有一些框架实现了模型上下文协议（MCP），它可以根据当前任务自动向模型提供正确的上下文。一个例子是 Context7 (context7.com)，它可以根据你正在处理的内容自动从文档中获取相关的上下文片段。在实践中，这可能意味着代理注意到你正在处理“支付处理”，然后它会将规范或文档的“支付”部分拉入提示中。考虑利用此类工具或设置一个基本版本（即使是在你的规范文档中
