---
title: 260307-如何为 AI 智能体写出优秀的规范
description: 学习如何为 AI 智能体写出真正可执行的规范，提升 AI 驱动开发工作流中的清晰度、专注度和生产力。文章涵盖从高层愿景到任务拆解的五个核心原则。
author: Addy Osmani
source: https://addyosmani.com/blog/good-spec/
date: '2026-03-07'
category: 03-toolchain-frameworks
tags:
- AI智能体
- 规范编写
- AI 辅助开发
- 提示工程
- 软件工程
---

# 如何为 AI 智能体写出优秀的规范


**作者：Addy Osmani**

**原文：[查看原文](https://addyosmani.com/blog/good-spec/)**



**TL;DR：写规范的目标，是给 AI 一个足够清晰、细节充分、但又不过载的执行依据。需要写清结构、风格、测试和边界；把大任务拆成小任务；先在只读模式下规划，再执行，并在过程中持续迭代。**

_"我看过很多关于 AI 智能体规范的讨论，但始终没找到一套真正稳定、可复用的框架。我可以写出接近 RFC 级别的规范，可一旦上下文变得太大，模型就开始失焦。"_

很多开发者都有过这种挫败感：你明明写出了一份看起来像 RFC 的大规范，模型却还是在上下文变长后逐渐跑偏。问题往往不在于“写得不够长”，而在于规范是否真的适合智能体消费。好的规范，应该既能清楚约束方向，又能控制上下文负担，还能随着项目推进持续演进。本文会把我在 Claude Code、Gemini CLI 等工具上的实践，整理成一套更可复用的规范写法。

我们将介绍优秀 AI 智能体规范的五个原则，每个原则都以粗体要点开始。

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

**用简洁的高层规范启动你的项目，然后让 AI 将其扩展为详细计划**。

不要在一开始就把所有细节都设计死，而是先从清晰的目标陈述和几条核心需求出发。把它当成一份“产品简报”，先让智能体基于它起草更完整的规范。这样做利用了 AI 擅长展开和补全的优势，同时方向盘仍然掌握在你手里。除非项目一上来就有非常严格的技术约束，否则这种方式通常更高效。

**为什么这有效**：基于 LLM 的智能体很擅长在高层目标明确时补齐细节，但前提是它真的知道自己的任务边界。你给它一份简短但可靠的大纲，再让它扩展成完整规范（比如 `spec.md`），本质上就是在为后续实现建立一个可持续引用的“真相来源”。对智能体来说，前置规划的重要性往往比对人更高：计划先对齐，后面的代码才更稳。

**实用方法**：你可以在新会话里直接这样开头：“你是一名 AI 软件工程师。请为 [项目 X] 起草一份详细规范，覆盖目标、功能、约束和分步计划。”初始提示尽量保持高层，比如“构建一个让用户管理待办事项的 Web 应用，包含账号系统、数据库和简单 UI”。智能体通常会先产出结构化草案：概述、功能列表、技术栈建议、数据模型等。接下来，这份规范就会成为你和智能体共享的参考基线。在真正开始写代码前，先把这份草案审一遍，修正偏题、补齐遗漏。

**用计划模式强制先规划**：像 Claude Code 这样的工具提供计划模式，会把智能体限制在只读范围内——它可以读代码、分析上下文、生成计划，但不会直接改文件。这个阶段非常适合拿来磨规范：你描述要做什么，它一边探索现有代码，一边起草方案；它也会反过来问你问题，帮助你补齐模糊地带。等到架构、测试、安全风险和关键约束都讲清楚之后，再切回执行模式。这样可以显著降低“规范没稳、代码先飞”的风险。

**把规范当成长期上下文**：一旦你确认方案，就把规范保存下来（比如 `SPEC.md`），并在后续需要时把相关片段重新喂给智能体。很多成熟的使用者都会这样做：规范文件不是一次性文档，而是跨会话存在的锚点。这样做能缓解长对话带来的上下文漂移，也能在你重新开新会话时快速恢复状态。它和团队里使用 PRD 的逻辑很像——无论执行者是人还是 AI，都能围绕同一份基线对齐。

**保持目标导向**：AI 智能体的高层规范应该更多地关注什么和为什么，而不是细节如何（至少最初）。把它想象成用户故事和验收标准：用户是谁？他们需要什么？成功是什么样子？（例如"用户可以添加、编辑、完成任务；数据持久保存；应用响应迅速且安全"）。这使 AI 的详细规范植根于用户需求和结果，而不仅仅是技术待办事项。正如 [GitHub Spec Kit 文档](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)所说，提供你正在构建什么以及为什么的高层描述，让编码智能体生成专注于用户体验和成功标准的详细规范。从这个大局愿景开始可以防止智能体在后来进入编码时见树不见林。

## **2. 像专业 PRD（或 SRS）一样构建规范**

**将你的 AI 规范视为具有清晰部分的结构化文档（PRD），而不是松散的笔记堆**。

许多开发者将智能体的规范视为传统的产品需求文档（PRD）或系统设计文档——全面、组织良好且易于"字面意义"的 AI 解析。这种正式方法为智能体提供了一个蓝图，并减少了歧义。

**六个核心领域**：GitHub 对[超过 2?500 个智能体配置文件](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)的分析揭示了一个清晰的模式：最有效的规范涵盖六个领域。将此用作完整性检查清单：

**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 工程师建议[将提示组织成不同的部分](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)（如 `<background>`、`<instructions>`、`<tools>`、`<output_format>` 等）正是出于这个原因——它为模型提供了关于哪些信息是哪些的强烈提示。记住，"最小并不一定意味着简短"——如果重要，不要回避规范中的细节，但要保持专注。

**将规范集成到你的工具链中**：将规范视为与版本控制和 CI/CD 相关的"可执行工件"。[GitHub Spec Kit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/) 使用一个四阶段、门控的工作流，使你的规范成为工程流程的中心。不是编写规范然后将其搁置，规范驱动实施、检查清单和任务分解。你的主要角色是引导；编码智能体完成大部分编写工作。每个阶段都有特定的工作，在当前任务完全验证之前，你不会进入下一个阶段：

![规范驱动开发工作流](/images/articles/localized/03-toolchain-frameworks/how-to-write-good-spec-for-ai-agents/01.jpg)

**1. 指定**：你先描述“要做什么”和“为什么做”，再让智能体把它扩展成详细规范。这里关注的不是技术栈，而是用户旅程、交互方式和成功标准。谁会使用它？它解决什么问题？用户将如何与它互动？先把体验层讲清楚，再让智能体补足细节。

**2. 规划**：这一步进入技术层。你给出技术栈、架构、限制条件和现实约束，智能体据此生成技术计划。如果项目要对接遗留系统、满足合规要求，或者必须遵循团队内部规范，这些都应在这里讲明。必要时也可以让它同时给出多个方案，方便比较取舍。

**3. 任务**：智能体会基于规范和计划，把工作拆成小而可审查的任务块。每个任务都应该足够具体，可以单独实现、单独验证。不是笼统地写“做登录系统”，而是拆成像“创建一个验证邮箱格式的注册接口”这样的可执行项。

**4. 实施**：智能体按任务逐个推进，必要时也可以并行处理。这样你审查的就不是一大坨代码，而是一组围绕具体问题的集中改动。你的角色也很清楚：在每个阶段确认规范是否准确、计划是否考虑了约束、实现是否遗漏边界情况。整个流程的价值，就在于它天然带着检查点。

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

**考虑 agents.md 用于专门的角色**：对于像 GitHub Copilot 这样的工具，你可以创建 [agents.md 文件](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)来定义专门的智能体角色——用于技术写作的 @docs-agent、用于 QA 的 @test-agent、用于代码审查的 @security-agent。每个文件充当该角色的行为、命令和边界的集中规范。当你想要不同任务的不同智能体而不是一个通用助手时，这特别有用。

**为智能体体验（AX）设计**：正如我们为开发者体验（DX）设计 API 一样，考虑为"智能体体验"设计规范。这意味着干净、可解析的格式：智能体将使用的任何 API 的 OpenAPI 架构、为 LLM 消费总结文档的 llms.txt 文件以及显式类型定义。智能体 AI 基金会（AAIF）正在标准化像 MCP（模型上下文协议）这样的工具集成协议——遵循这些模式的规范更容易让智能体可靠地消费和操作。

**PRD vs SRS 思维方式**：从既定的文档实践中借鉴是有帮助的。对于 AI 智能体规范，你通常会将这些混合到一个文档中（如上所示），但涵盖两个角度对你很有帮助。像 PRD 一样编写它可以确保你包含以用户为中心的上下文（"每个功能背后的原因"），这样 AI 就不会为错误的事情优化。像 SRS 一样扩展它可以确保你确定 AI 实际生成正确代码所需的细节（如使用什么数据库或 API）。开发者发现，这种额外的前期努力通过大幅减少后来与智能体的误解而得到回报。

**使规范成为"活文档"**：不要写了就忘了。随着你和智能体做出决定或发现新信息，更新规范。如果 AI 必须更改数据模型或你决定削减功能，在规范中反映这一点，使其保持为基本事实。把它想象成版本控制的文档。在[规范驱动工作流](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)中，规范驱动实施、测试和任务分解，在规范验证之前你不会进入编码。这种习惯使项目保持连贯，特别是如果你或智能体离开后再回来。记住，规范不仅仅是为 AI 准备的——它帮助你作为开发者保持监督并确保 AI 的工作满足真正的需求。

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

**分而治之：一次给 AI 一个集中的任务，而不是一次性包含所有内容的单一提示**。

有经验的 AI 工程师已经了解到，试图将整个项目（所有需求、所有代码、所有指令）塞进单个提示或智能体消息是造成混乱的秘诀。你不仅有达到 token 限制的风险，还有模型因"[指令诅咒](https://maxpool.dev/research-papers/curse_of_instructions_report.html)"而失去焦点的风险——太多指令导致它无法很好地遵循任何一个。解决方案是以模块化方式设计你的规范和工作流，一次处理一个部分，只引入该部分所需的上下文。

![模块化 AI 规范](/images/articles/localized/03-toolchain-frameworks/how-to-write-good-spec-for-ai-agents/02.jpg)

**太多上下文/指令的诅咒**：研究已经证实了许多开发者从经验中看到的：当你在提示中堆积更多指令或数据时，模型遵守每个指令的性能[显著下降](https://openreview.net/pdf/848f1332e941771aa491f036f6350af2effe0513.pdf)。一项研究将此称为"指令诅咒"，表明即使是 GPT-4 和 Claude 在被要求同时满足许多需求时也会挣扎。实际上，如果你提出 10 个详细规则的要点，AI 可能会遵守前几个并开始忽略其他的。更好的策略是迭代聚焦。[行业指南](https://maxpool.dev/research-papers/curse_of_instructions_report.html?建议将复杂需求分解为顺序的、简单的指令作为最佳实践。让 AI 一次专注于一个子问题，完成它，然后继续。这使质量保持高水平，错误可管理。

**将规范分为阶段或组件**：如果你的规范文档非常长或涵盖很多内容，考虑将其分成部分（物理上独立的文件或明确独立的部分）。例如，你可能有一个"后端 API 规范"部分和另一个"前端 UI 规范"部分。当它在后端工作时，你不需要总是向 AI 提供前端规范，反之亦然。许多使用多智能体设置的开发者甚至为每个部分创建单独的智能体或子流程——例如一个智能体处理数据库/架构，另一个处理 API 逻辑，另一个处理前端——每个都有规范的相关切片。即使你使用单个智能体，你也可以通过仅将相关规范部分复制到该任务的提示中来模拟这一点。避免上下文过载：不要在一次操作中混合身份验证任务和数据库架构更改，正如 [DigitalOcean AI 指南](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/)所警告的。使每个提示紧密限定在当前目标。

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

要实现这一点，你可以在编写规范后提示智能体："将上面的规范总结为一个非常简洁的大纲，包含每个部分的关键点和参考标签。"结果可能是一个部分列表，每个部分有一两句摘要。该摘要可以保留在系统或助手消息中，以指导智能体的焦点，而不会占用太多 token。这种[分层总结方法](https://addyo.substack.com/p/context-engineering-bringing-engineering?已知通过关注高层结构来帮助 LLM 维护长期上下文。智能体携带规范的"心智地图"。

**利用子智能体或"技能"处理不同的规范部分**：另一种高级方法是使用多个专门的智能体（Anthropic 称之为子智能体或你可能称之为"技能"）。每个子智能体都配置为特定的专业领域，并获得与该领域相关的规范部分。例如，你可能有一个数据库设计师子智能体，它只知道规范的数据模型部分，以及一个 API 编码器子智能体，它知道 API 端点规范。主智能体（或编排器）可以自动将任务路由到适当的子智能体。好处是每个智能体都有一个更小的上下文窗口要处理和一个更集中的角色，这可以[提高准确性并允许在独立任务上并行工作](https://10xdevelopers.dev/structured/claude-code-with-subagents/)。Anthropic 的 Claude Code 通过让你定义具有自己的系统提示和工具的子智能体来支持这一点。"每个子智能体都有特定的目的和专业领域，使用与主对话分离的自己的上下文窗口，并有指导其行为的自定义系统提示，"正如他们的文档所描述的。当出现与子智能体领域匹配的任务时，Claude 可以将该任务委派给它，子智能体独立返回结果。

**并行智能体以提高吞吐量**：同时运行多个智能体正在成为开发者生产力的"下一个大事件"。不是等待一个智能体完成后再开始另一个任务，你可以为非重叠工作启动并行智能体。Willison 将此描述为"[拥抱并行编码智能体](https://simonwillison.net/2025/Oct/7/vibe-engineering/)"，并指出它"令人惊讶地有效，如果精神上令人疲惫"。关键是确定任务范围，使智能体不会相互干扰——一个智能体编码功能，而另一个编写测试，或者并发构建单独的组件。像 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，"现在实现身份验证功能"，你提供规范的身份验证部分，如果需要，可能还有架构的相关部分。通过为每个主要任务刷新上下文，你确保模型不会携带大量可能分散注意力的陈旧或不相关信息。正如一份指南所建议的："[重新开始：开始新会话](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/)以在主要功能之间切换时清除上下文"。你总是可以提醒智能体关键的全局规则（来自规范的约束部分），但如果不是全部需要，不要塞入整个规范。

**使用内联指令和代码 TODO**：另一个模块化技巧是使用你的代码或规范作为对话的活跃部分。例如，用描述需要做什么的 // TODO 注释搭建你的代码，让智能体逐一填充它们。每个 TODO 本质上充当小任务的迷你规范。这使 AI 保持激光聚焦（"根据此规范片段实现此特定函数"），你可以在紧密循环中迭代。这类似于给 AI 一个检查清单项来完成，而不是一次性完成整个检查清单。

底线：小的、集中的上下文胜过一个巨大的提示。这提高了质量，并防止 AI 一次被太多东西"压倒"。正如一套最佳实践所总结的，向模型提供"一个任务焦点"和"仅相关信息"，避免到处倾倒所有东西。通过将工作构建为模块——并使用规范摘要或子规范智能体等策略——你将绕过上下文大小限制和 AI 的短期记忆上限。记住，喂养良好的 AI 就像喂养良好的函数：只给它[手头工作所需的输入](https://addyo.substack.com/p/context-engineering-bringing-engineering)。

## **4. 建立自检、约束和人类专业知识**

**使你的规范不仅仅是智能体的待办事项列表，还是质量控制指南——不要害怕注入你自己的专业知识**。

一个好的 AI 智能体规范预测 AI 可能出错的地方并设置护栏。它还利用你所知道的（领域知识、边缘情况、"陷阱"），这样 AI 就不会在真空中操作。把规范想象成 AI 的教练和裁判：它应该鼓励正确的方法并指出犯规。

**使用三层边界**：[GitHub 对 2?500+ 智能体文件的分析](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)发现，最有效的规范使用三层边界系统，而不是简单的禁止列表。这为智能体提供了更清晰的指导，说明何时继续、何时暂停以及何时停止：

![AI 智能体规范的三层边界](/images/articles/localized/03-toolchain-frameworks/how-to-write-good-spec-for-ai-agents/03.jpg)

**✅ 始终做**：智能体应该在不询问的情况下采取的行动。"始终在提交前运行测试。""始终遵循风格指南中的命名约定。""始终将错误记录到监控服务。"

**⚠️ 先询问**：需要人工批准的行动。"修改数据库架构前先询问。""添加新依赖项前先询问。""更改 CI/CD 配置前先询问。"这一层捕获可能没问题但值得人工检查的高影响更改。

**🚫 永远不要**：硬停止。"永远不要提交秘密或 API 密钥。""永远不要编辑 node_modules/ 或 vendor/。""未经明确批准，永远不要删除失败的测试。""永远不要提交秘密"是研究中最常见的有用约束。

这种三层方法比平面规则列表更细致。它承认某些行动总是安全的，某些需要监督，某些是绝对禁止的。智能体可以自信地继续"始终"项目，标记"先询问"项目以供审查，并在"永远不要"项目上硬停止。

**鼓励自我验证**：一个强大的模式是让智能体自动根据规范验证其工作。如果你的工具允许，你可以集成 AI 可以在生成代码后运行的单元测试或 linting 等检查。但即使在规范/提示级别，你也可以指示 AI 进行双重检查：例如"实施后，将结果与规范进行比较并确认满足所有要求。列出任何未解决的规范项目。"这推动 LLM 相对于规范反思其输出，捕获遗漏。这是内置到流程中的一种自我审计形式。

例如，你可能在提示后附加："（编写函数后，审查上述需求列表并确保满足每个需求，标记任何缺失的需求）。"然后模型将（理想情况下）输出代码，然后是一个简短的检查清单，指示它是否满足每个要求。这减少了在你甚至运行测试之前它忘记某些东西的机会。这不是万无一失的，但它有帮助。

**LLM 作为主观检查的评判者**：对于难以自动测试的标准——代码风格、可读性、对架构模式的遵守——考虑使用"LLM 作为评判者"。这意味着让第二个智能体（或单独的提示）根据你的规范的质量指南审查第一个智能体的输出。Anthropic 和其他人发现这对主观评估有效。你可能会提示："根据我们的风格指南审查此代码。标记任何违规。"评判者智能体返回反馈，这些反馈要么被纳入，要么触发修订。这在语法检查之外增加了一层语义评估。

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

**在规范中利用测试**：如果可能，在你的规范和提示流程中纳入测试计划甚至实际测试。在传统开发中，我们使用 TDD 或编写测试用例来澄清需求——你可以对 AI 做同样的事情。例如，在规范的成功标准中，你可能会说"这些示例输入应该产生这些输出……"或"以下单元测试应该通过。"如果智能体有该能力，可以提示它在脑海中运行这些情况或实际执行它们。Simon Willison 指出，拥有[强大的测试套件](https://simonwillison.net/2025/Oct/7/vibe-engineering/)就像给智能体超能力——当测试失败时，它们可以快速验证和迭代。在 AI 编码上下文中，在规范中为测试或预期结果编写一些伪代码可以指导智能体的实现。此外，你可以在子智能体设置中使用专用的"[测试智能体](https://10xdevelopers.dev/structured/claude-code-with-subagents/)"，它采用规范的标准并持续验证"代码智能体"的输出。

**带来你的领域知识**：你的规范应该反映只有有经验的开发者或有上下文的人才知道的见解。例如，如果你正在构建电子商务智能体，你知道"产品"和"类别"有多对多关系，请明确说明（不要假设 AI 会推断——它可能不会）。如果某个库特别棘手，请提及要避免的陷阱。本质上，将你的指导倾注到规范中。规范可以包含建议，如"如果使用库 X，请注意版本 Y 中的内存泄漏问题（应用变通方法 Z）。"这种细节水平将平均 AI 输出转变为真正强大的解决方案，因为你已经引导 AI 远离常见陷阱。

此外，如果你有偏好或风格指南（比如，"在 React 中使用函数组件而不是类组件"），在规范中编码。然后 AI 将模仿你的风格。许多工程师甚至在规范中包含小示例，例如，"所有 API 响应都应该是 JSON。例如 {"error": "message"} 用于错误。"通过给出快速示例，你将 AI 锚定到你想要的确切格式。

**简单任务的极简主义**：虽然我们提倡彻底的规范，但专业知识的一部分是知道何时保持简单。对于相对简单、孤立的任务，过于繁重的规范实际上可能比帮助更混乱。如果你要求智能体做一些简单的事情（如"在页面上居中一个 div"），你可能只需说，"确保保持解决方案简洁，不要添加多余的标记或样式。"那里不需要完整的 PRD。相反，对于复杂的任务（如"实现带有 token 刷新和错误处理的 OAuth 流程"），那就是你拿出详细规范的时候。一个好的经验法则：根据任务复杂性调整规范细节。不要对困难问题规范不足（智能体会挣扎或偏离轨道），但不要对琐碎问题过度规范（智能体可能会纠缠或在不必要的指令上使用上下文）。

**如果需要，明确 AI 的“角色”**：有时，规范的一部分就是定义智能体该以什么方式行动或回应，尤其是在它要直接与用户交互时。例如，如果你在构建客服智能体，规范里可以明确写上“语气友好且专业”“不知道答案时先澄清或说明后续跟进，而不是猜测”。这类规则通常会进入系统提示，用来让输出长期保持一致。

**你仍然是循环中的执行者**：规范赋予智能体权力，但你仍然是最终的质量过滤器。如果智能体产生的东西在技术上符合规范但感觉不对，相信你的判断。要么完善规范，要么直接调整输出。AI 智能体的好处是它们不会被冒犯——如果它们提供的设计偏离了，你可以说，"实际上，那不是我的意图，让我们澄清规范并重做。"规范是与 AI 协作的活工件，而不是你无法更改的一次性合同。

Simon Willison 曾幽默地把与 AI 智能体协作形容为“一种非常奇怪的管理形式”。这个比喻真正想强调的是：你需要给出清晰指令、提供足够上下文，并持续给出可执行反馈。规范负责搭台，执行过程中的监控与反馈则决定最后效果。

这是回报：一个好的规范不仅告诉 AI 要构建什么，它还帮助它自我纠正并保持在安全边界内。通过融入验证步骤、约束和你来之不易的知识，你大大增加了智能体的输出第一次就正确（或至少更接近正确）的几率。这减少了迭代和那些"它到底为什么这样做？"的时刻。

**将规范编写和智能体构建视为迭代循环：尽早测试、收集反馈、完善规范并利用工具自动化检查**。

初始规范不是结束——它是循环的开始。当你持续根据规范验证智能体的工作并相应调整时，会产生最佳结果。此外，现代 AI 开发者使用各种工具来支持这个过程（从 CI 管道到上下文管理实用程序）。

![规范迭代循环：测试、反馈、完善、工具](/images/articles/localized/03-toolchain-frameworks/how-to-write-good-spec-for-ai-agents/04.jpg)

**持续测试**：不要等到最后才看智能体是否满足规范。在每个主要里程碑甚至每个函数之后，运行测试或至少进行快速手动检查。如果某些东西失败了，在继续之前更新规范或提示。例如，如果规范说"密码必须用 bcrypt 哈希"，你看到智能体的代码存储明文——停止并纠正它（并提醒规范或提示关于规则）。自动化测试在这里大放异彩：如果你提供了测试（或在进行时编写它们），让智能体运行它们。在许多编码智能体设置中，你可以让智能体在完成任务后运行 npm test 或类似命令。结果（失败）然后可以反馈到下一个提示，有效地告诉智能体"你的输出在 X、Y、Z 上不符合规范——修复它。"这种智能体循环（代码 -> 测试 -> 修复 -> 重复）非常强大，是像 Claude Code 或 Copilot Labs 这样的工具如何演进以处理更大任务的方式。始终定义"完成"的含义（通过测试或标准）并检查它。

**迭代规范本身**：如果你发现规范不完整或不清楚（也许智能体误解了某些东西，或者你意识到你遗漏了一个需求），更新规范文档。然后明确地将智能体与新规范重新同步："我已按如下方式更新了规范……鉴于更新的规范，相应地调整计划或重构代码。"这样规范仍然是唯一的真相来源。这类似于我们在正常开发中如何处理不断变化的需求——但在这种情况下，你也是你的 AI 智能体的产品经理。如果可能，保留版本历史（即使只是通过提交消息或笔记），这样你就知道什么改变了以及为什么。

**利用上下文管理和内存工具**：有一个不断增长的工具生态系统来帮助管理 AI 智能体上下文和知识。例如，检索增强生成（RAG）是一种模式，智能体可以根据需要从知识库（如向量数据库）中提取相关数据块。如果你的规范很大，你可以嵌入它的部分，让智能体在需要时检索最相关的部分，而不是总是提供整个内容。还有一些框架实现了模型上下文协议（MCP），它根据当前任务自动向模型提供正确的上下文。一个例子是 [Context7](https://docs.digitalocean.com/products/gradient-ai-platform/concepts/context-management/)（context7.com），它可以根据你正在处理的内容从文档中自动获取相关的上下文片段。实际上，这可能意味着智能体注意到你正在处理"支付处理"，它会将你的规范或文档的"支付"部分拉入提示。考虑利用这些工具或设置一个基本版本（甚至是规范文档中的简单搜索）。

**谨慎并行化**：一些开发者在不同任务上并行运行多个智能体实例（如前面提到的子智能体）。这可以加快开发速度——例如，一个智能体生成代码，而另一个同时编写测试，或者并发构建两个功能。如果你走这条路，确保任务真正独立或明确分离以避免冲突（规范应该注明任何依赖关系）。例如，不要让两个智能体同时写入同一个文件。一个工作流是让一个智能体生成代码，另一个并行审查它，或者让单独的组件构建后来集成。这是高级用法，管理起来可能精神上很累（正如 Willison 承认的，运行多个智能体[令人惊讶地有效，如果精神上令人疲惫](https://simonwillison.net/2025/Oct/7/vibe-engineering/)！）。最多从 2-3 个智能体开始以保持可管理性。

**版本控制和规范锁定**：使用 Git 或你选择的版本控制来跟踪智能体所做的事情。[良好的版本控制习惯](https://simonwillison.net/2025/Oct/7/vibe-engineering/)在 AI 辅助下更重要。将规范文件本身提交到仓库。这不仅保留了历史，智能体甚至可以使用 git diff 或 blame 来理解更改（LLM 非常擅长阅读差异）。一些高级智能体设置让智能体查询 VCS 历史以查看何时引入了某些东西——令人惊讶的是，模型可以"在 Git 上非常有能力"。通过将你的规范保留在仓库中，你允许你和 AI 跟踪演变。有一些工具（如前面提到的 GitHub Spec Kit）将规范驱动开发集成到 git 工作流中——例如，在更新的规范上门控合并或从规范项目生成检查清单。虽然你不需要这些工具来成功，但要点是像对待代码一样对待规范——勤勉地维护它。

**成本和速度考虑**：使用大型模型和长上下文可能很慢且昂贵。一个实用的技巧是明智地使用模型选择和批处理。也许对初始草稿或重复使用更便宜/更快的模型，并为最终输出或复杂推理保留最有能力（和昂贵）的模型。一些开发者使用 GPT-4 或 Claude 进行规划和关键步骤，但将更简单的扩展或重构卸载到本地模型或更小的 API 模型。如果使用多个智能体，也许不是所有智能体都需要是顶级的；测试运行智能体或 linter 智能体可以是更小的模型。还要考虑限制上下文大小：如果 5k 就够了，不要提供 20k token。正如我们讨论的，[更多 token 可能意味着收益递减](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)。

**监控和记录一切**：在复杂的智能体工作流中，记录智能体的行动和输出至关重要。检查日志以查看智能体是否偏离或遇到错误。许多框架提供跟踪日志或允许打印智能体的思维链（特别是如果你提示它逐步思考）。审查这些日志可以突出显示规范或指令可能被误解的地方。这与调试程序没有什么不同——除了"程序"是对话/提示链。如果发生奇怪的事情，回到规范/指令，看看是否有歧义。

**学习和改进**：最后，将每个项目视为完善你的规范编写技能的学习机会。也许你会发现某种措辞始终让 AI 感到困惑，或者以某种方式组织规范部分会产生更好的遵守。将这些经验教训纳入下一个规范。AI 智能体领域正在快速发展，因此新的最佳实践（和工具）不断出现。通过博客（如 Simon Willison、Andrej Karpathy 等的博客）保持更新，不要犹豫进行实验。

AI 智能体的规范从来不是“写一次就结束”的文档，而是指导、验证与迭代的循环节点。你越早发现问题、越持续地校准方向，后面返工的代价就越低。有人会半开玩笑地把这种体验比作“同时管理一批执行力很强、但边界必须写清楚的助手”；比喻归比喻，真正起作用的还是规范、反馈与审查机制。

## **5. 避免常见陷阱**

在结束之前，值得指出可能破坏即使是善意的规范驱动工作流的反模式。[GitHub 对 2?500+ 智能体文件的研究](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)揭示了一个鲜明的分歧："大多数智能体文件失败是因为它们太模糊。"以下是要避免的错误：

**模糊的提示**："给我构建一些很酷的东西"或"让它工作得更好"没有给智能体任何锚定点。正如 Baptiste Studer 所说："模糊的提示意味着错误的结果。"对输入、输出和约束要具体。"你是一个有用的编码助手"不起作用。"你是一个为 React 组件编写测试的测试工程师，遵循这些示例，永远不要修改源代码"起作用。

**没有总结的过长上下文**：将 50 页文档倾倒到提示中并希望模型弄清楚很少起作用。使用分层摘要（如原则 3 中讨论的）或 RAG 仅显示相关内容。上下文长度不能替代上下文质量。

**跳过人工审查**：Willison 有一个个人规则：“我不会提交我无法向别人解释的代码。”仅仅因为智能体产出的内容通过了测试，并不意味着它就一定正确、安全或可维护。始终审查关键代码路径。“纸牌屋”这个比喻依然成立：有些代码表面上很稳，但一旦遇到你尚未覆盖的边界情况，就会迅速暴露问题。

**将 vibe coding 与生产工程混为一谈**：使用 AI 进行快速原型设计（"vibe coding"）非常适合探索和一次性项目。但在没有严格的规范、测试和审查的情况下将该代码发送到生产是自找麻烦。我区分"vibe coding"和"AI 辅助工程"——后者需要本指南描述的纪律。知道你处于哪种模式。

**忽略“致命三要素”**：Willison 提醒我们，AI 协作里有三个必须正视的因素：速度（它生成得可能比你审得还快）、非确定性（相同输入未必得到相同输出）和成本（容易诱使人减少验证步骤）。你的规范和审查流程必须把这三点都算进去，不要让生成速度跑在验证能力前面。

**遗漏六个核心领域**：如果你的规范没有涵盖命令、测试、项目结构、代码风格、git 工作流和边界，你可能遗漏了智能体需要的东西。在将其交给智能体之前，使用第 2 节中的六个领域检查清单作为健全性检查。

## **结论**

为 `Coding Agents` 写出真正有效的规范，靠的仍然是扎实的软件工程基本功，再加上一点对 LLM 工作方式的理解。先把目标讲清楚，再让模型帮你扩展计划；把规范写成可以执行、可以校验的工程工件，而不只是漂亮散文；把大任务拆成模型能稳定处理的小块；再用“始终做 / 先询问 / 永远不要”的边界、自检机制与一致性测试，尽量降低跑偏概率。整个过程本质上是迭代式的：规范、实现、测试、反馈，循环推进。

遵循这些原则后，你的 AI 智能体在长上下文里失焦、跑偏或反复返工的概率都会明显下降。

祝规范编写愉快！

_这篇文章使用 Gemini 格式化，图像使用 Nano Banana Pro 生成_

---

_我很高兴分享我与 O'Reilly 发布了一本新的 [AI 辅助工程书籍](https://beyond.addy.ie/)。如果感兴趣，书籍网站上有一些免费提示。_