TL;DR：写一份清晰的规格说明，涵盖恰到好处的细节（可包括结构、风格、测试、边界），既能指导 AI，又不会让它不堪重负。把大任务拆成小任务，而不是全部塞进一条超长提示里。先用只读模式做规划，再持续执行与迭代。**
“我常听说要给 AI 智能体写好的规格说明，但一直没找到靠谱的框架。规格可以写得像 RFC 一样细，但到某个程度上下文太大，模型就崩了。”
很多开发者都有这种挫败感。把一大份规格扔给 AI 智能体并不管用——上下文长度和模型的「注意力预算」会拖后腿。关键是写聪明的规格：能清晰引导智能体、控制在可行上下文内、并随项目演进的文档。本文把我使用 Claude Code、Gemini CLI 等编程智能体的经验提炼成一套规格撰写框架，让你的 AI 智能体既专注又高效。
我们会讲五条原则，每条都以加粗的要点开头。
1. 从高层愿景出发，让 AI 补充细节
用一份简洁的高层规格启动项目，再让 AI 据此展开成详细计划。
不要一开始就过度设计，而是先写清目标陈述和几条核心需求，把它当成「产品简报」，再让智能体据此生成更完整的规格。这样既发挥 AI 在展开细节上的优势，又由你掌控方向。除非你一开始就有非常具体、必须满足的技术要求，否则这种做法通常很有效。
为什么有效： 基于 LLM 的智能体在拿到明确的高层指令后，很擅长把细节补全，但需要清晰的使命才不会跑偏。给出一份简短提纲或目标描述，再让 AI 生成完整规格（例如 <code>spec.md</code>），你就得到一份智能体可以持续参照的文档。提前规划对智能体尤其重要——你可以先反复打磨计划，再交给智能体写代码。这份规格会成为你和 AI 一起产出的第一件制品。
具体做法： 开启新的编程会话时，可以这样提示：「你是一名 AI 软件工程师。请为 [项目 X] 起草一份详细规格说明，涵盖目标、功能、约束以及分步计划。」初始提示保持高层即可，例如：「做一个任务跟踪 Web 应用（待办列表），需要用户账号、数据库和简单 UI」。智能体可能会给出一份结构化草稿：概述、功能列表、技术栈建议、数据模型等。这份规格随后成为你和智能体共同参照的「单一事实来源」。GitHub 的 AI 团队推崇规格驱动开发：「规格成为共享的单一事实来源……随项目演进的、可执行的活文档」。在写任何代码之前，先审阅并修正 AI 的规格，确保符合你的设想，并纠正幻觉或偏离的细节。
用「规划模式」强制先规划再写代码： Claude Code 等工具提供规划模式，限制智能体只能做只读操作——可以分析代码库、制定详细计划，但在你准备好之前不会写代码。规划阶段非常适合这样用：在规划模式（Claude Code 中按 Shift+Tab）下描述你想做什么，让智能体在浏览现有代码的同时起草规格。让它通过向你提问来澄清歧义，并请它从架构、最佳实践、安全风险、测试策略等角度审查计划，直到没有误解空间，再退出规划模式让智能体执行。这套流程能避免「规格还没稳就急着写代码」的常见坑。
把规格当上下文用： 规格通过后，保存下来（例如 <code>SPEC.md</code>），在需要时把相关段落喂给智能体。很多使用强模型的开发者就是这么做的——规格文件在会话之间持久存在，每次继续做这个项目时都能把 AI 拉回正轨，缓解对话历史过长或重启智能体后的「遗忘」。这很像团队里用产品需求文档（PRD）：人（或 AI）都能查阅的参照物。有经验的工程师会说：「先把文档写好，模型有时仅凭这些输入就能写出匹配的实现。」规格就是那份文档。
保持目标导向： 给 AI 智能体的高层规格应聚焦「做什么」和「为什么」，先少纠结「怎么做」。可以类比用户故事和验收标准：用户是谁？需要什么？成功长什么样？（例如：「用户能新增、编辑、完成任务；数据持久保存；应用响应式且安全」）。这样 AI 展开的详细规格会锚定在用户需求和结果上，而不只是技术待办。正如 GitHub Spec Kit 文档所说：提供你要做的东西以及原因的高层描述，让编程智能体生成聚焦用户体验和成功标准的详细规格。从这种大图景出发，能避免智能体后来写代码时「见树不见林」。
2. 按专业 PRD（或 SRS）的结构组织规格
把给智能体的规格当成结构化文档（PRD），分节清晰，而不是一堆零散笔记。
很多开发者给智能体的规格会沿用传统产品需求文档（PRD）或系统设计文档的写法——完整、有条理、便于「较真」的 AI 解析。这种正式写法给智能体一份可执行的蓝图，减少歧义。
六个核心区域： GitHub 对 2,500+ 个智能体配置文件的统计显示，最有效的规格都覆盖六个方面。可以当作完整性检查清单：
1. 命令： 把可执行命令放在前面——不仅是工具名，而是带参数的全量命令：<code>npm test</code>、<code>pytest -v</code>、<code>npm run build</code>。智能体会反复用到这些。
2. 测试： 如何跑测试、用的什么框架、测试文件放在哪、对覆盖率有什么期望。
3. 项目结构： 源码在哪、测试在哪、文档在哪。写清楚：例如「<code>src/</code> 放应用代码，<code>tests/</code> 放单元测试，<code>docs/</code> 放文档」。
4. 代码风格： 一段真实代码示例胜过三段文字描述。包含命名约定、格式规则以及「好输出」的示例。
5. Git 工作流： 分支命名、提交信息格式、PR 要求。写清楚后智能体可以照做。
6. 边界： 智能体绝对不能动的东西——密钥、vendor 目录、生产配置、特定文件夹。在这项 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、加依赖、改 CI 配置
- 🚫 禁止：提交密钥、编辑 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 等工具中，可以写 <code>agents.md</code>，定义专门智能体角色——例如 @docs-agent 负责技术写作、@test-agent 负责 QA、@security-agent 负责代码审查。每个文件相当于该角色的行为、命令和边界的聚焦规格，适合「不同任务用不同智能体」而不是一个通用助手。
为智能体体验（AX）设计： 就像我们为开发者体验（DX）设计 API，也可以为「智能体体验」设计规格。即：干净、可解析的格式；智能体要调用的 API 用 OpenAPI 描述；用 llms.txt 等为 LLM 汇总文档；显式类型定义。Agentic AI Foundation（AAIF）正在标准化 MCP（Model Context Protocol）等工具集成协议——按这些模式写的规格更容易被智能体稳定消费和执行。
PRD 与 SRS 的思维： 借鉴成熟文档实践会有帮助。给 AI 智能体的规格往往会把 PRD 和 SRS 合在一份文档里（如上例），但两个角度都照顾到会更稳。按 PRD 写能保证有用户视角（「每个功能背后的为什么」），避免 AI 优化错目标。按 SRS 展开能落实 AI 真正生成正确代码所需的细节（用什么库、什么 API）。很多开发者发现，这点前期投入能大幅减少后续与智能体的误解。
让规格成为「活文档」： 不要写完就忘。随你和智能体做决策或发现新信息而更新规格。若 AI 改了数据模型或你决定砍掉某功能，在规格里同步，让它始终是事实来源。可以当成受版本控制的文档。在规格驱动流程里，规格驱动实现、测试和任务拆分，规格未验证前不进入编码。这个习惯能保持项目一致，尤其在你或智能体离开一阵再回来时。记住，规格不只为 AI——也帮你保持 oversight，确保 AI 的产出符合真实需求。
3. 把任务拆成模块化提示与上下文，而不是一条巨型提示
分而治之：一次只给 AI 一个聚焦任务，而不是把一切塞进一条大提示里。
有经验的 AI 工程师已经学到：把整个项目（所有需求、所有代码、所有说明）塞进一条提示或一条智能体消息，很容易混乱。不仅可能撞上 token 上限，还会触发「指令诅咒」——指令太多，模型反而哪条都执行不好。解决办法是把规格和工作流设计成模块化：一次只处理一块，只注入该块需要的上下文。
过多上下文/指令的诅咒： 研究印证了很多开发者的直观感受：往提示里堆的指令或数据越多，模型对每条指令的遵守程度会明显下降。有研究称之为「指令诅咒」，即使 GPT-4 和 Claude 在同时满足大量要求时也会吃力。实践中，如果你给出 10 条详细规则，AI 可能只认真遵守前几条，后面的开始忽略。更好的策略是迭代聚焦。业界指南建议把复杂需求分解成顺序的、简单的指令作为最佳实践。一次让 AI 专注一个子问题，做完再下一个，这样质量高、错误可控。
按阶段或组件拆分规格： 若规格很长或覆盖很多方面，可以拆成几部分（独立文件或清晰分节）。例如可以有「后端 API 规格」和「前端 UI 规格」。做后端时不必总把前端规格喂给 AI，反之亦然。不少使用多智能体的人会为每块配置单独智能体或子流程——例如一个负责数据库/schema、一个负责 API 逻辑、一个负责前端，各自只看相关那部分规格。即使用单一智能体，也可以每次只把相关规格段落复制进当前任务的提示里。避免上下文过载：如 DigitalOcean AI 指南所提醒的，不要把认证任务和数据库 schema 变更混在一次；每条提示都紧扣当前目标。
大规格用扩展目录/摘要： 一个实用技巧是让智能体为规格建「扩展目录 + 每节摘要」。这相当于把每节压缩成几个要点或关键词，并标明细节在哪。例如若规格里「安全要求」有 500 字，可以让智能体摘要成：「安全：使用 HTTPS、保护 API 密钥、做输入校验（详见规格 §4.2）」。在规划阶段建好这种层级摘要，你既有鸟瞰图可以常驻提示，细节则按需再取。扩展目录相当于索引：智能体可以查一下说「哦，有安全这一节该看看」，你再按需提供该节。类似人类开发者先扫一眼提纲，再翻到规格的某一页。
实现上可以在写完规格后这样提示智能体：「把上面规格总结成非常简洁的提纲，每节标出要点和引用标签。」结果可能是带一两句摘要的章节列表，这份摘要可以放在系统或助手消息里，在不占太多 token 的前提下引导智能体注意力。这种层级摘要已知能帮助 LLM 通过关注高层结构来维持长期上下文，智能体相当于带着规格的「心智地图」。
用子智能体或「技能」承载不同规格部分： 另一种进阶做法是用多个专门智能体（Anthropic 称为 subagent，或可称为「技能」）。每个子智能体只负责一个领域，只拿到规格中相关部分。例如可以有一个「数据库设计」子智能体只看数据模型那节，一个「API 编码」子智能体只看 API 端点规格。主智能体（或编排器）把任务路由到对应子智能体。好处是每个智能体面对的上下文更小、角色更聚焦，能提高准确率并支持独立任务并行。Anthropic 的 Claude Code 支持为子智能体定义各自的系统提示和工具。「每个子智能体有明确目的和专长领域，使用独立于主对话的上下文，并有自定义系统提示指导行为。」当任务落到某子智能体领域时，Claude 可以把任务委派给它，子智能体独立返回结果。
并行智能体提高吞吐： 同时跑多个智能体正在成为「下一波」开发效率热点。不必等一个智能体全部做完再开下一个，可以对不重叠的工作开并行智能体。Willison 称之为「拥抱并行编程智能体」，并说「效果出奇好，虽然心很累」。关键是划清任务边界，避免互相踩脚——例如一个写功能、一个写测试，或不同组件并行开发。LangGraph、OpenAI Swarm 等编排框架可以协调这些智能体，用向量库（如 Chroma）做共享记忆，让它们访问共同上下文而不用重复塞提示。
单智能体 vs 多智能体：何时用哪种
| 维度 | 单智能体 | 并行/多智能体 |
|---|---|---|
| 优势 | 配置简单、开销小、易调试、易跟踪 | 吞吐高、能处理复杂依赖、按领域分工 |
| 挑战 | 大项目上容易上下文过载、迭代慢、单点故障 | 协调成本、可能冲突、需要共享记忆（如向量库） |
| 适合 | 独立模块、中小项目、早期原型 | 大代码库、一个写代码一个写测试一个做审查、独立功能 |
| 建议 | 用规格摘要、按任务刷新上下文、多开新会话 | 先限制在 2–3 个智能体、用 MCP 共享工具、边界写清 |
实践中，用子智能体或按技能拆提示可以这样：你维护多份规格（或提示模板），例如 <code>SPEC_backend.md</code>、<code>SPEC_frontend.md</code>，然后告诉 AI：「做后端时看 SPEC_backend，做前端时看 SPEC_frontend。」或在 Cursor/Claude 里真的为每种起一个子智能体。这比单智能体循环复杂，但模仿了人类开发者的做法——我们也会在心里把大规格拆成相关块（你不会一次把 50 页规格全记着，只提取当前任务需要的部分，并对整体架构有个大致印象）。难点是依赖：子智能体之间仍要协调（前端需要知道后端规格里的 API 契约等），一个总览（或「架构师」智能体）可以引用各子规格并保证一致。
每条提示只聚焦一个任务/一节： 即使没有多智能体，也可以手动保持模块化。例如规格写完后，下一步可以是：「第一步：实现数据库 schema。」只喂给智能体规格里的「数据库」那一节，加上任何全局约束（如技术栈）。智能体只做这块。然后第二步「实现认证功能」时，只提供规格里的「认证」节以及需要的 schema 部分。通过为每个主要任务刷新上下文，避免模型带着大量陈旧或无关信息导致分心。有指南建议：「重新开会话：在切换主要功能时开新会话以清空上下文。」每次可以重申规格里「约束」部分的关键规则，但若用不到整份规格，就不要全塞进去。
用行内指令和代码 TODO： 另一种模块化技巧是把代码或规格当作对话的主动部分。例如用 <code>// TODO</code> 注释搭好骨架，描述要做什么，再让智能体一个一个填。每个 TODO 相当于一个小任务的迷你规格，让 AI 高度聚焦（「按这段规格实现这个具体函数」），形成紧密迭代。类似于每次只给 AI 一个清单项，而不是整张清单。
结论：小范围、聚焦的上下文优于一条巨型提示。这样质量更好，AI 也不会被一次塞太多东西「压垮」。正如某最佳实践所说：给模型「一次只做一件事」和「只给相关信息」，避免到处倾倒一切。通过把工作拆成模块——并用规格摘要或子规格智能体等策略——你既能绕开上下文长度限制，又能应对 AI 的短期记忆上限。记住，喂得好就像函数参数设计得好：只给它当前任务需要的输入。
4. 在规格中内置自检、约束与人的专业判断
让规格不仅是智能体的待办清单，还是质量控制的指南——并大胆注入你自己的经验。
好的 AI 智能体规格会预判 AI 可能出错的地方并设好护栏，同时利用你知道的东西（领域知识、边界情况、「坑」）让 AI 不是在真空中干活。可以把规格同时当成 AI 的教练和裁判：既鼓励正确做法，也明确犯规。
用三层边界： GitHub 对 2,500+ 个智能体配置文件的分析发现，最有效的规格用的不是简单「禁止清单」，而是三层边界，让智能体更清楚何时可以继续、何时要停、何时必须停：
✅ 始终做： 智能体无需询问就该执行的动作。「提交前始终跑测试。」「始终遵守风格指南中的命名约定。」「始终把错误打到监控服务。」
⚠️ 先问再做： 需要人工批准的动作。「改数据库 schema 前先问。」「加新依赖前先问。」「改 CI/CD 配置前先问。」这一层能兜住高影响变更——可能没问题，但值得人看一眼。
🚫 绝不做： 硬性禁止。「绝不提交密钥或 API Key。」「绝不编辑 node_modules/ 或 vendor/。」「绝不在没有明确批准的情况下删掉失败的测试。」在这项研究中，「绝不提交密钥」是最常见且最有用的约束。
三层比一维规则更细腻：有的动作永远安全，有的需要监督，有的绝对禁止。智能体在「始终」项上可以放心执行，在「先问」项上会提请审查，在「绝不做」项上直接停。
鼓励自检： 一个有力模式是让智能体根据规格自动核对自己的产出。若工具支持，可以接入单元测试或 lint，让 AI 在生成代码后自己跑。即便只在规格/提示层面，也可以要求 AI 自检，例如：「实现完成后，对照规格确认所有要求是否满足，并列出未覆盖的规格项。」这促使 LLM 根据规格反思输出，减少遗漏，相当于流程里内置了自审。
例如可以在提示末尾加：「（写完函数后，回顾上述需求列表，确保每一条都满足，并标出未满足的项）。」模型会（理想情况下）先输出代码，再给出一份短清单说明是否满足每条要求，在你还未跑测试前就降低遗漏概率。虽不完美，但有帮助。
用「LLM 当裁判」做主观检查： 对难以自动测试的标准——代码风格、可读性、对架构模式的遵守——可以考虑「LLM 当裁判」：用另一个智能体（或另一条提示）根据规格里的质量准则审查第一个智能体的输出。Anthropic 等发现这对主观评估很有效。可以这样提示：「根据我们的风格指南审查这段代码，标出所有违规。」裁判智能体返回反馈，要么被采纳，要么触发修改，在语法检查之外增加一层语义评估。
一致性测试： Willison 主张建一致性测试套件——与语言无关的测试（常用 YAML），任何实现都必须通过。它们相当于契约：若你在做 API，一致性套件规定期望的输入/输出，智能体的代码必须通过所有用例。这比零散的单元测试更严格，因为直接来自规格且可在不同实现间复用。在规格的「成功标准」里写上一致性标准（例如「必须通过 conformance/api-tests.yaml 中所有用例」）。
在规格里用好测试： 若可能，在规格和提示流里纳入测试计划甚至具体测试。传统开发里我们用 TDD 或写测试用例来澄清需求，对 AI 也可以。例如在规格的「成功标准」里写「以下示例输入应产生以下输出……」或「以下单元测试应通过」。智能体可以在脑中跑一遍，若有能力也可以实际执行。Simon Willison 说，有一套扎实的测试就像给智能体超能力——测试失败时它们可以快速验证和迭代。在 AI 编程场景下，在规格里写一点测试伪代码或期望结果能引导智能体实现。此外可以用专门的「测试智能体」作为子智能体，根据规格的准则持续验证「代码智能体」的产出。
注入领域知识： 规格应体现只有有经验的开发者或知情者才知道的东西。例如若你在做电商相关智能体，且知道「商品」和「类目」是多对多关系，在规格里写清楚（不要假设 AI 能推断——它可能不会）。若某库 notoriously 难用，写明要避开的坑。本质上把你在带人时的经验写进规格。规格里可以有类似建议：「若用库 X，注意 Y 版本的内存泄漏（采用 workaround Z）。」这种细节能把普通 AI 产出变成更稳健的方案，因为你提前把 AI 从常见陷阱旁引开。
若你有偏好或风格（例如「React 里用函数组件而不是类组件」），也写进规格，AI 会模仿你的风格。很多工程师还会在规格里放小例子，例如「所有 API 响应为 JSON，错误示例：{"error": "message"}。」一个简单例子就能把 AI 锚定在你想要的格式上。
简单任务从简： 我们主张规格要到位，但专业判断也包括知道何时从简。对相对简单、孤立的任务，过重的规格反而容易干扰。若只是让智能体做「把 div 居中」这种事，说一句「保持方案简洁，不要加多余标记或样式」可能就够了，用不着完整 PRD。反之，对复杂任务（例如「实现带 token 刷新和错误处理的 OAuth 流程」），再搬出详细规格。经验法则：规格的详细程度与任务复杂度匹配。不要对难题规格不足（智能体会乱试或跑偏），也不要对 trivial 任务规格过剩（智能体可能被缠住或浪费上下文）。
必要时维护 AI 的「人设」： 有时规格的一部分是定义智能体该如何表现或回应，尤其当智能体直接面对用户时。例如若做一个客服智能体，规格里可以有：「语气友好、专业」「若不确定答案，先澄清或承诺跟进，不要瞎猜。」这类规则（常放在系统提示里）让 AI 的输出符合预期，本质上是对 AI 行为的规格项。保持一致，长会话中必要时提醒模型（否则 LLM 的风格可能随时间漂移）。
你始终是「人在回路」的决策者： 规格赋予智能体能力，但最终的质量把关还是你。若智能体产出的东西技术上符合规格但你觉得不对，相信自己的判断，要么改规格要么直接改产出。AI 智能体的好处是不会「记仇」——若设计不符合预期，你可以说「其实我不是这个意思，我们把规格澄清一下再重做」。规格是你和 AI 协作中的活制品，不是一次写好就不能改的合同。
Simon Willison 调侃说，和 AI 智能体合作像「一种非常奇怪的管理」，甚至「从编程智能体那里拿到好结果，感觉 uncomfortably 接近管一个人类实习生」。你要提供清晰指令（规格）、确保它们有需要的上下文（规格和相关数据）、并给出可执行的反馈。规格搭好舞台，但执行中的监督和反馈同样关键。若 AI 是「一个会趁你给机会就偷懒的奇怪数字实习生」，你写的规格和约束就是防止偷懒、让它待在任务上的手段。
回报是：好的规格不仅告诉 AI 做什么，还帮它自检、待在安全边界内。通过把验证步骤、约束和你积累的经验写进去，能显著提高智能体第一次就做对（或至少接近对）的概率，减少返工和「它怎么会这么干？」的时刻。
5. 测试、迭代并演进规格（并选对工具）
把写规格和建智能体看成迭代环：尽早测试、收集反馈、修正规格，并用工具把检查自动化。
初始规格不是终点，而是循环的起点。当你持续用规格验证智能体产出并据此调整时，结果最好。同时，现代 AI 开发者会用各种工具支撑这个过程——从 CI 流水线到上下文管理工具。
持续测试： 不要等到最后才看智能体是否满足规格。每个重要里程碑甚至每个函数完成后就跑测试或至少快速手测。若有失败，先更新规格或提示再继续。例如若规格写「密码必须用 bcrypt 哈希」，却看到智能体代码存明文——立刻停、纠正，并在规格或提示里再次强调这条规则。自动化测试在这里特别有用：若你提供了测试（或边做边写），让智能体跑。在很多编程智能体设置里，可以让智能体在完成任务后跑 <code>npm test</code> 等，失败结果可以反馈到下一轮提示，相当于告诉智能体「你的产出在 X、Y、Z 上不符合规格，请修」。这种「代码 → 测试 → 修 → 重复」的智能体循环非常有力，也是 Claude Code、Copilot Labs 等处理更大任务的方向。要明确「完成」的定义（通过测试或标准），并检查是否达到。
对规格本身迭代： 若发现规格不完整或不清晰（可能智能体误解了，或你漏了需求），就更新规格文档，然后显式让智能体与新区同步：「我已将规格更新如下……请根据更新后的规格调整计划或重构代码。」这样规格始终是单一事实来源，类似正常开发里应对需求变更，只不过这里你同时也是 AI 智能体的产品经理。若可能保留版本历史（哪怕只是提交信息或笔记），便于知道改了什么、为什么。
用好上下文管理与记忆工具： 有一类工具专门管理 AI 智能体的上下文与知识。例如 RAG（检索增强生成）：智能体按需从知识库（如向量数据库）拉取相关数据块。若规格很大，可以把各节做成向量，让智能体在需要时检索相关部分，而不是每次都塞整份。还有实现 Model Context Protocol（MCP）的框架，能根据当前任务自动把合适上下文喂给模型。例如 Context7（context7.com）可以根据你正在做的工作从文档中自动拉取相关片段。实践中，智能体可能发现你在做「支付处理」，就把规格或文档里的「支付」一节拉进提示。可以考虑用这类工具，或至少做一个简单版（哪怕只是在规格文档里做个简单搜索）。
谨慎并行： 有些开发者会对不同任务并行跑多个智能体实例（前面提到的子智能体）。这能加速开发——例如一个智能体写代码、另一个同时写测试，或两个功能并行做。若走这条路，要确保任务真正独立或边界清晰，避免冲突（规格里应注明依赖）。例如不要让两个智能体同时写同一文件。一种做法是让一个智能体生成代码、另一个并行做审查，或分别做不同组件再集成。这是进阶用法，心智负担也不小（Willison 承认跑多个智能体「效果出奇好，但心很累」）。建议先最多 2–3 个智能体，便于掌控。
版本控制与规格锁定： 用 Git 或你熟悉的版本控制跟踪智能体做了什么。有 AI 协助时，良好的版本控制习惯更重要。把规格文件本身也提交到仓库，既保留历史，智能体也可以用 <code>git diff</code> 或 <code>blame</code> 理解变更（LLM 读 diff 能力不错）。有些进阶设置甚至让智能体查 VCS 历史看某段代码是何时引入的——模型对 Git 可以「非常在行」。把规格放在仓库里，你和 AI 都能跟踪演进。前面提到的 GitHub Spec Kit 等工具把规格驱动开发接到 git 工作流里——例如在合并前检查规格是否更新，或从规格项生成检查清单。虽不必用这些工具才能成功，但要点是：把规格当代码一样认真维护。
成本与速度： 用大模型、长上下文会又慢又贵。实用建议是聪明地选模型和批处理：或许用更便宜/更快的模型做初稿或重复劳动，把最强（也最贵）的模型留给最终产出或复杂推理。有人用 GPT-4 或 Claude 做规划和关键步骤，把简单扩展或重构交给本地模型或更小的 API 模型。若用多智能体，不必全是顶级模型；跑测试或跑 linter 的智能体可以用小模型。同时控制上下文大小：若 5k token 够用就不要喂 20k，更多 token 可能边际收益递减。
全面监控与日志： 在复杂智能体工作流中，记录智能体的动作和输出很重要。通过日志看智能体是否偏离或报错。很多框架提供追踪日志或可以打印 chain-of-thought（尤其若你提示它一步步想）。回顾这些日志能发现规格或指令在哪里被曲解，有点像调试程序——只不过「程序」是对话/提示链。若出现异常，回到规格/指令看看是否有歧义。
持续学习与改进： 把每个项目当成精进规格撰写能力的机会。或许你会发现某种说法总让 AI 困惑，或某种章节组织方式更能被遵守，下次规格就吸收这些经验。AI 智能体领域变化很快，新最佳实践和工具会不断出现，通过 Willison、Karpathy 等人的博客保持更新，并敢于尝试。
给 AI 智能体的规格不是「写一次就完事」，而是指示 → 验证 → 修正的持续循环的一部分。这份投入的回报很大：尽早发现问题、让智能体对齐，能避免后期昂贵的重写或失败。有 AI 工程师打趣说，用好这些实践就像拥有「一支实习生大军」，但你必须管好。一份写得好、持续维护的规格，就是你的管理工具。
避免常见陷阱
收尾前值得点出会毁掉哪怕初衷很好的规格驱动工作流的反模式。GitHub 对 2,500+ 个智能体文件的研究有个鲜明结论：「大多数智能体文件失败是因为太模糊。」要避免这些错误：
模糊的提示： 「给我做个酷的东西」或「让它更好用」给智能体没有任何锚点。正如 Baptiste Studer 所说：「模糊的提示意味着错误的结果。」要对输入、输出和约束具体化。「你是一个有用的编程助手」不够。「你是一名测试工程师，为 React 组件写测试，遵循以下示例，且绝不修改源码」才够。
过长上下文却不做摘要： 把 50 页文档丢进提示指望模型自己理清，很少奏效。用前面说的层级摘要或 RAG，只呈现相关部分。上下文长度不能替代上下文质量。
跳过人工审查： Willison 有个个人原则：「我不会提交自己无法向别人解释的代码。」智能体产出通过测试不代表正确、安全或可维护。关键代码路径一定要审。「纸牌屋」的比喻适用：AI 生成的代码可能看起来没问题，却在你没测到的边界情况下崩塌。
把 vibe coding 和生产工程混为一谈： 用 AI 快速原型（「vibe coding」）适合探索和一次性项目。但若没有严格规格、测试和审查就把代码上线，是在冒险。我把「vibe coding」和「AI 辅助工程」区分开——后者需要本文描述的那种纪律。要知道自己处于哪种模式。
忽视「致命三重奏」： Willison 警告，三个特性会让 AI 智能体变得危险：速度（它们比你审查得快）、非确定性（同样输入不同输出）、成本（让人在验证上偷工减料）。你的规格和审查流程必须同时应对这三者，别让速度超过你能验证的能力。
漏掉六个核心区域： 若规格没有覆盖命令、测试、项目结构、代码风格、Git 工作流和边界，很可能少了智能体需要的东西。把第 2 节的六区检查清单当作交给智能体前的 sanity check。
结语
为 AI 编程智能体写一份有效的规格，需要扎实的软件工程原则，并适应 LLM 的习性。从目的清晰出发，让 AI 帮你展开计划。把规格组织成严肃的设计文档——覆盖六个核心区域，并纳入工具链，使其成为可执行制品而不只是文字。通过一次只喂一块（并善用摘要目录、子智能体或并行编排处理大规格）保持智能体聚焦。用三层边界（始终/先问/绝不做）、自检和一致性测试预判失误——本质上是教 AI 如何不失败。并把整个过程视为迭代：用测试和反馈持续修正规格与代码。
按这些指南来做，你的 AI 智能体会更少在长上下文中「崩掉」或跑偏到无意义输出。
祝规格撰写顺利。