神译局是36氪旗下编译团队，关注科技、商业、职场、生活等领域，重点介绍国外的新技术、新观点、新风向。
编者按：别再给Agent塞长文档了！掌握这套“数字实习生”管理框架，是让AI从玩具进化为生产力的硬核关键。
目标是编写一份清晰的规范，涵盖恰到好处的细节（包括结构、风格、测试和边界），在引导 AI 的同时避免信息过载。将大任务拆解为小任务，而不是把所有内容都塞进一个庞大的提示词中。先在“只读模式”下进行规划，然后再执行并持续迭代。
“我听过很多关于如何为 AI Agent 编写优秀规范的建议，但始终没发现一套成熟的框架。我也能写出堪比 RFC（征求意见稿）的详尽规范，但一旦上下文过长，模型就会开始‘罢工’。”
许多开发者都有这种挫败感。粗暴地将一份冗长的规范丢给 AI Agent 是行不通的——上下文窗口的限制和模型的“注意力预算”会成为阻碍。关键在于编写“聪明”的规范：这些文档既能清晰地引导 Agent，又能保持在实际的上下文容量内，并随项目同步演进。本指南总结了我在使用 Claude Code 和 Gemini CLI 等开发 Agent 的过程中的最佳实践，提炼出一套规范编写框架，旨在让你的 AI Agent 保持专注且高效。
我们将介绍编写优秀 AI Agent 规范的五项原则，每项原则都以加粗的要点开头。
用一份简练的概要规范启动项目，把细节交给 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 在随后进入编码阶段时“只见树木不见森林”。
将你的 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
*
发布时间：2026-03-24 08:24
立即订购
在线咨询
返回顶部