文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载导读当上下文变长、任务变复杂时AI 编码智能体常常写着写着就跑偏。本文整理出一套可复用的规范Spec编写框架从高层愿景出发让 AI 起草细节以 PRD/SRS 的结构化方式组织内容将大任务拆解为模块化提示并用三层边界、自检机制与一致性测试持续校准方向。读者将掌握一套完整的规范驱动开发工作流并能在当前 vibe-vibe 仓库的 PRD 模板、示例项目与测试用例中找到可直接落地的参照。TL;DR写规范的目标是给 AI 一个足够清晰、细节充分、但又不过载的执行依据。需要写清结构、风格、测试和边界把大任务拆成小任务先在只读模式下规划再执行并在过程中持续迭代。很多开发者都有过这种挫败感你明明写出了一份看起来像 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 的详细规范植根于用户需求和结果而不仅仅是技术待办事项。提供你正在构建什么以及为什么的高层描述让编码智能体生成专注于用户体验和成功标准的详细规范。从这个大局愿景开始可以防止智能体在后来进入编码时见树不见林。在当前仓库中你可以直接参考 PRD 模板 来体会高层愿景的落笔方式它从文档状态、更新记录、相关文档这类元信息起步再逐层展开目标、业务流程与功能细节天然就是一份让 AI 有据可依的产品简报。这也印证了本节的核心观点——先把愿景和边界讲清楚再让细节自然生长。2. 像专业 PRD或 SRS一样构建规范将你的 AI 规范视为具有清晰部分的结构化文档PRD而不是松散的笔记堆。许多开发者将智能体的规范视为传统的产品需求文档PRD或系统设计文档——全面、组织良好且易于字面意义地被 AI 解析。这种正式方法为智能体提供了一个蓝图并减少了歧义。六个核心领域GitHub 对超过 2500 个智能体配置文件的分析揭示了一个清晰的模式最有效的规范涵盖六个领域。将此用作完整性检查清单命令尽早放置可执行命令——不仅仅是工具名称而是带有标志的完整命令npm test、pytest -v、npm run build。智能体会不断引用这些。测试如何运行测试、你使用什么框架、测试文件在哪里以及存在什么覆盖率期望。项目结构源代码在哪里、测试去哪里、文档属于哪里。明确说明src/用于应用代码tests/用于单元测试docs/用于文档。代码风格一个真实的代码片段显示你的风格胜过三段描述它的文字。包括命名约定、格式规则和良好输出的示例。Git 工作流分支命名、提交消息格式、PR 要求。如果你详细说明智能体可以遵循这些。边界智能体永远不应该触及的内容——秘密、供应商目录、生产配置、特定文件夹。永远不要提交秘密是最常见的有用约束。在 vibe-vibe 仓库中demo-01-todo项目就是一套活生生的命令 测试 结构样板package.json 的scripts字段明确给出了devnext dev --turbopack、buildnext build、startnext start、testvitest run四条命令测试文件统一放在tests目录应用源码按src/app、src/components、src/db、src/lib、src/store分层组织见 vitest.config.ts 与 drizzle.config.ts。把这样的真实命令与目录约定写进规范智能体就能在每一步自检跑哪个测试、代码放哪。对你的技术栈要具体说React 18 with TypeScript、Vite、Tailwind CSS而不是React 项目。包括版本和关键依赖项。模糊的规范产生模糊的代码。以demo-01-todo为例规范里可以直接写明Next.js 16 React 19 TypeScript 5.9 Tailwind CSS 4 Drizzle ORM Vitest 4package.json精确到版本号智能体就不会凭训练数据里的旧版本惯性写代码。使用一致的格式清晰为王。许多开发者在规范中使用 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 找到信息。将提示组织成不同的部分如background、instructions、tools、output_format等正是出于这个原因——它为模型提供了关于哪些信息属于哪里的强烈提示。记住最小并不一定意味着简短——如果重要不要回避规范中的细节但要保持专注。将规范集成到你的工具链中将规范视为与版本控制和 CI/CD 相关的可执行工件。Spec Kit 使用一个四阶段、门控的工作流使你的规范成为工程流程的中心。不是编写规范然后将其搁置规范驱动实施、检查清单和任务分解。你的主要角色是引导编码智能体完成大部分编写工作。每个阶段都有特定的工作在当前任务完全验证之前你不会进入下一个阶段指定你先描述要做什么和为什么做再让智能体把它扩展成详细规范。这里关注的不是技术栈而是用户旅程、交互方式和成功标准。谁会使用它它解决什么问题用户将如何与它互动先把体验层讲清楚再让智能体补足细节。规划这一步进入技术层。你给出技术栈、架构、限制条件和现实约束智能体据此生成技术计划。如果项目要对接遗留系统、满足合规要求或者必须遵循团队内部规范这些都应在这里讲明。必要时也可以让它同时给出多个方案方便比较取舍。任务智能体会基于规范和计划把工作拆成小而可审查的任务块。每个任务都应该足够具体可以单独实现、单独验证。不是笼统地写做登录系统而是拆成像创建一个验证邮箱格式的注册接口这样的可执行项。实施智能体按任务逐个推进必要时也可以并行处理。这样你审查的就不是一大坨代码而是一组围绕具体问题的集中改动。你的角色也很清楚在每个阶段确认规范是否准确、计划是否考虑了约束、实现是否遗漏边界情况。整个流程的价值就在于它天然带着检查点。这种门控工作流防止了纸牌屋代码——在审查下崩溃的脆弱 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 vs SRS 思维方式从既定的文档实践中借鉴是有帮助的。对于 AI 智能体规范你通常会将这些混合到一个文档中如上所示但涵盖两个角度对你很有帮助。像 PRD 一样编写它可以确保你包含以用户为中心的上下文每个功能背后的原因这样 AI 就不会为错误的事情优化。像 SRS 一样扩展它可以确保你确定 AI 实际生成正确代码所需的细节如使用什么数据库或 API。开发者发现这种额外的前期努力通过大幅减少后来与智能体的误解而得到回报。使规范成为活文档不要写了就忘。随着你和智能体做出决定或发现新信息更新规范。如果 AI 必须更改数据模型或你决定削减功能在规范中反映这一点使其保持为基本事实。把它想象成版本控制的文档。在规范驱动工作流中规范驱动实施、测试和任务分解在规范验证之前你不会进入编码。这种习惯使项目保持连贯特别是如果你或智能体离开后再回来。记住规范不仅仅是为 AI 准备的——它帮助你作为开发者保持监督并确保 AI 的工作满足真正的需求。3. 将任务分解为模块化提示和上下文而不是一个大提示分而治之一次给 AI 一个集中的任务而不是一次性包含所有内容的单一提示。有经验的 AI 工程师已经了解到试图将整个项目所有需求、所有代码、所有指令塞进单个提示或智能体消息是造成混乱的秘诀。你不仅有达到 token 限制的风险还有模型因指令诅咒而失去焦点的风险——太多指令导致它无法很好地遵循任何一个。解决方案是以模块化方式设计你的规范和工作流一次处理一个部分只引入该部分所需的上下文。太多上下文/指令的诅咒研究已经证实了许多开发者从经验中看到的当你在提示中堆积更多指令或数据时模型遵守每个指令的性能显著下降。一项研究将此称为指令诅咒表明即使是 GPT-4 和 Claude 在被要求同时满足许多需求时也会挣扎。实际上如果你提出 10 个详细规则的要点AI 可能会遵守前几个并开始忽略其他的。更好的策略是迭代聚焦。行业指南建议将复杂需求分解为顺序的、简单的指令作为最佳实践。让 AI 一次专注于一个子问题完成它然后继续。这使质量保持高水平错误可管理。将规范分为阶段或组件如果你的规范文档非常长或涵盖很多内容考虑将其分成部分物理上独立的文件或明确独立的部分。例如你可能有一个后端 API 规范部分和另一个前端 UI 规范部分。当它在后端工作时你不需要总是向 AI 提供前端规范反之亦然。许多使用多智能体设置的开发者甚至为每个部分创建单独的智能体或子流程——例如一个智能体处理数据库/架构另一个处理 API 逻辑另一个处理前端——每个都有规范的相关切片。即使你使用单个智能体你也可以通过仅将相关规范部分复制到该任务的提示中来模拟这一点。避免上下文过载不要在一次操作中混合身份验证任务和数据库架构更改。使每个提示紧密限定在当前目标。大型规范的扩展目录/摘要一个聪明的技巧是让智能体为规范构建一个带摘要的扩展目录。这本质上是一个规范摘要将每个部分浓缩为几个关键点或关键词并引用可以找到详细信息的位置。例如如果你的完整规范有一个跨越 500 字的安全需求部分你可能让智能体将其总结为安全使用 HTTPS保护 API 密钥实施输入验证见完整规范 §4.2。通过在规划阶段创建分层摘要你可以获得一个可以保留在提示中的鸟瞰图而精细细节除非需要否则保持卸载。这个扩展目录充当索引智能体可以查阅它并说啊哈有一个我应该看的安全部分然后你可以按需提供该部分。这类似于人类开发者浏览大纲然后在处理特定部分时翻到规范文档的相关页面。要实现这一点你可以在编写规范后提示智能体将上面的规范总结为一个非常简洁的大纲包含每个部分的关键点和参考标签。结果可能是一个部分列表每个部分有一两句摘要。该摘要可以保留在系统或助手消息中以指导智能体的焦点而不会占用太多 token。这种分层总结方法通过关注高层结构帮助 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 就像喂养良好的函数只给它手头工作所需的输入。值得注意的是仓库中收录的姊妹篇 AGENTS.md vs Skills被动上下文为何胜过主动检索 从另一个角度佐证了本节的核心结论Vercel 团队在评估中发现8KB 的AGENTS.md文档索引达到 100% 通过率而按需调用的 Skills 最高只有 79%。这说明少而聚焦、持续可用的上下文管理策略是让智能体稳定遵循规范的前提。4. 建立自检、约束和人类专业知识使你的规范不仅仅是智能体的待办事项列表还是质量控制指南——不要害怕注入你自己的专业知识。一个好的 AI 智能体规范预测 AI 可能出错的地方并设置护栏。它还利用你所知道的领域知识、边缘情况、陷阱这样 AI 就不会在真空中操作。把规范想象成 AI 的教练和裁判它应该鼓励正确的方法并指出犯规。使用三层边界GitHub 对 2500 智能体文件的分析发现最有效的规范使用三层边界系统而不是简单的禁止列表。这为智能体提供了更清晰的指导说明何时继续、何时暂停以及何时停止✅ 始终做智能体应该在不询问的情况下采取的行动。始终在提交前运行测试。始终遵循风格指南中的命名约定。始终将错误记录到监控服务。⚠️ 先询问需要人工批准的行动。修改数据库架构前先询问。添加新依赖项前先询问。更改 CI/CD 配置前先询问。这一层捕获可能没问题但值得人工检查的高影响更改。 永远不要硬停止。永远不要提交秘密或 API 密钥。永远不要编辑 node_modules/ 或 vendor/。未经明确批准永远不要删除失败的测试。永远不要提交秘密是最常见的有用约束。这种三层方法比平面规则列表更细致。它承认某些行动总是安全的某些需要监督某些是绝对禁止的。智能体可以自信地继续始终项目标记先询问项目以供审查并在永远不要项目上硬停止。鼓励自我验证一个强大的模式是让智能体自动根据规范验证其工作。如果你的工具允许你可以集成 AI 可以在生成代码后运行的单元测试或 linting 等检查。但即使在规范/提示级别你也可以指示 AI 进行双重检查例如实施后将结果与规范进行比较并确认满足所有要求。列出任何未解决的规范项目。这推动 LLM 相对于规范反思其输出捕获遗漏。这是内置到流程中的一种自我审计形式。例如你可能在提示后附加编写函数后审查上述需求列表并确保满足每个需求标记任何缺失的需求。然后模型将理想情况下输出代码然后是一个简短的检查清单指示它是否满足每个要求。这减少了在你甚至运行测试之前它忘记某些东西的机会。这不是万无一失的但它有帮助。LLM 作为主观检查的评判者对于难以自动测试的标准——代码风格、可读性、对架构模式的遵守——考虑使用LLM 作为评判者。这意味着让第二个智能体或单独的提示根据你的规范的质量指南审查第一个智能体的输出。Anthropic 和其他人发现这对主观评估有效。你可能会提示根据我们的风格指南审查此代码。标记任何违规。评判者智能体返回反馈这些反馈要么被纳入要么触发修订。这在语法检查之外增加了一层语义评估。一致性测试Willison 提倡构建一致性套件——任何实现都必须通过的、与语言无关的测试通常基于 YAML。这些充当合同如果你正在构建 API一致性套件指定预期的输入/输出智能体的代码必须满足所有情况。这比临时单元测试更严格因为它直接从规范派生可以跨实现重用。在规范的成功部分包含一致性标准例如必须通过 conformance/api-tests.yaml 中的所有情况。在规范中利用测试如果可能在你的规范和提示流程中纳入测试计划甚至实际测试。在传统开发中我们使用 TDD 或编写测试用例来澄清需求——你可以对 AI 做同样的事情。例如在规范的成功标准中你可能会说这些示例输入应该产生这些输出……或以下单元测试应该通过。如果智能体有该能力可以提示它在脑海中运行这些情况或实际执行它们。Simon Willison 指出拥有强大的测试套件就像给智能体超能力——当测试失败时它们可以快速验证和迭代。在 AI 编码上下文中在规范中为测试或预期结果编写一些伪代码可以指导智能体的实现。此外你可以在子智能体设置中使用专用的测试智能体它采用规范的标准并持续验证代码智能体的输出。这正是 vibe-vibe 仓库的实践方式demo-01-todo内置了 todos.test.ts 测试文件配合 vitest.config.ts 的路径别名配置一条npm test即vitest run即可跑完整套用例。把必须通过 todos.test.ts写进规范智能体就有了明确的验收标准与自我验证闭环。带来你的领域知识你的规范应该反映只有有经验的开发者或有上下文的人才知道的见解。例如如果你正在构建电子商务智能体你知道产品和类别有多对多关系请明确说明不要假设 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 管道到上下文管理实用程序。持续测试不要等到最后才看智能体是否满足规范。在每个主要里程碑甚至每个函数之后运行测试或至少进行快速手动检查。如果某些东西失败了在继续之前更新规范或提示。例如如果规范说密码必须用 bcrypt 哈希你看到智能体的代码存储明文——停止并纠正它并提醒规范或提示关于规则。自动化测试在这里大放异彩如果你提供了测试或在进行时编写它们让智能体运行它们。在许多编码智能体设置中你可以让智能体在完成任务后运行npm test或类似命令。结果失败然后可以反馈到下一个提示有效地告诉智能体你的输出在 X、Y、Z 上不符合规范——修复它。这种智能体循环代码 - 测试 - 修复 - 重复非常强大。始终定义完成的含义通过测试或标准并检查它。迭代规范本身如果你发现规范不完整或不清楚也许智能体误解了某些东西或者你意识到你遗漏了一个需求更新规范文档。然后明确地将智能体与新规范重新同步我已按如下方式更新了规范……鉴于更新的规范相应地调整计划或重构代码。这样规范仍然是唯一的真相来源。这类似于我们在正常开发中如何处理不断变化的需求——但在这种情况下你也是你的 AI 智能体的产品经理。如果可能保留版本历史即使只是通过提交消息或笔记这样你就知道什么改变了以及为什么。利用上下文管理和内存工具有一个不断增长的工具生态系统来帮助管理 AI 智能体上下文和知识。例如检索增强生成RAG是一种模式智能体可以根据需要从知识库如向量数据库中提取相关数据块。如果你的规范很大你可以嵌入它的部分让智能体在需要时检索最相关的部分而不是总是提供整个内容。还有一些框架实现了模型上下文协议MCP它根据当前任务自动向模型提供正确的上下文。一个例子是 Context7它可以根据你正在处理的内容从文档中自动获取相关的上下文片段。实际上这可能意味着智能体注意到你正在处理支付处理它会将你的规范或文档的支付部分拉入提示。考虑利用这些工具或设置一个基本版本甚至是规范文档中的简单搜索。谨慎并行化一些开发者在不同任务上并行运行多个智能体实例如前面提到的子智能体。这可以加快开发速度——例如一个智能体生成代码而另一个同时编写测试或者并发构建两个功能。如果你走这条路确保任务真正独立或明确分离以避免冲突规范应该注明任何依赖关系。例如不要让两个智能体同时写入同一个文件。一个工作流是让一个智能体生成代码另一个并行审查它或者让单独的组件构建后来集成。这是高级用法管理起来可能精神上很累正如 Willison 承认的运行多个智能体令人惊讶地有效如果精神上令人疲惫。最多从 2-3 个智能体开始以保持可管理性。版本控制和规范锁定使用 Git 或你选择的版本控制来跟踪智能体所做的事情。良好的版本控制习惯在 AI 辅助下更重要。将规范文件本身提交到仓库。这不仅保留了历史智能体甚至可以使用git diff或blame来理解更改LLM 非常擅长阅读差异。一些高级智能体设置让智能体查询 VCS 历史以查看何时引入了某些东西——令人惊讶的是模型可以在 Git 上非常有能力。通过将你的规范保留在仓库中你允许你和 AI 跟踪演变。虽然你不需要这些工具来成功但要点是像对待代码一样对待规范——勤勉地维护它。成本和速度考虑使用大型模型和长上下文可能很慢且昂贵。一个实用的技巧是明智地使用模型选择和批处理。也许对初始草稿或重复使用更便宜/更快的模型并为最终输出或复杂推理保留最有能力和昂贵的模型。一些开发者使用 GPT-4 或 Claude 进行规划和关键步骤但将更简单的扩展或重构卸载到本地模型或更小的 API 模型。如果使用多个智能体也许不是所有智能体都需要是顶级的测试运行智能体或 linter 智能体可以是更小的模型。还要考虑限制上下文大小如果 5k 就够了不要提供 20k token。更多 token 可能意味着收益递减。监控和记录一切在复杂的智能体工作流中记录智能体的行动和输出至关重要。检查日志以查看智能体是否偏离或遇到错误。许多框架提供跟踪日志或允许打印智能体的思维链特别是如果你提示它逐步思考。审查这些日志可以突出显示规范或指令可能被误解的地方。这与调试程序没有什么不同——除了程序是对话/提示链。如果发生奇怪的事情回到规范/指令看看是否有歧义。学习和改进最后将每个项目视为完善你的规范编写技能的学习机会。也许你会发现某种措辞始终让 AI 感到困惑或者以某种方式组织规范部分会产生更好的遵守。将这些经验教训纳入下一个规范。AI 智能体领域正在快速发展因此新的最佳实践和工具不断出现。通过持续阅读与实验保持你的方法更新。AI 智能体的规范从来不是写一次就结束的文档而是指导、验证与迭代的循环节点。你越早发现问题、越持续地校准方向后面返工的代价就越低。有人会半开玩笑地把这种体验比作同时管理一批执行力很强、但边界必须写清楚的助手比喻归比喻真正起作用的还是规范、反馈与审查机制。5. 避免常见陷阱在结束之前值得指出可能破坏即使是善意的规范驱动工作流的反模式。GitHub 对 2500 智能体文件的研究揭示了一个鲜明的分歧大多数智能体文件失败是因为它们太模糊。以下是要避免的错误模糊的提示给我构建一些很酷的东西或让它工作得更好没有给智能体任何锚定点。正如 Baptiste Studer 所说模糊的提示意味着错误的结果。对输入、输出和约束要具体。你是一个有用的编码助手不起作用。你是一个为 React 组件编写测试的测试工程师遵循这些示例永远不要修改源代码起作用。没有总结的过长上下文将 50 页文档倾倒到提示中并希望模型弄清楚很少起作用。使用分层摘要如原则 3 中讨论的或 RAG 仅显示相关内容。上下文长度不能替代上下文质量。跳过人工审查Willison 有一个个人规则我不会提交我无法向别人解释的代码。仅仅因为智能体产出的内容通过了测试并不意味着它就一定正确、安全或可维护。始终审查关键代码路径。纸牌屋这个比喻依然成立有些代码表面上很稳但一旦遇到你尚未覆盖的边界情况就会迅速暴露问题。将 vibe coding 与生产工程混为一谈使用 AI 进行快速原型设计vibe coding非常适合探索和一次性项目。但在没有严格的规范、测试和审查的情况下将该代码发送到生产是自找麻烦。本文明确区分vibe coding和AI 辅助工程——后者需要本指南描述的纪律。知道你处于哪种模式。忽略致命三要素Willison 提醒我们AI 协作里有三个必须正视的因素速度它生成得可能比你审得还快、非确定性相同输入未必得到相同输出和成本容易诱使人减少验证步骤。你的规范和审查流程必须把这三点都算进去不要让生成速度跑在验证能力前面。遗漏六个核心领域如果你的规范没有涵盖命令、测试、项目结构、代码风格、git 工作流和边界你可能遗漏了智能体需要的东西。在将其交给智能体之前使用第 2 节中的六个领域检查清单作为健全性检查。结论为 Coding Agents 写出真正有效的规范靠的仍然是扎实的软件工程基本功再加上一点对 LLM 工作方式的理解。先把目标讲清楚再让模型帮你扩展计划把规范写成可以执行、可以校验的工程工件而不只是漂亮散文把大任务拆成模型能稳定处理的小块再用始终做 / 先询问 / 永远不要的边界、自检机制与一致性测试尽量降低跑偏概率。整个过程本质上是迭代式的规范、实现、测试、反馈循环推进。遵循这些原则后你的 AI 智能体在长上下文里失焦、跑偏或反复返工的概率都会明显下降。在 vibe-vibe 仓库中你可以把 PRD 模板、demo-01-todo 的命令与结构以及 测试用例直接当作规范素材把真实命令写进命令区、把目录约定写进项目结构区、把必过测试写进测试区再配上一组三层边界一份可执行、可校验、可迭代的智能体规范就成型了。祝规范编写愉快赞分享文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载相关推荐从 Vibe Coding 到 Spec Coding以规范Spec为中心的 AI 编程范式easy-vibe 实战指南从 Vibe Coding 到 Spec Coding以规范Spec为中心的 AI 编程范式easy vibe 实战指南 导读本文基于 easy v教程文档easy-vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码easy vibe 深度指南从 Vibe Coding 到 Spec Coding让规范文档成为 AI 编程的新代码 Code is a lossy pr教程文档人工智能Vibe Coding从 Vibe Coding 到 Spec Coding在 easy-vibe 项目中用规范即代码重构 AI 编程工作流从 Vibe Coding 到 Spec Coding在 easy vibe 项目中用规范即代码重构 AI 编程工作流 「代码是意图的有损投影。」Code教程文档上一篇SmartDNS多IP返回三档配置只回最快那一个下一篇猫抓浏览器插件免费开源的网页资源嗅探工具终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考