写代码这几年我最头疼的事不是功能实现不了而是需求变了、上下文丢了、代码和文档又对不上了。特别是开始用 AI 辅助写代码之后这个问题被无限放大——模型能读懂我的仓库但它不知道我心里想要的“规矩”是什么。后来我接触到 OpenSpec 这套思路算是对上了我的胃口。它不是什么重武器就是一个轻量级的规范管理框架专门用来约束 AI 工程实践中的规则、流程和上下文传递让 AI 生成的代码和项目长期演进方向保持一致。简单说OpenSpec 解决的核心问题是AI 写代码时把“隐性规则”显性化。它不像传统架构文档那样又臭又长而是以轻量级、可校验、可追溯的规范文件作为 AI 工程的核心语境让开发者在跑任务之前就把边界划清楚。这套东西适合谁所有在项目里重度依赖 AI 辅助编程的团队以及和我一样的独立开发者尤其是那种一个仓库上百个文件、靠对话式提示词已经搞不动上下文的人。下面我把这套框架的拆解思路、落地细节和实践中踩过的坑都整理出来。1. 整体设计思路为什么规范管理比提示词管理更靠谱先说一个我自己的观察。很多人用 AI 写代码翻车不是因为模型的智力不够而是因为你和模型之间没有“共同契约”。你一句“按项目风格实现接口”模型根本不知道你的项目风格到底是什么。它只能从现有代码里去猜猜得准是运气猜不准是常态。OpenSpec 的核心思路是换一个交互底座不是靠对话里的临时描述去约束行为而是把规范本身做成项目的一部分。每个关键模块、每类任务背后都有一份明确、格式化、可被自动读取的规范文件AI 在执行任务前会被要求先读取这些规范再开始动手。这套设计背后其实模拟的是成熟开源社区的操作逻辑贡献者先读 CONTRIBUTING再按 ADR架构决策记录沉淀决策最后才写实现。OpenSpec 就是把这个过程压缩成一个工程框架直接嵌入到 AI 编程工作流里。1.1 与传统文档、架构治理工具的对比肯定有人问这不就是写文档吗我用 Notion、Confluence 不也一样。区别在于三个维度第一OpenSpec 的文件是结构化、机器可读的不是自然语言散文。传统文档写“本模块采用依赖注入方式”AI 读起来要靠悟性OpenSpec 直接定义好格式让 AI 能在多个文件中精准检索规则并受其约束。第二OpenSpec 强调演进性。它不是一次性架构设计而是把规范分成当前状态、目标状态、任务边界、验收标准几个领域在每个迭代周期里可持续更新。对比之下传统文档从写完那天就开始腐烂。第三它的反馈闭环很短。改一行规范文件、重新运行校验AI 下一次执行就会带上新规则。不需要开会同步不需要技术宣讲仓库就是唯一的真相源。我梳理了一个对比表方便大家理解定位差异方案类型结构程度更新成本对 AI 友好度适用场景自然语言提示词弱低差一次性任务传统架构文档中高一般人类阅读为主ADR 机制中中中团队决策记录OpenSpec 框架强低高AI 工程持续演进1.2 框架的三个核心模块规范、流程、校验OpenSpec 不是单一的大配置文件它由三个互相配合的模块构成。规范Specifications是核心以目录形式组织每个目录对应一个领域能力或子系统。这里面不是写“代码应该更优雅”这种废话而是写“缓存模块必须支持 TTL 过期策略且默认过期时间 5 分钟”这种能被校验的事实。流程Workflows是操作层面的编排定义 AI 在执行任务时应该按什么顺序读取规范、修改哪些文件、如何提交变更说明。很多团队忽略这一步结果规范文件写了AI 根本不看。流程模块的价值就是强制把规范读取嵌入到执行链路里。校验Validation是兜底机制通过内置脚本扫描代码和规范声明之间的一致性比如接口是否按要求导出、命名规范是否满足正则约束、废弃 API 是否被移除。这一环不做到全自动但至少实现了半自动提示保证规范不被悄悄绕过。三者的关系可以理解成规范是宪法流程是司法程序校验是警察。缺了任何一个整个体系都有可能变成纸上谈兵。2. 核心细节解析与实操要点这套框架一开始上手会觉得有点抽象因为它不像是装一个依赖库或者配一个配置文件那么直接。OpenSpec 更多是一种工程组织方式需要用目录和文件去承载再让 AI 工具链通过规则读取去感知。下面拆解几个最容易卡住新人的关键点。2.1 目录结构的规划与放置位置我在实际项目中目录结构设计得比较轻。OpenSpec 本身不强制你放在某个根目录但我在多个项目里对比下来放在仓库根目录下的 specs/ 里最顺手因为 AI 助手扫描文件的时候能第一时间感知到这个目录的存在。内部我一般分成两层。第一层按领域拆比如 auth、billing、data-pipeline第二层按性质拆比如每个领域目录下固定放 three 类文件spec.md能力现状与缺口、tasks.md待办任务、rules.md硬性约束。如果某个领域有特别复杂的决策再补一个 decisions.md。这套结构的核心价值就是把“领域知识”和“任务状态”分离。之前用 AI 辅助写代码时最怕把一堆历史决策混在任务描述里结果模型的注意力被无关信息稀释。OpenSpec 这种分文件方式能让 AI 每次只加载需要的上下文响应质量明显更稳。实际规划中有三个建议都是踩过坑总结出来的不要在根目录塞一堆顶层文件必须以领域为粒度拆分否则规范就变成了另一个没人读的大文档。每个领域容量控制住如果一个 spec.md 超过 200 行说明领域切得太粗要继续拆。rules.md 里只放机器可判定的约束不要放“模块设计要有层次感”这类虚词没有可执行性。2.2 规则文件怎么写才能被 AI 执行这是很多初上手的人最容易翻车的地方。大家习惯性用人类语言写规则比如“遵循最小惊讶原则”“保持代码整洁”。问题是AI 对这些抽象词汇只能给出随机性很强的响应不同模型执行的波动大到你怀疑人生。我调试下来发现能被 AI 有效执行的规则都有三个特征具体、可检验、可示例化。以命名规范为例。不要写“变量命名要有意义”而要写“缓存键格式必须为 biz:{module}:{key}其中 module 为小写蛇形命名禁止使用 UUID 作为缓存键”。这种规则 AI 能直接内化成行为因为它不需要理解什么叫“有意义”只需要套模板。规则里加示例也非常重要。我在 rules.md 里每个约束下几乎都配了正例和反例。比如- 规则service 层接口必须返回领域对象禁止返回 JPA 实体。 - 正例userService.getProfile() - UserProfiledomain model - 反例userService.getProfile() - UserEntityjpa entity为什么示例这么管用因为 AI 模型擅长 pattern matching给它抽象规则它容易发散给它正反例它反而能牢牢记住。那个 AI coding 工具的上下文限制大家都懂与其在对话里反复纠正不如在规范文件里一次喂饱。2.3 校验脚本的设计边界校验不能太贪心。我有段时间想把所有规则都自动化检查写了差不多 300 行 Python 脚本结果维护成本比写代码还高后来砍掉大半只保留了四类高价值检查文件命名是否符合基础设施约定暴露的 API 是否在指定的头部目录统一导出禁止使用的类型或函数是否出现在代码中任务状态和代码变更是否匹配比如标记为完成的模块是否还有 TODO本质上校验脚本干的是“廉价信号检测”不是“代码质量评审”。前者让 AI 在提交前自我纠错后者人类自己都不一定做得好别指望机器一次性解决。提示校验逻辑应该保持单一职责。如果你发现校验脚本里混进了代码风格检查、测试覆盖率检查赶紧拆出去否则这个脚本会变成新的技术债。2.4 任务状态机的流转逻辑OpenSpec 里的任务状态是个很容易被忽略的设计点。它不是简单的 todo/done而是包含三层proposed待评审、active进行中、done已完成。这个设计是为了配合 AI 工程里的异步工作节奏。很多 AI 生成的任务清单热热闹闹但实际执行到一半发现上下文变了、需求调整了如果状态只能从 todo 直接跳 done整个规范文件很快就失真了。引入 proposed 状态意思是先记录意图但不承诺实现active 表示正在处理done 必须满足两条代码合入主分支、相关的 spec 更新完成。我在实践中直接把这三态写进了 tasks.md 的文件头用 YAML 管理。AI 每次执行任务时读取状态避免反复造轮子或者跳过关键步骤。3. 实操过程与核心环节实现规章说了不少直接上实战流程。我以自己维护的一个模拟项目 X一个带用户体系的内容发布后台为例拆一下从初始化规范框架到跑通闭环的完整操作过程。3.1 从零初始化 OpenSpec 规范的完整步骤初始化那一步其实非常轻不用安装额外运行时不用引入构建工具。OpenSpec 本质上就是一组目录加约定。我会手动创建初始结构specs/ auth/ spec.md tasks.md rules.md content/ spec.md tasks.md rules.md project/ spec.md tasks.md rules.md第一步是给项目根域project写当前状态。把项目的技术栈、目录解释、启动方式、关键约定全部写进 spec.md这部分不需要写得像架构设计文档那么多重点是给 AI 一个“全局地图”。比如项目是前后端分离架构前端使用 Vue3 TypeScript后端使用 Python FastAPI数据库统一走 PostgreSQL所有外部访问走网关转发。模块划分以域为单位禁止跨域直接调用数据库表必须走服务接口。第二步是梳理硬性约束到 rules.md。比如禁止在代码中出现明文密钥、禁用 any 类型、接口返回统一包装格式等等。每一条都配正反例。第三步是建立任务状态表把第一个迭代要处理的 backlog 按 proposed 状态列进去等开发者逐个激活。这个流程做完整个仓库的 AI 上下文“骨架”就建立起来了后面所有任务都基于这套框架推进。3.2 让 AI 编码助手理解并遵循规范框架建好后最大的问题是AI 怎么知道要读这些文件我尝试过几种方式简单聊一下效果。第一种是把规范路径直接写进系统提示词system prompt比如“开始任务前必须读取 /specs/ 下所有 rules.md”。这种效果最直接但只对支持自定义提示词的工具有效。第二种是在任务描述里附带规范摘要。比如让 AI 实现登录接口时直接把 auth/rules.md 里与 JWT 相关的内容贴进任务文本。这种比较可靠但麻烦在于需要人工精选相关内容搜索成本高。第三种是写一个 pre-task 脚本自动列出仓库里所有带 TODO 或 ACTIVE 状态的任务再把对应规范文件打包拼接进上下文。我实测下来这种最适合中等规模项目既能保证全量读取又不至于超出模型上下文窗口。我在项目里最终采用方案一加方案三的混合模式系统提示词约束必须读取脚本负责把最相关的规范片段注入每一次任务的上下文。3.3 一个典型任务迭代的完整演示拿模拟项目 X 的“实现用户注册验证码”这个任务来演示。这套任务在传统工作流里无非就是“写个接口加点验证”但在 OpenSpec 框架下有一个比较标准的推进路径。先读 auth/rules.md发现里面有一条硬约束验证码必须绑定会话 ID且 5 分钟内有效过期后必须清理。同时 spec.md 里记录当前验证码服务还未接入 Redis这是一个能力缺口。接着激活 tasks.md 里的 pending 任务标记为 active然后让 AI 开始实现。我在实际执行时观察到规范前置的效果非常明显AI 在实现时自动避免了把验证码存在内存变量的行为因为 rules.md 里明确写了“生成后写入 Redis并设置过期时间”。实现完成后运行一遍校验脚本检查是否使用了 Redis API是否导出为标准响应格式是否在网关层添加了限流说明。全部通过后把 spec.md 从“未支持验证码”更新为“已支持验证码服务Redis 存储TTL 5 分钟”同步将任务状态改为 done。整个闭环本质上就是现状记录 - 规范约束 - 代码生成 - 自动校验 - 规范更新。每一步都有据可查AI 的行为不再是一个不可控的黑盒。3.4 规范变更与重构的推进方法项目不可能不变规范和现实之间的偏差是常态。我把规范变更分成两类被动变更和主动重构。被动变更是需求驱动比如上线后发现验证码有效期 5 分钟太短要改成 10 分钟。操作不复杂改 rules.md重新跑校验通知相关模块同步。这一步的坑主要在关联影响改完验证码规则后说不定登录模块的会话策略也得跟着调所以我把变更记录统一放在 decisions.md方便追溯。主动重构比较费劲。比如决定把缓存层从 Redis 迁移到本地多级缓存这种情况下不能只改规范文件得先更新 spec.md 的目标状态创建一个迁移任务标注涉及的历史决策和废弃项最后再让 AI 按新规则实施代码改造。在这么多次迭代中我最大的体会是规范变更必须小步走一次只动一个约束点然后马上验证效果。如果一次改五六条规则出问题后根本定位不到是哪一条导致的。4. 常见问题与排查技巧实录任何框架在实际落地中都会碰到反模式OpenSpec 也一样。下面这几个问题几乎每个刚接触的人都会踩列出来给大家排雷。4.1 规范文件写了AI 却不遵守怎么办这个问题出现的频率极高。表面上看起来像是 AI 能力不足实际上多半是规则没有被有效传递。我排查的顺序一般是先确认 AI 是否真的读取了规范文件方法是在任务描述里加一句“回答前请先复述你将要遵循的规范”如果复述得不对说明文件根本没进上下文。接着看规则本身的质量。抽象规则导致的“不遵守”其实不是 AI 的问题是规则缺少可操作性。比如“保持架构清晰”这种规则AI 根本不知道该具体保持什么。我通常的处理方法是把这类规则改写成三到五个具体检查点禁止循环依赖、禁止业务逻辑写在 Controller 层、禁止直接操作第三方 API 不封装。如果这两步都没问题还有可能是规则文件太多AI 在长上下文里“迷失”了。解决方法是把 rules.md 再拆分让每个任务只加载和它直接相关的规则文件注意力不稀释执行力会明显上升。4.2 多团队协作时规范冲突如何处理OpenSpec 在个人项目上很顺手一旦多团队一起开发规范冲突就来了。A 团队要求所有接口走 REST 风格B 团队协作的模块可能要求走 RPC两边 rules.md 写在一起就开始打架。我在多团队项目里的处理方案是在顶层建立 shared/ 目录放所有团队必须遵守的全局规范各团队保留自己的领域规范目录互不干扰。冲突发生时先看全局规范能不能覆盖如果不能则在共享目录里发起一个变更提案而不是在各自领域里互相覆盖。这个机制其实模仿了开源项目里的治理逻辑公共规范变动成本高需要评审局部规范自主权高可以快速迭代。这么一区分大部分冲突都能在架构层面化解不会渗透到代码层面。4.3 哪些规则不应该纳入 OpenSpec这个问题看起来不痛不痒实际决定了这个框架能走多远。如果什么都往里塞规范文件很快就会膨胀成一个没人维护的巨型文档AI 执行也会因上下文过载而变钝。我现在的标准很简单纳入规范的规则必须能影响 AI 的代码生成行为或模块边界。比如“禁止在 service 层直接 new 一个 mapper”这种影响代码结构值得纳入比如“代码风格统一用 4 空格缩进”这个交给格式化工具就行了不进规范再比如“接口文档需要同步更新”这虽然是好习惯但机器很难自动校验写了等于没写。还有一类需要特别警惕的就是和具体实现绑得太死的临时规则。比如针对某个特定 Bug 的修复策略应该只存在于 issue 里而不是写进长期规范。否则三个月后 AI 还在为那个早就不存在的问题做防御性编程白白浪费上下文和性能。4.4 规范老化与被绕过的问题项目跑久了规范老化和被绕过的现象会逐渐凸显。被绕过比较好理解开发者图省事直接手动改代码绕过校验。这时最有效的办法不是加大惩罚而是让校验结果变得“可视化”。我在 CI 里展示一个规范符合率趋势图每个模块的符合率随迭代变化一目了然哪个模块长期下跌问题自然被暴露。规范老化更头疼。业务变了旧规范没删AI 每次都会读取并执行一套过时约束。我在固定节奏里加了一项“规范体检”每两个迭代周期审一次 specs/ 目录检查每个规则是否还有实际场景支撑没有的应用例就标记 deprecated下个周期删除。这套机制虽然简单但能让规范真正“活着”而不是成为数字坟墓。5. 扩展思考规范驱动开发带来的上下游影响OpenSpec 看起来只是在管 AI 的行为但用久了你会发现它的影响会渗透到整个研发生命周期的上下游环节从需求拆解一路延伸到交付质量。5.1 与增量式文档生成、代码评审的配合传统模式里文档是“写出来的”OpenSpec 模式下文档是“长出来的”。因为每个功能模块都自带 spec.md、rules.md 和任务状态新加入的开发者不需要再去翻各种零散文档直接读规范目录就能建立完整心智模型。AI 生成的 PR 描述也可以从决策记录里自动提取做到每次提交都有清晰的背景说明评审者不再需要从几千行 diff 里猜意图。这个转变很微妙但很关键规范驱动让“代码评审”从看写得对不对变成看“代码是否兑现了规范承诺”。评审标准前所未有的统一因为标准在进入评审之前就已经固化了。5.2 对不同规模的团队的落地建议如果你是个人开发者或者三五人小团队OpenSpec 可以不要仪式感目录轻一点规则聚焦一点主要目的是让 AI 干活稳定。如果你的团队超过十人或者并行开发的项目模块比较多则一定要把决策记录和任务状态管理起来。这个阶段规范就是团队内部的“沟通语言”缺失的决策记录会让新人无所适从。超过几十人的大团队我也接触过说实话全量推广 OpenSpec 的阻力不小因为团队行为惯性太重。我的建议是从一个新项目、一个新方向开始做试点用两到三个迭代证明效果再逐步扩展到存量项目别想着一步到位。5.3 下一步可以尝试的优化方向按我自己的实践轨迹下一步值得尝试的方向是把校验结果与测试覆盖率、代码度量数据打通做一个更完整的“工程健康度仪表盘”。另外就是研究多智能体协作模式下OpenSpec 如何在多个 AI Agent 之间共享规范上下文避免几个 Agent 同时改一个领域时规范互相覆盖。这部分我还在试验有了稳定结果会再更新。聊到这里OpenSpec 这套框架能解决的问题和不能覆盖的边界应该都比较清楚了。我自己在写代码时有个习惯每次准备让 AI 动手之前先问自己三个问题规则写清楚了吗校验能抓出来吗这个任务如果三天后再看还能不能看懂为什么这么写如果答案都是肯定的我再让它开工。这套习惯就是从 OpenSpec 的实践中慢慢长出来的现在也分享给你。