在 AI Coding 实战中我越来越确信一件事在提示词里把话说清楚远不如把验收标准定明白。OpenSpec 正是冲着这个痛点来的——它把自然语言需求转成结构化的规格说明让 AI 在动手写代码之前先明确“要做什么”“怎么验证”“做到什么程度算完成”。这篇手册是我把 OpenSpec 从概念到落地踩过一遍坑之后的完整梳理包含实际项目里用得上的步骤、文件结构、验收方法和排查思路覆盖从零开始到接入现有工作流的全过程。无论你是刚接触 AICoding 的开发者还是已经在用 AI 辅助编程但总觉得结果不可控这套方法都值得花半小时看完。1. 项目背景与整体设计思路1.1 为什么 AI 写代码需要一份“规格说明书”传统开发流程里需求从产品经理传到开发靠的是文档、会议和口头补充。但 AI 没有“上下文记忆体感”你给它一段自然语言描述它就按字面意思生成代码。问题是自然语言天然有歧义“快速处理”是多快“用户友好”是什么标准“日志记录完整”又到底完整到什麼程度这些词在人类同事之间可以靠默契补全但在 AI 面前就是一个个隐含的坑。我在一次内部工具开发中遇到过非常典型的例子我让 AI 写一个导出功能只说了“把数据导出成 Excel”。结果它调用了某个特定库生成的文件在老版本 Office 里打不开而且完全没有做列宽优化。需求本身没错但验收标准缺失AI 在无数个合理选择里挑了一个我不想要的。OpenSpec 的思路就是终结这种“玄学”它将需求拆解为功能点每个功能点都有明确的验收标准。它将“描述”转化为可执行的验证清单AI 可以逐项自查。它将需求变更变成可追溯的增量文件避免 AI 在长上下文里遗忘早期约束。说白了OpenSpec 是给 AI 编程加了一道“质检工序”。质检标准不是人脑里的模糊感觉而是写进文件、可检查、可追溯的硬性条件。这对于依赖 AI 独立产出代码的场景尤其重要。1.2 OpenSpec 的核心理念从“描述意图”到“定义可验证行为”很多人第一次看到 OpenSpec会误以为它只是又一种文档模板。但实际上它更接近一套针对 AI Agent 的行为契约机制。核心思想可以浓缩成一句话让 AI 理解“完成”的定义而不是“想法”的描述。以登录功能为例自然语言描述可能是“用户可以通过邮箱登录”。这句话 AI 能理解但不知道边界在哪里。Email 格式不对要拦截吗密码错误提示什么文案登录成功后跳转到哪里锁定策略要不要做这些在自然语言里都没有答案。OpenSpec 的做法是把功能拆成一连串可验证的行为表现输入合法邮箱与正确密码返回登录成功令牌。输入非法邮箱格式返回参数错误提示不发起认证请求。同一账号连续失败 5 次触发临时锁定时间窗口。如此AI 在代码生成阶段就有了明确边界条件它的每一个实现选择都可以对照规格条目进行验证。这就是 OpenSpec 与传统需求文档的本质区别传统文档是给人看的参考OpenSpec 是给 AI 执行的可测契约。这个设计理念直接影响了文件组织方式一份变更规格change spec不是散文而是按行为分组的测试导向文档。AI 读完之后不是“大概明白要干什么”而是“知道每项行为如何被验证”。我后续会把具体的文件结构和写作方法展开讲。理解这个理念后面所有的实操步骤都顺理成章。2. 核心细节解析文件结构与规格写法2.1 四类文件的职责划分OpenSpec 在仓库里约定了一套标准目录结构。初次接触可能会觉得文件多但每个文件都有明确职责熟悉之后会非常顺手。一个典型结构如下openspec/ ├── specs/ │ ├── auth-login/ # 变更规格目录 │ │ ├── spec.md # 本次变更的行为定义 │ │ ├── requirements.md # 功能需求追踪矩阵 │ │ └── tasks.md # 任务拆解与依赖关系 └── project.md # 项目级约束与全局规则四类文件各司其职spec.md规格主体。逐条列出行为需求每条都带验收标准AI 在编码前必须完整理解此文件。requirements.md需求追踪矩阵。把业务需求、功能点、验收标准、对应测试关联起来便于查漏补缺。tasks.md任务拆解清单。把规格拆成可逐步执行的子任务AI 按顺序推进每完成一个任务就自查一次。project.md项目级约定。包括技术栈约束、代码风格、第三方服务限制等是全局适用规则。这个拆分极大降低了 AI 的认知负担。代码生成前它只需读spec.md和tasks.md不必在长篇大论的需求文档里挑重点遇到模糊规则时再回看requirements.md查对应条目。对于上下文窗口有限的 AI 模型这种文件结构等于把“思考路线图”直接喂了进去。2.2 spec.md 的写作规范行为优先拒绝形容词我见过不少人在 spec.md 里写下类似“系统应该有良好的性能”“体验需要流畅”这样的条目。这完全违背了 OpenSpec 的初衷。规格条目必须聚焦可验证行为尽量使用量化数据和判定规则。以“搜索功能”为例对比两组写法差系统可以快速搜索用户列表。 好用户输入关键词后 1 秒内返回匹配结果匹配基于用户名和邮箱的前缀/精确匹配不涉及模糊匹配。第二组写法中包含三层信息时间约束1 秒内、匹配字段用户名、邮箱、匹配方式前缀/精确。AI 拿到这样的规格后实现路径非常明确构建索引、按字段过滤、性能目标可视化。而且验收时可以自动化测试不需要人工“凭感觉”判断。写规格的另一关键是覆盖正常路径与异常路径。AI 天然倾向于实现“快乐路径”——输入合法、流程顺畅。但真实系统里大量代码都在处理异常。OpenSpec 规格中必须明确写出异常行为的期望结果例如当关键词为空时返回空列表不发起查询。当服务端返回 500 时界面展示“服务暂时不可用”并允许重试。有了这些条目AI 生成的代码不会在异常场景直接崩溃。我给出的经验法则是正常路径一条异常路径至少一条边界条件单独一条。把这三类行为覆盖到位代码质量会显著提升。2.3 requirements.md 与验收标准的映射关系requirements.md的价值在项目中期尤其明显。当 AI 已经生成了一部分代码新增需求开始叠加时靠人脑记住“哪些需求已实现、哪些还在进行中”非常困难。追踪矩阵就是为此设计的。我习惯用表格维护映射关系需求编号用户故事/描述功能点验收标准关联测试状态REQ-001用户通过邮箱登录认证接口合法邮箱密码校验通过后返回 JWTtest_login_success已完成REQ-002登录失败次数限制锁定逻辑5 次失败后锁定 15 分钟test_login_lockout进行中这张表看起来简单但实操中有两个要点。第一验收标准必须能唯一对应到某个测试或验证动作不能含糊。第二每次代码变更后要主动更新状态否则矩阵会失真。AI 处理增量任务时读这张表就能准确判断哪些模块已经稳定、哪些需要调整避免重复实现或漏改。初期维护表格确实会占用少量时间但中后期收益巨大。我在实际项目里经历过这种情况某天要新增“忘记密码”功能我直接查矩阵发现 REQ-001 的认证流程已经验收通过于是新规格只聚焦密码重置链路完全不触碰登录核心逻辑。这个体验比阅读一整个需求文档再梳理边界要高效得多。3. 实操流程从零落地 OpenSpec3.1 初始化与配置准备引入 OpenSpec 不需要安装额外服务本质是约定目录结构和文件写法。我建议在仓库根目录创建openspec/文件夹然后按前文结构补上project.md。这个文件是全局规则的锚点内容至少包括项目技术栈与版本如 Python 3.11 FastAPI PostgreSQL。代码风格约定如类型注解必须完整函数需带 docstring。第三方服务限制如不能引入未经评估的依赖包。通用验收规则如所有接口必须包含超时处理与错误码。写project.md时要有“给 AI 立规矩”的意识。它描述的不是某个功能而是所有 AI 生成代码都必须遵守的底线。我见过的最佳实践是把常用的架构约束也写进去例如“业务逻辑不得写在路由层”“数据库查询必须走仓储层”。AI 在没有明确规则时倾向于直连数据库有了这些约束后生成的代码结构会干净许多。3.2 完整实操将业务需求转化为 OpenSpec 规格为了让大家看清楚完整落地路径我用一个实际案例走一遍流程。需求描述如下用户可以创建项目项目包含名称、描述和截止日期。项目列表页按截止日期排序仅显示尚未完成的项目。第一步拆解行为。基于这个需求我识别出三个核心行为创建项目、校验输入、按规则列表展示。这步不写文档先在脑中过一遍行为边界。第二步写spec.md。我按行为分组写下规格条目## 创建项目 - 用户可提交名称、描述、截止日期创建项目。 - 名称为必填长度限制 1-100 字符。 - 描述可选长度限制 0-500 字符。 - 截止日期格式为 YYYY-MM-DD且不能早于创建当天。 ## 项目列表页 - 列表仅包含未完成项目即截止日期晚于当前日期。 - 列表按截止日期升序排列。 - 每项展示名称、描述、截止日期。 - 当无未完成项目时展示空状态提示“暂无进行中的项目”。第三步写requirements.md。将上面行为对应成需求矩阵补上测试策略。第四步写tasks.md。按依赖顺序拆任务先创建数据模型再写创建接口与校验逻辑接着列表查询与排序最后补前端展示或 API 返回格式。这个顺序让 AI 可以先搭骨架再补细节。第五步把文档交给 AI 编码。有了规格约束后AI 生成的代码基本不会偏离预期。创建项目接口会包含必填校验和日期格式校验列表查询会主动过滤已完成项目并按截止日期排序。3.3 将 OpenSpec 接入 AI 辅助编程工作流OpenSpec 的价值最大化需要与 AI 编程工具工作流深度绑定。我目前使用的是 Claude 驱动的编程工作流但在任何支持“读取文件作为上下文”的工具中都适用。我的工作流程是开发新功能前先把spec.md和tasks.md路径提供给 AI提示它先阅读规格再动手。在项目根目录准备一个AGENTS.md或类似说明文件明确写出“所有代码变更必须遵循 openspec/ 目录下的规格定义开始任务前先读取对应 spec.md 和 tasks.md”。当 AI 完成代码后我要求它逐条对照验收标准自查。这个自查动作是关键它能利用 AI 自身的逻辑推理能力找出遗漏。有一次AI 生成的创建接口没有处理“截止日期为同一天”的边缘情况我让 AI 自查时它就发现测试缺失主动补上了边界测试。这比我人肉审查代码的效率高很多。需要强调的是OpenSpec 不能替代代码审查但从“AI 自由发挥”变成了“AI 按契约交付”审查范围大幅缩小。后续只需要关注逻辑性能和架构细节不用把时间花在反复纠正基本功能偏差上。4. 问题排查与经验沉淀4.1 常见问题与解决方案落地 OpenSpec 过程中我积累了一张问题排查表基本覆盖了多数首次使用者的困惑。问题现象可能原因解决方案AI 忽略规格描述按自然语言理解行事提示词中没有明确指向规格文件在系统提示词或 AGENTS.md 中明确“优先遵循 openspec 规格”规格条目与最终实现不一致验收标准写得模糊重写条目确保每条包含量化约束与判定规则文件结构混乱找不到对应条目目录命名没有语义化用具体功能名如 auth-login代替通用命名如 feature-1需求变更后旧规格干扰新实现没有归档旧变更规格每次变更新建独立目录标注状态为“已完成”或“已废弃”AI 生成的测试没有覆盖异常路径spec.md 中缺少异常行为定义在规格中明确补充异常输入与边界条件的预期行为项目中期矩阵状态失真requirements.md 未及时更新每次编码完成后立即更新对应需求行状态其中第一条是我一开始最常踩的坑。AI 非常擅长“顺从用户”如果你在对话里说了“请实现用户注册功能”它就会重点参考这句指令而不是自己去翻目录中的规格文件。解决办法是在提示词中硬性指定文件读取顺序比如“先读取 openspec/specs/auth-register/spec.md按规格条目逐步实现禁止跳过任何验收标准”。这能极大减少规格被忽略的概率。4.2 实战经验与建议我在两个项目里完整跑过 OpenSpec 流程一个是一次性工具开发另一个是长期维护的内部系统。前者的体验是“需求转写过程比直接写代码还慢”但后期几乎没有返工后者的收益则体现在需求变更的可控性上。没有 OpenSpec 时我害怕临时加需求总担心 AI 会把已经很稳定的模块改出问题。有了规格文件后增量需求可以精确限定到某个目录AI 只需解析对应目录中的变更规格旧功能完全不受影响。还有一个值得推荐的小技巧把 OpenSpec 的规格文件与 Git 分支绑定。每份变更规格对应一个 feature 分支规格文件随代码一起提交代码合并时规格一并合并。这样整个仓库的历史记录中每个功能都有与之对应的“契约档案”。回溯问题时不用翻聊天记录或需求文档直接看对应分支的 spec 和代码 diff 就能快速定位。如果要说一个最核心的心得那就是“宁可花一小时写规格不要花三小时和 AI 纠缠代码”。很多开发者觉得写文档浪费时间但 AI 编程时代规格就是指挥棒。指挥棒方向不明AI 做出来的东西必然要返工。而且 OpenSpec 的一大好处是规格文件对所有 AI 工具通用换了模型也能直接沿用。你积累的规格库不会因为切换工具而作废这份资产会持续沉淀。5. 扩展OpenSpec 在团队协作中的使用模式5.1 从个人实践到团队协作个人使用 OpenSpec 时文件怎么写、流程怎么定都很自由。但一旦进入团队协作就需要统一一些约定。我在团队中推行 OpenSpec 时最重要的约定是**“规格先行”**任何功能开发先提交 spec.md 和 requirements.md 的变更经过评审后再让 AI 编码。这保证了 AI 生成的代码是基于团队确认过的行为定义而不是某个成员的个人理解。评审规格时我一般关注三点验收标准是否量化、是否覆盖异常边界、是否与现有功能冲突。只要这三点通过AI 编码环节就不太需要人工干预。团队协作中使用 OpenSpec 还有个额外优点新人可以通过阅读历史规格快速理解系统各模块的行为边界比翻代码逐行推理高效得多。5.2 规格库的积累与演进随着项目推进openspec 目录会积累大量变更规格。合理的做法是对已经完成的规格目录做归档标记保留历史记录但不再纳入 AI 读取范围。活跃开发集中在当前迭代的规格目录中这样 AI 每次只需加载与本次任务相关的内容不会被历史信息干扰。此外我倾向于定期复盘规格质量。每两个迭代后我会回头看看哪些规格写得高效、哪些被反复修改。通常效率最低的规格都败在“没有量化验收标准”上。比如“展示所有项目”这条规格AI 实现为分页列表而需求方希望无限滚动这就是规格缺失“展示形式”约束导致的偏差。量化后的写法应该是“页面初始展示最近 20 个项目滚动到底部时自动加载下一批 20 个项目”。这类复盘让规格库越来越精确项目越复杂这种精确性的价值越大。从经验来看OpenSpec 并不适合极其简单的、一次性的小脚本——那种场景直接写代码更快。但凡是需求会变、代码会持续演进的项目规格驱动的收益非常明显。我目前的新项目一律先搭 OpenSpec 骨架再开工这个习惯已经稳定跑了大半年后面还会继续用下去。