AI编程总跑偏？用OpenSpec规范驱动，从“拆盲盒”到“按图施工”-北京尧图网络

1. 为什么 AI 编程需要“规范驱动”先问一个扎心的问题你有没有遇到过 AI 编程助手一本正经地写出几百行代码结果你一看方向完全跑偏了要么是没按你的目录结构来要么是缺少关键的错误处理要么是它信心满满地编造了一个根本不存在的函数接口。我见过太多人抱怨“AI 写代码像拆盲盒”明明提示词写得挺清楚出来的东西还是得大改。问题不是出在提示词写得不详细而是出在“一次性对话”这个模式上。你把所有要求塞进一段 prompt 里AI 生成完代码就结束了中间没有校验、没有阶段评审、没有标准化文件结构它只能靠猜。猜对了算运气好猜错了就是一场灾难。OpenSpec 解决的就是这个问题。它的核心思路是在 AI 写代码之前先把“需求规格”和“验收标准”写成结构化文档用文档驱动编码过程。也就是说你不再用“唠嗑式提示词”让 AI 自由发挥而是让 AI 按照一份预先定义好的规格说明去执行变更。变更做没做对也不是靠肉眼判断而是有明确的检查项和测试标准来验证。这样做的收益非常明显一是可复现同样的规格文档交给 AI跑出来的结果基本一致不会今天一个样明天一个样二是可评审规格文档本身就是人类可读的团队里任何一个人都能在 AI 动代码之前先确认需求方向三是可追踪每一个变更都有对应的 spec 记录改了什么、为什么改、验收标准是什么一目了然。这个工具适合谁适合所有用 AI 写代码的开发者和团队。哪怕你是个人开发者只要你希望 AI 不只是一个“代码生成器”而是一个真正能交付可靠代码的“协作工程师”OpenSpec 这套思路就值得你认真研究。当然它对团队协作的价值更大因为规格文档本身就是一种沟通语言能大幅减少“我以为你说的是这个意思”这类扯皮。2. OpenSpec 的核心机制拆解OpenSpec 不是一个重量级框架它本质上是一套约定加一个 CLI 工具。你要先理解它的核心设计才能真正用出价值。2.1 AGENTS.md给 AI 的“项目宪法”OpenSpec 的第一个关键设计是在项目根目录维护一份AGENTS.md文件。这份文件的作用是给 AI 一个关于项目结构、编码规范、技术栈、命名约定、约束条件的全局说明。你可以把它理解成一份“项目宪法”。不管 AI 之后接到的任务是什么它都会先读一遍 AGENTS.md确保自己的行为符合项目的整体规则。这个设计解决了一个非常典型的问题很多 AI 编程工具在生成代码时缺乏“项目上下文”它不知道你这个项目用没用到特定框架、目录应该怎么组织、接口风格是 REST 还是 RPC。如果你只在某一次对话里告诉它它下次就忘了。但 AGENTS.md 是持久化存在的AI 每次都会读到相当于把项目常识固化了下来。实际写 AGENTS.md 的时候我建议至少包含以下内容项目的技术栈清单语言、框架、构建工具、包管理器目录结构说明尤其是哪些目录放什么类型的代码编码规范比如缩进风格、命名规则、注释语言常用的命令行操作怎么跑测试、怎么构建、怎么启动开发环境禁止做的事比如不要修改某个文件、不要引入额外的依赖库写的时候尽量具体避免模糊表达。比如“保持代码整洁”这种话就没用AI 不知道你所谓的整洁是什么意思。但如果你写“函数体超过 50 行必须拆分”“所有公共 API 必须写 JSDoc 注释”AI 就知道该怎么执行。2.2 Spec 目录需求的可执行化载体OpenSpec 的第二个设计是在项目里创建一个spec/目录里面按照specs/和projects/两条线组织规格文档。每份规格文档用 Markdown 写结构固定包含三部分变更描述Change Description、需求与逻辑Requirement and Logic、任务与测试Task and Test。这三部分各自承担不同的职责。Change Description 是对变更总体目标的概括让人一眼看出这个变更要做什么。Requirement and Logic 是核心要把需求和对应的逻辑拆开来讲不能只写“首页要支持用户登录”你得写清楚登录流程、会话保持方式、异常处理逻辑。Task and Test 则把工作拆成一个个可执行的任务每个任务都要对应可验证的测试标准。为什么要这样拆分因为 AI 生成代码的问题往往不在于“写不出来”而在于“不知道自己和目标之间有多少差距”。如果你只告诉它“写一个登录功能”它可能直接给你甩一整套完整的认证模块里面有一堆你根本不需要的东西。但如果你把需求拆成 Task A、Task B、Task C每个 Task 都有明确的产出物和验收条件AI 就能按部就班地执行每完成一个任务就知道自己确实做对了。2.3 变更状态机从草稿到合入的完整生命周期OpenSpec 对变更的生命周期定义得非常清晰。每一份 spec 文档都会经历几个状态proposed提议中、active执行中、review评审中、merged已合入。这个状态机不是形式主义它确保变更在进入编码阶段之前先经过需求确认。很多 AI 编程翻车就是因为跳过了“需求确认”这一环需求都没对齐就开始写代码写完发现根本不是我想要的返工成本极高。OpenSpec 强制你在 first review 阶段先让人类评审需求文档评审通过后才进入编码阶段这个流程符合软件工程里的“先设计再开发”原则。状态流转的实际操作是通过 CLI 工具一步步完成的。你在命令行里执行openspec review它会把当前变更标记为评审状态同时生成一份差异对比方便团队评审人在 Pull Request 里查看。这个过程顺畅且透明不会出现“我明明改了但没人知道改了什么”的情况。3. 实战从零初始化到第一次规范驱动开发理论讲完了实操才是重点。我用自己的实际经历带你走一遍 OpenSpec 的完整流程。你要跟着操作也可以大概十分钟就能跑通。3.1 安装与初始化安装 OpenSpec 很简单它依赖 Node.js 和 npm 环境。如果你还没有装 Node.js先去官网下载 LTS 版本装好。然后执行npm install -g openspec/cli装完验证一下版本openspec --version接下来进入你的项目目录执行初始化命令openspec init这条命令会在项目根目录创建AGENTS.md和spec/目录结构。我强烈建议你在这时候花点时间认真写 AGENTS.md不要直接用它生成的模板。因为后面所有 AI 编程操作都会以这份文件为行为基准它写得越具体AI 跑偏的可能性就越低。顺便说一句如果你担心 AGENTS.md 写得不完整可以先写个基础版然后在实际使用中不断补充。AI 是不会抱怨文档质量的但文档质量会直接反映在它的产出质量上。3.2 创建你的第一份 Spec初始化完成后创建一个新变更。假设我们要给一个 To-Do 应用增加“标签筛选”功能执行openspec create filter-tasks-by-tag执行之后OpenSpec 会在spec/specs/filter-tasks-by-tag/spec.md生成一份规格文档模板。用编辑器打开填入具体内容。Change Description 部分我写的是为任务列表增加按标签筛选功能用户可以通过点击标签快速查看包含该标签的任务并在筛选状态下正常执行完成任务、编辑任务等操作。Requirement and Logic 部分我拆成三条需求每条对应明确的逻辑。比如“标签列表展示”这条需求对应的逻辑是从所有任务中提取唯一标签集合并按使用频率排序点击标签后触发筛选状态更新。Task and Test 部分我把工作拆分成了三个任务创建标签数据模型并迁移数据库实现标签点击筛选的前端交互为筛选功能补充后端查询接口和测试每个任务下面都写了明确的验收标准。比如任务三的验收标准是“新增接口在无筛选条件时返回全部任务有筛选条件时只返回匹配标签任务响应时间不超过 200ms”。写完整份 spec 之后执行openspec plan filter-tasks-by-tag生成变更计划。这个计划文件里记录了这个变更涉及哪些文件、哪些技术决策、预计的修改范围是后面所有编码工作的执行蓝图。3.3 用规则驱动 AI 编码现在到了真正的重头戏让 AI 按照这个 spec 去写代码。配置好 Codex 或其他支持读取 AGENTS.md 的 AI 编程工具直接让它执行请按照 OpenSpec 变更计划执行任务。先阅读 spec/specs/filter-tasks-by-tag/spec.md 中的需求逐项实现并运行测试验证。AI 收到这个指令后会先读取 AGENTS.md 了解项目规则再读取 spec 文档理解需求然后按 Task 列表逐项执行。和之前“自由发挥”模式最大的区别是它不再是基于你抛给它的几句提示词猜需求而是基于一份结构化的完整规格去落地每一步都知道自己在做什么、为什么这样做。我实际测下来这种模式下 AI 生成代码的准确率显著提升返工次数明显减少。尤其是需求逻辑越复杂的时候spec 文件的价值越能体现出来——它实际上是给 AI 补上了“需求分析”和“架构设计”这两块过去严重缺失的能力。3.4 评审与合入AI 完成编码后进入评审阶段。执行openspec review filter-tasks-by-tag这个命令会做几件事对比 spec 中声明的任务和 git 中实际发生的变更生成一致性报告列出哪些任务已完成、哪些还有缺口生成当前变更的完整 diff 信息供人评审。我review完确认没问题后执行openspec merge filter-tasks-by-tag把变更标记为已合入状态整个流程闭环结束。这个变更从需求定义、计划生成、编码执行、测试验证到评审合入全程都有迹可循。以后想回头看“这个功能当初是怎么实现的”打开 spec 目录就能找到完整记录。4. 常见问题与排查技巧实录用了一段时间之后我整理了几个高频问题和对应的排查方法相信你在实践中也会遇到。4.1 高频问题速查表问题现象可能原因排查方法AI 生成的代码和 spec 不一致AGENTS.md 里的项目规则写得太模糊AI 没有足够上下文检查 AGENTS.md 是否覆盖技术栈、代码结构、命名规范把模糊描述改成具体规则spec 里写了任务但 AI 跳过没做spec 的 Task and Test 部分描述不够具体AI 无法将其拆成可执行步骤每个 Task 必须写明产出物和验收标准避免类似“完善功能”这种无法执行的任务描述review 阶段发现变更范围失控Change Description 描述的是一个笼统目标没有界定边界写明“本变更不包括”什么内容比如“本次不处理性能优化”多个变更互相关联时状态混乱没有把关联逻辑写在 spec 里在 Requirement and Logic 部分显式声明依赖关系注明前置变更的 spec 名称通过评审的变更合入后测试失败测试标准写得太宽泛没有覆盖边界条件在 Task and Test 中补充异常分支测试例如输入为空、数据不存在、并发操作等情况4.2 我最常踩的三个坑第一个坑一开始我把 AGENTS.md 写得像一篇散文详细但散乱AI 读完抓不住重点。后来改成结构化清单每条规范独立一行AI 的执行准确性立刻上来了。这个经验启发我写 AGENTS.md 的时候每条规则要能独立理解不要依赖上下文推断。第二个坑按照自由发挥的习惯我坚持在一份 spec 里塞了四个不相关的功能结果 AI 在执行过程中逻辑混乱文件修改互相干扰。后来我严格遵从一个变更只做一件事的原则独立的小功能也要拆成独立的 spec整个流程立刻顺畅了。第三个坑review 环节最初我很不上心简单看看就 merged。结果有一次 AI 虽然按 spec 实现了功能但代码风格和项目原有风格严重不一致合入后维护成本升高。现在我会专门检查新增代码的风格和结构这个环节不能省。4.3 团队协作时的额外建议如果你是在团队里推行 OpenSpec建议第一周先跑一个小项目让每个人都写一遍 spec 并互相评审。不用急着立一堆规定先把基本流程跑顺。跑顺之后你会发现规格文档这种“先文档后代码”的方式不仅对 AI 有效对团队里的人类同事同样有效——因为需求沟通的颗粒度变细了很多东西在开发之前就被聊透了。另外可以把 spec 目录提交到 git 仓库和代码一起管理。这样每次 Pull Request 里都包含对应的规格文档评审人看着文档看代码理解成本降低很多。团队成员离职或者新人加入的时候翻开 spec 目录就能快速理解每个功能的设计意图上手速度快得多。5. 这套方法论更深层的价值用 OpenSpec 一段时间后我回头看它做的事情本质上不是“让 AI 听你的话”而是“让 AI 和你在同一个频道上”。很多 AI 编程工具的使用者处在“提示词工程师”阶段费尽心思琢磨怎么把需求描述清楚但 OpenSpec 提供了一条新的路跳出“张嘴说需求”的框框把需求文档化、结构化让它成为 AI 和人类共同依赖的参考系。你自己试试就明白我说的意思了。当 spec 文档写得足够清晰AI 就会从一个被动的“代码生成器”变成一个理解目标并主动推进的“工程师助手”。你不需要在提示词里反复强调各种细节因为规范已经替你把细节定义好了。这个体验上的跨越是单纯优化提示词很难达到的。我个人现在每个项目开始之前都会先花 20 分钟写 AGENTS.md 和一个基础 spec这个时间花得特别值。而且我发现这个习惯一旦养成了就很难回去——体验过“按流程推进”的省心感你就不想再回到“拆盲盒”式编程了。后面的路你完全可以先拿一个真实的小需求跑一遍完整流程经验积累起来之后再看看哪部分需要调整。

AI编程总跑偏？用OpenSpec规范驱动，从“拆盲盒”到“按图施工”

相关推荐

archify：AI代理技能模块，自动生成可交互架构图

园区网络与监控系统设计：从VLAN规划到存储与告警实践

JDK 8u431 压缩包配置指南：从解压到环境变量与多版本切换

更多资讯

制造集团数字化转型规划：151页PPT拆解与落地避坑指南

TinyImageNetTorch：微调预训练模型的轻量级压力测试集

DeepSeek双链路实战：硅基流动API与LM Studio本地部署

C++从零实现CNN与全连接网络：手写梯度、内存与MNIST训练

基于深度学习的恶意加密流量检测毕设源码：DoH与CTU-13特征工程及模型复现

基于FFmpeg的轻量级音视频播放器实现与同步原理

今日更新

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？