1. AI 编程的“失控现场”为什么需要一份强制规范我先说个真实场景。你让 AI 帮你写一个用户登录模块它给你输出一个完整文件看着挺像回事但细看全是问题错误处理只写了主路径、日志字段和你以前用的完全对不上、缩进风格换了三套、连函数命名一会儿驼峰一会儿下划线。更崩溃的是你让它改一个函数它顺手把你另一处好端端的逻辑也重构了。这就是当前 AI 编程最大的痛点模型本身能力很强但完全没有“上下文边界感”和“风格记忆”。每次对话都是新的它不知道你项目的代码规范、目录约定、提交格式、安全底线。你靠口头叮嘱“记住我们的规范”它能记一会儿但对话一长、上下文一挤它就忘了又开始自由发挥。OpenSpec 就是为了解决这个问题出现的。它的核心思路特别直白把规范当成代码一样管理。你写一份项目级别的规则文件把它放在固定位置让 AI 在动手之前必须先读这份规则并且每次生成代码都严格按规则校验。不再是“AI 随意发挥你事后检查”而是“AI 动手之前就被规则锁定”。适合谁用说实话只要你日常用 AI 写代码、改代码、做代码审查不管是个人项目还是团队协作这套思路都值得了解一下。尤其适合已经被 AI“自由发挥”坑过几次、手里有自己技术栈规范、想让 AI 产出更可控的人。2. 规范驱动的核心逻辑把“潜规则”变成“显规则”2.1 从“提示词约束”到“文件级约束”很多人会问我直接把规范写在 system prompt 里不行吗行但这有几个硬伤。第一上下文长度有限。项目规范往往不止十条你把规范写全了留给代码的上下文就少了。第二每次对话都要重新贴换工具、换会话就断了。第三AI 对提示词末尾部分的遵从度远不如对“固定文件”的遵从度高。你让 AI 先读某个文件再干活这个动作是强逻辑绑定你让 AI“记住这些规则”这是软约束随时可能失效。OpenSpec 的做法是把规范做成独立文件通过 CLI 工具统一加载。AI 要执行任务之前先加载规范。规范成了整个生成流程的前置条件而不是可有可无的背景信息。2.2 规范的分层设计用过几周 OpenSpec 之后我觉得它的分层设计是最值得抄的作业。整套体系分成三层全局层绑在你用户目录下不管哪个项目都生效。适合放代码风格、提交消息格式、注释语言等个人偏好。项目层放在仓库里的固定目录每个项目单独配置。适合放技术选型约束、目录结构、禁止使用的模式。任务层针对单个功能或模块写的临时规范任务完成即失效。适合放“本次改造必须满足的验收条件”。这个层次划分解决了一个很实际的问题你不需要一份大而全的“万能规范”去适配所有场景不同层面的规则各有归属互不干扰。2.3 规则不是越多越好是有“触发边界”的我见过有人一口气写了两百多条规范结果 AI 的执行效果反而更差。为什么因为模型面对过多约束时会出现“顾头不顾尾”的情况尤其是相互之间隐含冲突的规则AI 根本无法自己消解。真正的做法是每个规则都要写清楚适用对象和触发条件。比如“所有新增函数必须带 docstring”这个规则就该限定“仅适用于 public 接口”而不是一竿子打倒所有内部工具函数。规则写得越精确AI 执行得越稳定。3. 实操准备安装 OpenSpec 与初始化项目环境3.1 安装方式与版本选择OpenSpec 是一个命令行工具安装方式取决于你用的操作系统。我在 macOS 和 Linux 上都跑过直接用 npm 安装即可npm install -g openspec/cli装完验证一下openspec --version这里有个坑要提前说OpenSpec 迭代速度很快不同版本的规则语法和命令可能有细微差异。建议在项目里固定版本号或者至少让团队的 package.json 锁住版本避免“我这能跑你那报错”的尴尬。如果是 Windows 环境建议配合 Git Bash 或 Windows Terminal 使用避免 PowerShell 的编码问题导致规则文件里的中文乱码。3.2 初始化项目结构在一个已有项目里执行初始化命令openspec init执行完之后你的项目目录下会多出一个.openspec文件夹结构大概是这样的.openspec/ ├── rules/ │ ├── code-style.md │ ├── git-commit.md │ └── security.md ├── templates/ │ └── feature-spec.md └── config.jsonrules目录就是项目规范的存放处每个 md 文件就是一组规则。templates目录放任务规格模板config.json控制 OpenSpec 的整体行为。3.3 config.json 的关键配置项{ extends: [myscope/oss-rules], rules: { enabled: true, strict: true, auto_load: true }, ai_tools: { codex: true, claude: true, cursor: true }, ignore_patterns: [**/dist/**, **/node_modules/**] }几个参数说明一下extends如果你在公司内部发布了通用基础规则包可以直接继承不用每个仓库都复制一份。rules.strict严格模式下AI 生成的内容如果触犯规则会直接报错并拒绝输出宽松模式下只是警告AI 可以无视警告继续。ai_tools声明你主要用哪些 AI 编程工具OpenSpec 会把规范按工具调用的方式做适配。ignore_patterns排除不需要校验的目录比如构建产物、依赖目录。正常情况下auto_load保持开启。这样 AI 工具启动时会自动扫描.openspec目录并加载规范。这个机制非常关键相当于每次动手前 AI 都会先“读一遍公司制度”。4. 核心实操编写规范与接入 AI 编程工具4.1 从零编写第一条有效规范规范文件本身是 Markdown 格式写起来门槛很低。但“有效规范”和“看起来像规范的文字”之间差别很大。我从失败的尝试里总结出一个核心公式每条规范 触发场景 明确要求 禁止行为 示例。四个要素缺一不可。拿前端项目最常见的“fetch 请求封装”举例## API 请求规范 ### 适用场景 所有通过 fetch 或 axios 发起 HTTP 请求的代码。 ### 要求 - 所有请求必须走统一的 request 封装模块禁止直接使用原生 fetch。 - 所有请求必须携带 requestId用于日志追踪。 - 超时时间统一设置为 10s不允许在业务代码中自定义超时。 ### 禁止行为 - 禁止在组件内部直接调用 fetch、axios 或 XMLHttpRequest。 ### 正确示例 import { request } from /utils/request; const data await request(/api/user/info, { timeout: 10000 }); ### 错误示例 const res await fetch(/api/user/info, { timeout: 10 });注意看这条规则的结构。它不是空泛地要求“请封装请求”而是给了 AI 三个维度的硬约束路径约束必须走统一封装、参数约束必须带 requestId、时间约束超时固定 10s并且给了正确和错误的对照示例。实测下来带示例的规则比纯文字描述的规则命中率高出一大截。4.2 规则优先级冲突时听谁的多层规则并存难免出现冲突。全局规则要求“所有代码必须用双引号”项目规则要求“JS/TS 代码用单引号”。这时候听谁的OpenSpec 的优先级设计是越具体的规则越优先任务级 项目级 全局级。项目规则可以覆盖全局规则任务规则可以覆盖项目规则。这个设计很合理因为任务规则往往是专门为某个特殊场景写的不应该被全局风格约束卡死。但这里有个细节如果你在 config.json 里把strict设为 true冲突覆盖依然会生效。OpenSpec 不会因为某条规则被覆盖就报警因为它把“覆盖”视为合法行为。这一点和许多理解中“严格模式下规则不可覆盖”的直觉不同。4.3 与常见 AI 编程工具的接入方式OpenSpec 目前支持几个主流 AI 编程工具接入方式基本都是“复制一段引导文本放进配置”。以 Codex 为例你需要在它的配置里加入这段引导在开始任何代码任务之前请先查看项目根目录的 .openspec 目录 加载其中的所有规则并严格遵循规则执行。 如果规则与用户直接指令冲突以规则为准并向用户说明冲突原因。加了这段引导之后Codex 每次接到任务的第一件事就是读取.openspec目录。它读不读、读到什么程度决定了你的规范是否真正生效。而像 Claude Code 这类支持工具调用协议的工具OpenSpec 可以走自动化扫描。在 config.json 里声明claude: true之后工具启动时会通过规范目录的元数据自动完成加载不太需要手动干预。4.4 实战记录用规范驱动改造一个遗留模块理论说再多不如看一次完整流程。我随便挑一个实际项目里的例子。任务背景老项目里有个订单模块代码风格混乱有直接写 SQL 的地方有在视图层拼字符串的情况日志字段也五花八门。让 AI 直接重构它很可能只是把代码揉了揉换了个排版就算完事。所以我先写了一份针对本次重构的任务级规范放进.openspec/rules/下## 订单模块重构规范临时任务级 ### 适用范围 仅限 order 目录下的所有文件。 ### 硬性要求 - 所有数据查询必须走 OrderRepository禁止在 Controller 中直接使用 QueryBuilder。 - 所有金额字段必须用 Decimal 类型禁止用 Number。 - 日志必须统一走 LoggerFactory.getLogger(当前类名) 方式获取实例。 - 每个对外接口必须包含 3 层日志请求入参、处理结果、异常堆栈。然后我把任务交给 AI说明“你的任务是重构订单模块先读 .openspec 下的规范再动手”。实测下来的效果AI 生成的所有 Controller 都干净了没有一条 SQL 泄漏到 Controller 层金额类型全部换成了 Decimal日志也按要求打了三层。更明显的差异是那次重构完几乎不需要我逐行审查业务逻辑的边界情况。这在以前是不可想象的——以前 AI 输出的代码总是漏掉异常分支。5. 避坑指南与常见问题速查5.1 这些语法细节容易踩坑正则表达式的使用场景有限。OpenSpec 的规则文件支持正则匹配但不要滥用。对路径敏感的场景比如“禁止修改 auth 模块下的文件”用路径匹配即可对内容判断用自然语言表达更可靠。AI 理解自然语言的能力远强于你对正则表达式的把控能力。glob 模式的限制。在写ignore_patterns或规则适用路径时务必确认 glob 模式是否符合预期。比如**/test/**和**/test/*的匹配范围有差别前者匹配所有层级的 test 目录后者只匹配直接子目录。文件编码格式。Windows 下如果规则文件被保存为 UTF-8 with BOMCLI 解析时可能出现奇怪的问题。建议统一用 UTF-8 无 BOM 格式保存。5.2 常见问题速查表现象原因解决方案AI 不读规范文件引导文本没加进工具配置在 AI 工具配置中追加“先读 .openspec”引导语规范生效但执行不稳定规则描述存在歧义精简规则数量每条规则只表达一个明确约束规则太多导致 AI 拒绝输出规则间隐含冲突检查规则优先级删除相互矛盾的条目Windows 下中文规则乱码编码格式问题统一转成 UTF-8 无 BOM更新 CLI 后行为异常版本间不兼容在 package.json 锁定 openspec/cli 版本5.3 一个常被忽视的“杀手级”用法提交前规则校验很多人把 OpenSpec 局限在“AI 生成代码时约束行为”其实它还适合做提交前的规则校验。把规则校验集成到 git pre-commit hook 里效果非常直接openspec validate --staged这条命令会检查暂存区的文件看它们是否满足项目规范。AI 写的代码如果有违规项直接拦截在提交前。我在团队里把这条命令接进了 husky 的 pre-commit从那以后规范遭到“漏网之鱼”的概率低了很多。这个用法对人工写代码同样有效。6. 关于 OpenSpec 的扩展思考与我的使用体会OpenSpec 最触动我的地方不是它“能管住 AI”而是它逼着我重新梳理了自己项目的到底有哪些不成文的规则。过去我在项目里积累的规范——文件命名习惯、目录划分逻辑、异常处理偏好、代码风格要求——大多都存在自己脑子里从来没有被显式地写下来过。OpenSpec 强制我把这些隐性知识外化成文档这对项目本身的价值甚至大于约束 AI 的价值。哪怕完全抛开 AI光是把团队里那些“大家默认该这么做”的东西落成规范化文件就已经赚回了使用成本。有一点要明确OpenSpec 不是万能的。它做的是“约束”不是“理解”。你给出清晰的规范AI 的产出会稳定得多但如果你不知道自己想要什么规范写得含糊其辞AI 照样会给你一份“看起来不错”但经不起推敲的结果。工具能放大你已有的工程素养不能替你思考。从我个人的实际体验来看OpenSpec 让我最舒心的一点是我重新拿回了对 AI 代码的“预期控制权”不用每次都对着一堆陌生的输出做临场判断。它适合所有想把 AI 编程从“开着跑”变成“在轨道上跑”的人。我的建议是先从你的项目里挑一个真正反复出问题的场景写一份针对它的规范跑通一次全流程再逐步扩大覆盖范围。规范驱动这件事最重要的是先跑起来。