拆解GitHub 2500个案例后：我们总结出编写AI Agent规范的“六大军规”
神译局是36氪旗下编译团队，关注科技、商业、职场、生活等领域，重点介绍国外的新技术、新观点、新风向。
编者按：别再给Agent塞长文档了！掌握这套“数字实习生”管理框架，是让AI从玩具进化为生产力的硬核关键。
目标是编写一份清晰的规范，涵盖恰到好处的细节（包括结构、风格、测试和边界），在引导 AI 的同时避免信息过载。将大任务拆解为小任务，而不是把所有内容都塞进一个庞大的提示词中。先在“只读模式”下进行规划，然后再执行并持续迭代。
“我听过很多关于如何为 AI Agent 编写优秀规范的建议，但始终没发现一套成熟的框架。我也能写出堪比 RFC（征求意见稿）的详尽规范，但一旦上下文过长，模型就会开始‘罢工’。”
许多开发者都有这种挫败感。粗暴地将一份冗长的规范丢给 AI Agent 是行不通的——上下文窗口的限制和模型的“注意力预算”会成为阻碍。关键在于编写“聪明”的规范：这些文档既能清晰地引导 Agent，又能保持在实际的上下文容量内，并随项目同步演进。本指南总结了我在使用 Claude Code 和 Gemini CLI 等开发 Agent 的过程中的最佳实践，提炼出一套规范编写框架，旨在让你的 AI Agent 保持专注且高效。
我们将介绍编写优秀 AI Agent 规范的五项原则，每项原则都以加粗的要点开头。
1. 从顶层愿景开始，让 AI 拟定细节
用一份简练的概要规范启动项目，把细节交给 AI。
与其预先就过度设计，不如从清晰的目标陈述和几个核心需求开始。把它看作是一份“产品简报”，让 Agent 据此生成更详尽的规范。这样可以发挥 AI 擅长补充细节的长处，同时让你掌控大方向。除非你从一开始就有必须满足的极特定技术需求，否则这种方法非常奏效。
其原理在于：基于大语言模型（LLM）的 Agent 在获得明确的概要指令后，非常擅长填充细节；但它们需要一个清晰的任务目标，以防跑偏。通过提供简短的提纲或目标描述，并要求 AI 生成完整的规范（比方说 `spec.md`），就为 Agent 建立了一个持久的参考标准。在与 Agent 协作时，预先规划尤为重要——你可以先迭代计划，然后再交给 Agent 去写代码。这份规范成了你与 AI 共同构建的第一个产物。
实操方法：开启一个新的编程会话并输入以下提示词：
“你是一名 AI 软件工程师。请为 [项目 X] 起草一份详细规范，涵盖目标、功能、约束条件以及分步实施计划。”
初始提示词应保持在高层级——比方说：“构建一个网页应用，让用户可以跟踪任务（待办事项列表），应用需具备用户账户、数据库和简单的 UI”。
Agent 可能会回复一份结构化的规范草案，包括：概述、功能列表、技术栈建议、数据模型等。随后，这份规范就成了你和 Agent 共同参考的“唯一事实来源”。GitHub 的 AI 团队极力推崇规范驱动开发（Spec-driven Development），即“规范成为共享的事实来源……是随项目进化的、活生生的、可执行的产物”。在编写任何代码之前，务必检查并完善 AI 生成的规范，确保它符合你的愿景，并纠正其中的幻觉或偏离目标的细节。
利用“计划模式”强制执行规划优先：像 Claude Code 这样的工具提供了“计划模式”（Plan Mode），将 Agent 限制在只读操作——它可以分析你的代码库并创建详细计划，但在你准备好之前不会编写任何代码。这非常适合规划阶段：在计划模式下启动，描述你想构建的内容，让 Agent 在探索现有代码的同时起草规范。要求它针对计划向你提问，以消除歧义。让它从架构、最佳实践、安全风险和测试策略等方面评审该计划。目标是精炼计划，直到没有任何误解的空间。只有到那时，你才退出计划模式并让 Agent 开始执行。这一工作流可以避免“在规范尚未定型前就匆忙生成代码”这一常见陷阱。
将规范作为上下文：一旦获得批准，将该规范保存下来（比方说存为 `SPEC.md`），并根据需要将相关章节提供给 Agent。许多使用强力模型的开发者正是这么做的——规范文件在不同会话间持久存在，每当项目复工时，它都能为 AI 提供支撑。这减轻了因对话历史过长或重启 Agent 时可能出现的“健忘”问题。这类似于团队中使用产品需求文档 (PRD)：它是每个人（人类或 AI）都可以查阅以保持步调一致的参考资料。正如一位工程师所观察到的，经验丰富的人往往“先写好文档，模型仅凭这些输入就可能构建出相匹配的实现”。这份规范就是那份文档。
保持目标导向：AI Agent 的概要规范应更多地关注“做什么”和“为什么”，而不是纠结于“怎么做”的琐碎细节（至少在初期如此）。可以把它想象成用户故事和验收标准：用户是谁？他们需要什么？成功的标准是什么？（比方说：“用户可以添加、编辑、完成任务；数据持久化保存；应用响应迅速且安全”）。这能让 AI 生成的详细规范立足于用户需求和结果，而不仅仅是技术待办事项。正如 GitHub Spec Kit 文档所言，提供关于构建内容及其原因的概要描述，让编程 Agent 生成专注于用户体验和成功标准的详细规范。从大局愿景出发，可以防止 Agent 在随后进入编码阶段时“只见树木不见森林”。
2. 像写专业的 PRD（或 SRS）一样构建规范
将你的 AI 规范视为一份结构化的文档 (PRD)，拥有清晰的章节，而不是一堆零散的笔记。
许多开发者对待 Agent 规范的方式与传统的产品需求文档 (PRD) 或系统设计文档非常相似——全面、组织良好且易于让“一根筋”的 AI 解析。这种正式的方法为 Agent 提供了一个可以遵循的蓝图，减少了歧义。
六大核心领域：GitHub 对超过 2500 个 Agent 配置文件进行的分析揭示了一个清晰的模式：最有效的规范涵盖了六个领域。请将其作为完整性检查清单：
命令： 将可执行命令放在前面——不仅是工具名称，还要带上参数的完整命令：`npm test`、`pytest -v`、`npm run build`。Agent 会频繁参考这些命令。
测试： 如何运行测试、使用什么框架、测试文件存放位置以及代码覆盖率期望。
项目结构： 源代码在哪里、测试在哪里、文档在哪里。要明确表述：“`src/` 存放应用代码，`tests/` 存放单元测试，`docs/` 存放文档。”
代码风格： 一段显示你风格的真实代码片段，胜过三段文字描述。包括命名规范、格式化规则和优秀输出示例。
Git 工作流： 分支命名、提交信息格式、PR 要求。只要你写清楚，Agent 就能照办。
边界： Agent 绝对不能碰的东西——密钥、第三方库目录、生产环境配置、特定文件夹。“严禁提交密钥”是 GitHub 研究中出现频率最高的有益约束。
明确你的技术栈：说“React 18 配合 TypeScript、Vite 和 Tailwind CSS”，而不是只说“React 项目”。包含版本号和核心依赖。模糊的规范会产生模糊的代码。
使用一致的格式：清晰至上。许多开发者在规范中使用 Markdown 标题甚至类似 XML 的标签来划分章节，因为 AI 模型处理结构化文本的能力优于随意散文。比方说，你可以这样构建规范：
# Project Spec: My team's tasks app
## Objective
* Build a web app for small teams to manage tasks...
## Tech Stack
* React 18+, TypeScript, Vite, Tailwind CSS
* Node.js/Express backend, PostgreSQL, Prisma ORM
## Commands
* Build: `npm run build` (compiles TypeScript, outputs to dist/)
* Test: `npm test` (runs Jest, must pass before commits)
* Lint: `npm run lint --fix` (auto-fixes ESLint errors)
## Project Structure
* `src/` – Application source code
* `tests/` – Unit and integration tests
* `docs/` – Documentation
## Boundaries
* ✅ Always: Run tests before commits, follow naming conventions
* ⚠️ Ask first: Database schema changes, adding dependencies
* 🚫 Never: Commit secrets, edit node_modules/, modify CI config
组织到这种程度不仅能帮你理清思路，还能帮 AI 快速定位信息。Anthropic 的工程师建议将提示词组织成不同的章节（如 `<background>`、`<instructions>`、`<tools>`、`<output_format>` 等），原因就在于：它能为模型提供强有力的线索，区分哪些信息是什么。请记住，“简约不代表简短”——如果某些细节很重要，不要害怕在规范中写得太细，只需保持聚焦即可。
将规范整合进你的工具链：将规范视为与版本控制和 CI/CD 绑定的“可执行产物”。GitHub Spec Kit 采用了一种四阶段的闸口式工作流，让规范成为工程流程的核心。与其写完规范就束之高阁，不如让它驱动实现、检查清单和任务分解。你的核心角色是掌舵；编程 Agent 则负责大部分的编写工作。每个阶段都有特定的任务，在当前任务完全验证之前，不要进入下一阶段：
确定规范 (Specify)： 你提供关于构建内容及其原因的概要描述，编程 Agent 生成详细规范。这不关乎技术栈或应用设计，而关乎用户旅程、体验以及成功的定义。谁会使用它？它解决了什么问题？用户如何与之交互？将其视为绘制你想要创造的用户体验蓝图，并让编程 Agent 充实细节。这会成为一个随认知深入而不断进化的动态产物。
制定计划 (Plan)： 现在进入技术层面。你提供期望的技术栈、架构和约束，以及生成全面技术计划的编程 Agent。如果你的公司对某些技术有标准化要求，就在这里说明。如果你要集成旧系统或有合规性要求，也全写在这里。你可以索要多份方案以对比不同方法。如果你提供了内部文档，Agent 甚至能将你的架构模式直接整合进计划中。
分解任务 (Tasks)： 编程 Agent 根据规范和计划将其拆解为实际工作——即细小、可评审的模块，每个模块解决一个特定的难题。每个任务都应该是可以独立实现并测试的，这几乎就像是为你 AI Agent 准备的测试驱动开发。得到的不再是“构建身份验证”这种模糊指令，而是“创建一个验证电子邮件格式的用户注册接口”这样具体的任务。
实施 (Implement)： 你的编程 Agent 逐一（或并行）处理任务。你无需再去评审数千行的代码堆，而是评审针对特定问题的专项更改。Agent 清楚构建什么（规范）、如何构建（计划）以及目前该做什么（任务）。关键在于，你的角色是分阶段验证：规范是否领会了你的意图？计划是否考虑了约束？AI 是否遗漏了边缘情况？该流程内置了多个检查点，让你在推进之前能够进行评价、寻找漏洞并校正方向。
这种闸口式的工作流防止了 Willison 所说的“纸牌屋代码”——即那些经不起推敲、脆弱的 AI 输出。Anthropic 的 Skills 系统也提供了类似的模式，允许你定义基于 Markdown 的可重用行为供 Agent 调用。通过将规范嵌入这些工作流，可以确保在规范通过验证之前 Agent 无法推进，且任何变更都会自动同步到任务分解和测试中。
考虑给特定角色创建 `agents.md`：对于像 GitHub Copilot 这样的工具，你可以创建 `agents.md` 文件来定义专业的 Agent 角色——比方说负责技术写作的 `@docs-agent`，负责质量保证的 `@test-agent`，负责代码评审的 `@security-agent`。每个文件都作为该角色的行为、命令和边界的专项规范。当你需要多个 Agent 各司其职，而不是一个什么都懂但样样不精的助手时，这非常有用。
为Agent 体验 (AX) 设计：就像我们设计API要考虑开发者体验 (DX) 一样，设计规范也要考虑“Agent 体验”。这意味着使用干净、可解析的格式：为 Agent 将调用的任何 API 提供 OpenAPI 模式，提供总结文档供 LLM 调用的 `llms.txt` 文件，以及明确的类型定义。Agentic AI Foundation (AAIF) 正在对像 MCP（模型上下文协议）这样的工具集成协议进行标准化——遵循这些模式的规范更易于被 Agent 理解并可靠地执行。
PRD vs SRS 心态：借鉴成熟的文档实践会很有帮助。对于 AI Agent 规范，你通常会将所有的东西融入到一份文档（如上所述），但兼顾这两个视角对你大有裨益。像写 PRD 那样去写，能确保包含以用户为中心的背景（“每个功能背后的原因”），这样 AI 就不会为了错误的目标进行优化。像 SRS 那样去扩展，能确保夯实 AI 实际生成正确代码所需的细节（比方说使用哪个数据库或 API）。开发者们发现，这种前期额外投入的回报是：大幅减少了后期与 Agent 的沟通误区。
让规范成为“活文档”：不要写完就扔。当你和 Agent 做出决定或发现新信息时，及时更新规范。如果 AI 必须更改数据模型，或者你决定删减某个功能，请在规范中体现出来，使其始终作为唯一事实来源。将其视为受版本控制的文档。在规范驱动的工作流中，规范驱动实现、测试和任务分解，在规范通过验证之前不会进入编码阶段。这种习惯能保持项目的一致性，特别是当你或 Agent 暂时离开后又回来继续工作时。记住，规范不只是给 AI 看的——它也能帮助你作为开发者保持全局把控，确保 AI 的工作符合真实需求。
3. 将任务拆解为模块化的提示词和上下文，而非单一庞大的提示词
分而治之：每次给 AI 一个专注的任务，而不是一个塞满所有内容的大一统提示词。
经验丰富的 AI 工程师深知，试图将整个项目（所有需求、代码、指令）塞进单个提示词或 Agent 消息中，简直就是混乱的温床。你不仅面临触及 token 限制的风险，还可能让模型因为“指令魔咒”而失去焦点——指令太多会导致它哪条都执行不好。解决方案是以模块化的方式设计规范和工作流，每次只攻克一个环节，并且只引入该环节所需的上下文。
信息/指令过载的魔咒：研究已经证实了许多开发者的直观感受：随着你往提示词里堆叠更多的指令或数据，模型对每一条指令的遵循性能会显著下降。一项研究将其称为“指令魔咒”，表明即便是 GPT-4 和 Claude，在被要求同时满足许多需求时也会感到吃力。在实际操作中，如果你列出 10 条详细规则，AI 可能会遵守前几条，然后开始忽略其余部分。更好的策略是迭代式聚焦。行业准则建议将复杂需求分解为一系列简单的指令，这是最佳实践。让 AI 每次专注于一个子问题，完成后再继续下一个。这能保持高质量，并使错误处于可控范围内。
将规范划分为阶段或组件：如果你的规范文档非常长或涵盖范围极广，考虑将其拆分成几个部分（可以是物理上独立的文件，也可以是逻辑上清晰的章节）。比方说，你可以设置一个“后端 API 规范”章节和另一个“前端 UI 规范”章节。当 AI 处理后端工作时，你不需要总是喂给它前端规范，反之亦然。许多使用多 Agent 架构的开发者甚至会为每个部分创建独立的 Agent 或子进程——比方说一个负责数据库/模式，一个负责 API 逻辑，一个负责前端——每个 Agent 只接收相关的规范切片。即便你只用了一个 Agent，也可以通过只把相关的规范章节复制到当前任务的提示词中来模拟这种效果。避免上下文过载：正如 DigitalOcean AI 指南所警告的那样，不要一次性混合身份验证任务和数据库模式更改。让每个提示词都紧紧围绕当前目标。
给大型规范准备扩展目录/摘要：一个聪明的技巧是让 Agent 给规范构建一个带摘要的扩展目录。这本质上是一份“规范缩略图”，将每个章节压缩成几个关键点或关键词，并标注细节出处。比方说，如果你的完整规范中有一个长达 500 字的“安全要求”章节，你可以让 Agent 将其总结为：“安全：使用 HTTPS，保护 API 密钥，实施输入验证（见规范全文 §4.2）”。通过在规划阶段创建这种层级化的摘要，你可以获得一个可以常驻提示词的“上帝视角”，而琐碎的细节则被卸载掉，除非需要。这个扩展目录充当了索引的角色：Agent 可以查阅它并意识到“啊，这里有个安全章节我该看一眼”，然后你再按需提供该章节。这类似于人类开发者先扫一遍大纲，然后在处理特定部分时翻到规范文档的相关页面。
要实现这一点，你可以在写完规范后提示 Agent：“将上述规范总结为一个极其简明的提纲，包含每个章节的关键点和参考标签。”结果可能是一份带有一两句话总结的章节列表。这份摘要可以放在系统消息或助手消息中，在不消耗过多 token 的情况下引导 Agent 的焦点。这种层次化的摘要方法被证明能通过聚焦纲要结构来帮助 LLM 维持长期上下文。Agent 就像随身携带了一份规范的“心智地图”。
针对规范的不同部分利用子 Agent 或“技能”：另一种进阶方法是使用多个专业 Agent（Anthropic 称之为 subagents，或者你也可以称之为“技能”）。每个子 Agent 都配置了特定的专业领域，并获得了规范中与该领域相关的部分。比方说，你可能有一个只了解规范中数据模型部分的“数据库设计师”子 Agent，以及一个了解 API 端点规范的“API 程序员”子 Agent。主 Agent（或协调器）可以自动将任务路由到相应的子 Agent。这样做的好处是每个 Agent 处理的上下文窗口更小，角色更专注，从而提高准确性，并允许对独立任务进行并行开发。Claude Code 支持此项功能，允许你定义拥有独立系统提示词和工具的子 Agent。如其文档所述：“每个子 Agent 都有特定的目的和专业领域，使用独立于主对话的上下文窗口，并有自定义的系统提示词来引导其行为。”当出现匹配子 Agent 领域的任务时，Claude 可以将任务委托给它，由子 Agent 独立返回结果。
利用并行 Agent 提高吞吐量：同时运行多个 Agent 正在成为提升开发者生产力的“下一个大趋势”。与其等待一个 Agent 完成后再开始另一个任务，你可以针对互不干扰的工作启动并行 Agent。按照Willison 的说法这叫做 “拥抱并行编程 Agent”，他指出这“极其有效，尽管心智负担很重”。关键在于界定任务范围，以免 Agent 互相踩脚——比如一个 Agent 写功能代码，另一个写测试；或者同时构建独立的组件。LangGraph 或 OpenAI Swarm 等编排框架可以帮助协调这些 Agent，而通过向量数据库（如 Chroma）实现的共享内存，则能让它们在无需冗余提示的情况下访问公共上下文。
单 Agent vs 多 Agent：何时该用哪种
在实践中，使用子智能体或特定技能提示词的具体做法通常是这样的：您可以维护多个规范文档（或提示词模板）——例如 `SPEC_backend.md`、`SPEC_frontend.md`——并告知人工智能（AI）：“对于后端任务，请参考 `SPEC_backend`；对于前端任务，请参考 `SPEC_frontend`。” 或者在 Cursor或Claude 等工具中，您可以直接为每个任务启动一个专用的子智能体。相较于单智能体循环，这种设置固然更为复杂，但它模拟了人类开发者的工作方式——我们在脑海中将庞大的需求说明（Spec）划分为相关的模块（您不可能一次性将厚达50页的规范全部记在脑中；您只需回忆起当前任务所需的部分，并对整体架构有一个宏观的认知）。正如前文所述，挑战在于如何管理相互依赖关系：子智能体之间仍须进行协调（例如，前端亟需从后端规范中获悉 API 契约）。一个中央系统或具备“架构师”角色的智能体可以通过参考子规范并确保一致性来提供协助。
将每个提示词聚焦于单一任务或部分：*即使没有复杂的多智能体配置，您也可手动执行模块化。例如，在编写完规范后，您的下一步行动可能是：“第一步：实现数据库模式。”您只需向智能体提供规范中的数据库部分，以及规范中的任何全局约束（例如技术栈）。智能体会据此展开工作。随后，在第二步“现在实现身份验证功能”时，您可以提供规范中的身份验证（Auth）部分，并在需要时提供模式的相关部分。通过在每个主要任务中刷新上下文，您可以确保模型不会携带大量过时或无关的信息，以免分散其注意力。正如一份指南所建议的：“重新开始：在切换主要功能特性时，启动新的会话以清除上下文”。您每次都可以提醒智能体注意关键的全局规则（源自规范的“约束”部分），但如果无需通盘掌握，就请勿将整个规范一股脑塞入。
使用代码内联指令和代码 TODO 注释： 另一个模块化的技巧是将您的代码或规范作为与AI对话的活跃部分。例如，使用描述待办事项的 `// TODO` 注释搭建代码骨架，并让智能体逐一完善。本质上，每个 TODO 充当着小型任务的微型规范。这使得 AI 能够保持高度专注（“根据该规范片段实现特定的函数”），并且您可以借此在一个紧凑的循环中进行迭代。这有如向 AI 提供一个待完成的待办事项，而不是一次性塞给它整张清单。
总结：*较小且专注的上下文胜过庞大的提示词。这能够提升代码质量，并避免 AI 因为一次性摄入过多内容而“不堪重负”。恰如一套最佳实践所总结的，向模型提供“专注单一任务”和“仅限相关信息”，避免将所有内容肆意倾倒。通过将工作结构化为多个模块——并利用规范摘要或子规范智能体等策略——您能避开上下文容量限制和 AI 的短期记忆上限。请记住，一个「恰好喂饱」的 AI 就像一个参数设定恰当的函数：只需为其提供完成手头工作所需的输入即可。
4. 内置自检、约束和人类的专业经验
让你的规范不仅是 Agent 的待办清单，更是质量控制指南——并且不要害怕注入你自己的专业见解。
一份优秀的 AI Agent 规范会预见 AI 可能出错的地方并设立“护栏”。它还会利用你所知的信息（领域知识、边缘情况、潜在坑点），以免 AI 在信息真空中操作。把规范想象成 AI 的教练兼裁判：它既要鼓励正确的方法，也要判罚违规行为。
使用三级边界系统：GitHub 对 2500 多个 Agent 文件的分析发现，最有效的规范使用三级边界系统，而非简单的“禁止事项”清单。这能让 Agent 在何时推进、何时暂停、何时停止方面获得更清晰的指导：
AI Agent 规范的三级边界
✅ 始终执行： Agent 无需询问即可采取的行动。“始终在提交前运行测试。”“始终遵循风格指南中的命名规范。”“始终将错误记录到监控服务中。”
⚠️ 事先询问： 需要人工批准的行动。“修改数据库模式前请询问。”“添加新依赖前请询问。”“更改 CI/CD 配置前请询问。”这一层级旨在捕捉那些可能没问题但值得人工检查的高影响变更。
🚫 绝不执行： 绝对红线。“严禁提交密钥或 API 秘钥。”“严禁编辑 `node_modules/` 或 `vendor/` 目录。”“未经明确批准，严禁删除失败的测试。”“严禁提交密钥”是研究中公认最有益的单一约束。
这种三级方法比平铺直叙的规则列表更细腻。它承认某些行为始终安全，某些需要监督，而某些则是绝对禁区。Agent 可以自信地处理“始终执行”项，标记“事先询问”项待审，并对“绝不执行”项执行硬停止。
鼓励自检：一个强大的模式是让 Agent 自动根据规范验证其工作。如果你的工具允许，你可以整合单元测试或代码检查 (linting) 等手段，让 AI 在生成代码后运行。但即便在规范/提示词层面，你也可以指示 AI 进行复核：比方说，“实现后，将结果与规范进行对比，确认满足所有需求。列出任何未涵盖的规范项。”这会促使 LLM 针对规范反思其输出，从而发现遗漏。这是一种内置在流程中的自我审计形式。
比方说，你可以在提示词末尾加上：“（在写完函数后，审阅上述需求列表，确保每一项都得到满足，并标记出遗漏的部分）。”随后，模型（理想情况下）会先输出代码，紧接着是一份简短的核查表，说明其是否满足了每项需求。这减少了在你运行测试之前它遗漏某些东西的几率。虽然并非万无一失，但确实有效。
用 LLM 作为裁判进行主观检查：对于难以自动测试的标准——如代码风格、可读性、对架构模式的遵循——可以考虑使用“LLM 作为裁判”。这意味着让第二个 Agent（或独立的提示词）对照规范中的质量指南，对第一个 Agent 的输出进行评审。Anthropic 等机构发现，这在主观评估方面非常有效。你可以提示：“评审这段代码是否遵循了我们的风格指南，并标记出任何违规之处。”“裁判 Agent”会返回反馈，这些反馈要么被整合，要么触发修改。这给语法检查之外增加了一层语义评估。
一致性测试：Willison 主张构建“一致性测试套件”——即任何实现都必须通过的、与语言无关的测试（通常基于 YAML）。这些测试充当了契约的角色：如果你在开发 API，一致性套件会规定预期的输入/输出，而 Agent 编写的代码必须满足所有情况。这比临时性的单元测试更严谨，因为它直接源自规范，且可在不同实现间复用。在规范的“成功标准”章节中包含一致性准则（比方说，“必须通过 `conformance/api-tests.yaml` 中的所有案例”）。
在规范中利用测试：如果可能的话，在你的规范和提示流中加入测试计划甚至实际的测试用例。在传统开发中，我们使用 TDD 或编写测试用例来明确需求——在 AI 协作中也可以这样做。比方说，在规范的“成功标准”中，你可以说“这些示例输入应产生这些输出……”或“以下单元测试应通过”。可以提示 Agent 在大脑中预演这些案例，或者如果它具备执行能力，就实际运行它们。Simon Willison 指出，拥有一个健壮的测试套件就像给 Agent 赋予了超能力——当测试失败时，它们可以迅速验证并迭代。在 AI 编程场景下，在规范中写一点关于测试或预期结果的伪代码，可以有效引导 Agent 的实现。此外，你可以在子 Agent 设置中使用专门的“测试 Agent”，由它获取规范标准并持续验证“代码 Agent”的输出。
带入你的领域知识：你的规范应体现出只有经验丰富的开发者或知情者才具备的见解。比方说，如果你在构建一个电商 Agent，且深知“产品”和“类别”之间是多对多关系，请明确指出（不要假设 AI 会推断出来——它可能推断不出）。如果某个库是出了名的难搞，请提到要避免的坑。本质上，这相当于把你的“导师经验”灌注进规范里。规范可以包含类似这样的建议：“如果使用库 X，注意版本 Y 中的内存泄漏问题（请应用变通方案 Z）”。这种层级的细节能将平庸的 AI 输出转化为真正健壮的方案，因为你已经引导 AI 避开了常见陷阱。
此外，如果你有个人偏好或风格指南（比方说，“在 React 中优先使用函数组件而非类组件”），请将其写入规范。AI 随后会模仿你的风格。许多工程师甚至在规范中包含简短的示例，比方说：“所有 API 响应都应为 JSON。比方说：错误时返回 `{"error": "message"}`”。通过提供一个简单的示例，你可以将 AI 固定在你想要的准确格式上。
针对简单任务保持极简：虽然我们提倡规范要详尽，但专业水平的体现之一在于知道何时该保持简单。对于相对简单、孤立的任务，规范过度详尽反而可能帮倒忙，让人困惑。如果你要求 Agent 做一些简单的事情（如“将页面上的 div 居中”），你可能只需说：“确保方案简洁，不要添加多余的标记或样式”。这种时候不需要完整的 PRD。相反，对于复杂的任务（如“实现带 token 刷新和错误处理的 OAuth 流程”），那才是拿出详细规范的时候。一条金科玉律是：根据任务复杂度调整规范细节。对于难题不要规范不足（Agent 会乱阵脚或偏离轨道），对琐碎任务也不要规范过度（Agent 可能会陷入细枝末节或在不必要的指令上耗尽上下文）。
如有需要，维持 AI 的“人设”：有时，规范的一部分是定义 Agent 应当如何表现或响应，尤其是当 Agent 需要与用户交互时。比方说，如果构建一个客户支持 Agent，你的规范可能包括：“使用友好且专业的语气”，“如果你不知道答案，请请求澄清或提议后续跟进，而不是靠猜”。这类规则（通常包含在系统提示词中）有助于让 AI 的输出符合预期。它们本质上是 AI 行为的规范项。在漫长的会话中保持它们的一致性，并在必要时提醒模型（如果不管好，LLM 的风格会随时间产生“漂移”）。
你始终是整个环节的执行主管：规范赋予了 Agent 力量，但你才是最终的质量过滤器。如果 Agent 产出的东西在技术上符合规范，但感觉不对劲，请相信你的直觉。要么完善规范，要么直接调整输出。AI Agent 的一个优点是它们不会觉得被冒犯——如果它们给出的设计跑偏了，你可以说：“我的本意其实不是这个意思，让我们把规范讲清楚，重新做一遍。”规范是与 AI 在协作过程中的动态产物，而不是一份不可更改的一次性合同。
Simon Willison 曾幽默地将与 AI Agent 协作比作“一种非常奇怪的管理形式”，甚至说“从编程 Agent 那里获得好结果，感觉就像在管理一名人类实习生，这种相似度让人不安”。你需要提供清晰的指令（规范），确保它们拥有必要的上下文（规范和相关数据），并给出可操作的反馈。规范搭建了舞台，但在执行过程中的监控和反馈才是关键。如果说 AI 是一个“只要有机会就绝对会偷懒耍滑的奇怪数字实习生”，那么你编写的规范和约束就是用来防止它们偷懒并让其专注任务的手段。
回报就在这里：一份优秀的规范不仅告诉 AI 构建什么，还帮助它自我纠错并保持在安全边界内。通过内置验证步骤、约束条件和你辛苦积累的知识，你将大幅提高 Agent 输出“一次过”的概率（或至少更接近正确）。这减少了迭代次数，也减少了那些让你惊呼“它到底为什么会这么干？”的时刻。
5. 测试、迭代并演进规范（并使用正确的工具）
将编写规范和构建 Agent 视为一个迭代循环：尽早测试、收集反馈、完善规范，并利用工具自动化检查。
初始规范并不是终点，而是循环的起点。最好的结果来自于你持续对照规范验证 Agent 的工作并做出相应调整。此外，现代 AI 开发者会使用（从 CI 流水线到上下文管理工具的）各种工具来支持这一流程。
持续测试：不要等到最后才看 Agent 是否符合规范。在每个重大里程碑甚至每个函数完成后，运行测试或至少进行快速的人工检查。如果失败了，在继续前先更新规范或提示词。比方说，如果规范说“密码必须用 bcrypt 加密”，而你看到 Agent 的代码在存储明文——停下来纠正它（并在规范或提示词中重申该规则）。自动化测试在这里大放异彩：如果你提供了测试（或随做随写），让 Agent 运行它们。在许多编程 Agent 设置中，你可以让 Agent 在完成任务后运行 `npm test` 或类似命令。结果（失败项）可以反馈到下一个提示词中，相当于告诉 Agent：“你的输出在 X、Y、Z 方面不符合规范——修复它。”这种“Agent 循环”（编写->测试->修复->重复）极具威力，也是 Claude Code 或 Copilot Labs 等工具能够处理更大型任务的原因。始终明确“完成”的定义（通过测试或标准）并进行检查。
迭代规范本身：如果你发现规范不完整或不清晰（可能是 Agent 误解了某些内容，或者你意识到漏掉了某个需求），请更新规范文档。然后明确地让 Agent 与新规范重新同步：“我已将规范更新如下……根据更新后的规范，调整计划或重构代码。”这样，规范就始终是唯一的事实来源。这类似于我们在常规开发中处理需求变更的方式——只不过在这种情况下，你同时还是 AI Agent 的产品经理。如果可能的话，保留版本历史（哪怕只是通过提交信息或笔记），这样你就知道变动了什么以及原因。
利用上下文管理和记忆工具：目前已经出现了一个日益壮大的工具生态系统，可用于帮助管理 AI Agent 的上下文和知识。比方说，通过检索增强生成 (RAG) 这种模式，Agent 可以从知识库（如向量数据库）中即时提取相关的分块数据。如果你的规范非常庞大，你可以将其分段嵌入，让 Agent 在需要时检索最相关的部分，而不是始终提供全文。还有一些实现了模型上下文协议 (MCP) 的框架，它们可以根据当前任务自动向模型喂入正确的上下文。比方说 Context7 (context7.com)，它可以根据你正在处理的内容，自动从文档中抓取相关的上下文片段。在实践中，这可能意味着 Agent 注意到你正在处理“支付处理”，于是它将规范或文档中的“支付”章节拉入提示词。考虑利用此类工具或设置一个初级版本（哪怕只是在规范文档中进行简单的搜索）。
谨慎并行化：有些开发者会在不同任务上并行运行多个 Agent 实例（如前文提到的子 Agent）。这可以加速开发——比方说，一个 Agent 生成代码的同时，另一个编写测试；或者同时构建两个功能。如果你走这条路，请确保任务是真正独立的或已明确分离，以避免冲突（规范中应注明任何依赖关系）。比方说，不要让两个 Agent 同时修改同一个文件。一种工作流是让一个 Agent 生成代码，另一个并行评审；或者构建随后合并的独立组件。这是进阶用法，管理起来可能很费脑子（正如 Willison 所承认的，运行多个 Agent 效果惊人，但心智负担也重！）。初期建议最多运行 2-3 个 Agent，以保持可控。
版本控制和规范锁定：使用 Git 或你选择的版本控制工具来跟踪 Agent 的所作所为。在 AI 辅助下，良好的版本控制习惯尤为重要。将规范文件本身提交到仓库。这不仅保留了历史，Agent 甚至可以利用 `git diff` 或 `blame` 来理解变更（LLM 阅读 diff 的能力相当强）。一些进阶的 Agent 设置允许 Agent 查询版本控制历史，看看某项内容是什么时候引入的——令人惊讶的是，模型在“玩转 Git”方面表现得极其出色。通过将规范保留在仓库中，你和 AI 都能跟踪演进过程。有些工具（如前述 GitHub Spec Kit）将规范驱动开发整合到了 Git 工作流中——比方说，根据规范更新情况来限制合并，或者根据规范项生成核查清单。虽然不一定非要这些工具才能成功，但核心思路是将规范视为代码——勤勉地维护它。
成本和速度考量：使用大型模型和长上下文可能既慢又贵。一个实用建议是巧妙地进行模型选择和批处理。或许在初稿或重复性工作中使用更便宜/更快的模型，而将最强（也最贵）的模型留给最终输出或复杂推理。一些开发者使用 GPT-4 或 Claude 进行规划和关键步骤，而将简单的扩展或重构卸载给本地模型或更小的 API 模型。如果使用多个 Agent，未必全都需要顶级配置；运行测试或代码检查的 Agent 可以用小模型。同时考虑限制上下文大小：如果 5k token 就能搞定，就不要喂 20k。正如我们讨论过的，token 越多，收益递减越明显。
监控并记录一切：在复杂的 Agent 工作流中，记录 Agent 的动作和输出至关重要。检查日志，看 Agent 是否偏离轨道或遇到错误。许多框架提供追踪日志或允许打印 Agent 的“思维链”（特别是当你提示它逐步思考时）。审阅这些日志可以发现规范或指令在何处被误解了。这与调试程序并无二致——只不过这个“程序”是对话/提示链。如果发生了诡异的事情，回到规范/指令中看看是否存在歧义。
学习与改进：最后，将每个项目视为磨炼规范编写技巧的学习机会。也许你会发现某种表述总是让 AI 困惑，或者以某种方式组织规范章节能获得更好的遵循效果。将这些教训融入下一份规范。AI Agent 领域正在飞速演进，新的最佳实践（和工具）层出不穷。通过博客（如 Simon Willison、Andrej Karpathy 等人的博客）保持更新，并大胆尝试。
一份 AI Agent 规范绝非“一劳永逸”。它是指令、验证和精炼这一持续循环的一部分。这种勤勉的回报是丰厚的：通过及早发现问题并保持 Agent 的步调一致，可以避免后期昂贵的重写或失败。正如一位 AI 工程师打趣道，运用这些实践感觉就像拥有一支“实习生大军”为你效力，但你必须管理好他们。一份持续维护的优秀规范，就是你的管理工具。
避免常见坑点
在结束之前，有必要指出一些可能会让哪怕是初衷良好的规范驱动工作流跑偏的反模式。GitHub 对 2500 多个 Agent 文件的研究揭示了一条严峻的鸿沟：“大多数 Agent 文件的失败都是因为太模糊。”以下是要避免的错误：
模糊的提示词： “给我做个酷炫的东西”或“让它运行得更好”让 Agent 无处着力。正如 Baptiste Studer 所言：“提示词模糊意味着结果错误。”对输入、输出和约束要具体。说“你是一个乐于助人的编程助手”没用；说“你是一名测试工程师，负责为 React 组件编写测试，遵循这些示例，且严禁修改源代码”才有用。
不加摘要的冗长上下文： 往提示词里丢 50 页文档并寄希望于模型自己悟出来，这几乎行不通。使用层次化摘要（如原则 3 所述）或 RAG 来仅呈现相关内容。上下文长度不能替代上下文质量。
跳过人工评审： Willison 有条个人准则：“我绝不提交连我也没法向别人解释清楚的代码。”Agent 生成了通过测试的代码，并不代表它就是正确、安全或可维护的。务必评审关键代码路径。“纸牌屋”的比喻很贴切：AI 生成的代码可能看起来很稳固，但在你未测试的边缘情况下会瞬间崩塌。
将“氛围编程”与生产工程混为一谈： 利用 AI 进行快速原型开发（即“氛围编程”）非常适合探索和一次性项目。但在没有严谨规范、测试和评审的情况下将代码推向生产环境，就是在找麻烦。我不会将“氛围编程”与“ AI 辅助工程”混为一谈——后者需要遵守本指南所描述的纪律。搞清楚你是哪一种。
忽略“致命三重威胁”： Willison 警告说，AI Agent 有三个特性使其变得危险：速度（它们干活比你评审快）、非确定性（相同的输入可能得到不同的输出）和成本（诱导人们在验证上抄近路）。你的规范和评审流程必须兼顾这三点。不要让速度超越了你的验证能力。
遗漏六大核心领域： 如果你的规范没有涵盖命令、测试、项目结构、代码风格、Git 工作流和边界，你很可能漏掉了 Agent 所需的关键信息。在交给 Agent 之前，请使用第 2 节中的六大领域清单进行合规性检查。
结语
给 AI 编程智能体编写有效规范，既需要扎实的软件工程原则，也需要对 LLM 的怪癖进行调适。从明确目标开始，让 AI 协助扩展计划。像对待正式设计文档一样构建规范——涵盖六大核心领域并将其整合进工具链，使其成为可执行的产物，而不仅仅是文字。通过每次只喂给 Agent 一块“拼图”，让其保持专注（并考虑使用摘要目录、子 Agent 或并行编排等聪明策略来处理大型规范）。通过包含三级边界（始终执行/事先询问/绝不执行）、自检和一致性测试来预见坑点——本质上，就是教 AI 别掉链子。并将整个过程视为迭代：利用测试和反馈不断精炼规范和代码。
遵循这些指南，你的 AI Agent 在处理大型上下文时“罢工”或胡言乱语的概率将大大降低。
祝你规范编写愉快！
译者：boxi。
