如果你第一次听说 OpenSpec (SDD)大概率会冒出一个念头开发不写代码先写规格这不是又回到文档先行的老路了吗。说实话我一开始也是这个想法直到自己在一个需求经常做到一半就改口的项目里被反复坑了几次才意识到规格驱动开发想解决的恰恰是这个痛点。这篇文章不打算给你讲一堆 SDD 概念而是把我在 Windows 上从零安装 OpenSpec 的完整过程、撞过的报错、以及每个报错背后的排查思路原原本本写下来。如果你正被环境配置卡住可以直接跳到第 4 节对号入座。1. SDD 到底改变了什么为什么一个写文档的工具值得折腾很多人对规格驱动开发的第一反应是倒退觉得敏捷都提倡可工作的软件胜过详尽的文档了你还让我先写规格这里其实有个理解偏差。SDD 不是要求你写几十页没人看的 Word 文档而是把系统要做什么、为什么做、怎么验收用结构化的、可评审的文本固定下来让它在编码之前就变成团队共识。1.1 规格驱动的核心不是写文档是风险前置想象一个特别常见的场景需求方口头说了一个功能开发理解成 A测试理解成 B等联调的时候发现完全是两套认知。返工的成本是翻倍的因为代码已经写了测试用例已经写了进度已经报了这时候再改谁都不痛快。SDD 的做法是在动手写代码之前先把系统应该做什么、为什么做、怎么做写成一份足够小、足够明确的规格。它不追求面面俱到只要求把变更说清楚。关键动作是评审——规格写完后不是直接丢给开发而是先让相关角色看一遍把理解偏差消灭在编码之前。这几十分钟的评审时间比后面几天返工划算得多。我以前总以为想清楚了自然就能写清楚后来发现恰恰相反写作这个动作本身就是强制你面对模糊地带的过程。很多好像想清楚了的需求一旦落到纸面上立刻会暴露问题边界条件没定义、失败场景没考虑、验收标准含糊不清。SDD 的隐性价值就在这里。1.2 OpenSpec 在 SDD 工作流里的位置OpenSpec 是一个命令行工具它把 SDD 的流程变成一串可执行的动作新建规格、列出全部规格、生成变更记录、检查规格格式是否合规。规格文件不是躺在某个共享盘里而是和代码放在同一个仓库的specs目录下和 Git 分支、提交记录绑在一起。你大概可以把它理解成建筑施工图。过去我们习惯拿着一张草图就开工结果砌墙砌到一半发现窗户位置不对OpenSpec 做的事不是逼你多写一堆文档而是让图纸先于施工存在并且图纸本身可以被检查、被评审、被回溯。一份规格改过几个版本、为什么改、谁批准的全部有迹可循。所以我说值得为它配置环境。不是因为工具本身多炫酷而是它背后那套流程确实能省下真实的返工成本。工具装好只是一个开始环境问题恰恰是第一个劝退点这也是标题想表达的意思——别让环境配置挡住你。1.3 它和 TDD、ADR 不是一回事有朋友会问这不就是测试驱动开发吗还真不是。TDD 是先写失败测试再写实现让测试变绿它约束的是技术层面的行为SDD 约束的是业务层面的变更描述。测试告诉你代码是否符合预期规格告诉你这个预期本身是不是大家想要的。还有人会联想到架构决策记录ADR。ADR 侧重记录为什么当初选了某个技术方案OpenSpec 的规格则更像这次变更要做什么、改成什么样、验收标准是什么。两者可以共存但关注点完全不同。把这几个概念分清楚你才不会在安装完之后不知道该拿它干嘛。1.4 初期的成本和收益说句实在话刚开始推广 SDD 的团队前几个迭代一定会觉得变慢了。因为要把模糊的需求翻译成结构化描述逼着产品、开发、测试在前期就坐在一起把细节掰扯清楚这比直接闷头写代码要费时间。但收益出现在需求频繁变更的项目里改动的冲击还在纸面上时就被发现而不是在几百行代码里推倒重来。所以我的建议是别拿核心业务的大项目直接试水先选一个中等规模、需求本来就容易变的项目跑两三个迭代环境安装只是第一关后面真正要过的关是团队习惯。2. 安装前最容易忽略的三件事版本、终端、目录在 Windows 上装命令行工具最气人的一点是官方文档明明写着一条命令搞定你照着敲就是报错。原因通常不是工具本身有问题而是 Windows 的环境变量、执行策略、权限模型和文档默认假设的 macOS/Linux 环境差异太大。所以在敲安装命令之前先把三件基础事过一遍。2.1 先把 Node.js 版本对齐而不是能跑就行OpenSpec 是命令行工具跑在 Node.js 运行时上。很多人卡住的第一个点不是安装命令而是本机 Node 版本太老或者太新。老版本缺少新版语法支持太新的版本有时会遇到工具依赖还没适配的情况。我的建议是尽量用 LTS 长期支持版本并且别混用两个不稳定的大版本。安装前先执行两条命令看看家底node -v npm -v如果你看到的 Node 主版本号特别低建议去官网下载当前 LTS 版覆盖安装。覆盖安装一般不会破坏已有项目但装完一定要重开终端确认node -v指向的是新版。这里多说一句为什么版本这么重要CLI 工具本质是跑在 Node 环境里的应用程序它的依赖解析、语法特性、内置 API 全跟随 Node 版本走。版本不对安装阶段可能很顺利运行阶段才爆出莫名其妙的问题到时候你很难联想到是 Node 版本的问题。2.2 终端选择用 PowerShell而不是 CMD装命令行工具终端是绕不开的。Windows 上最常见的两个终端是 CMD 和 PowerShell。OpenSpec 这类工具两者都能用但我强烈建议用 PowerShell 作为主终端。不是说 CMD 无法安装而是 CMD 的输出格式、错误信息展示都弱一些。排查问题的时候你希望终端尽可能提供完整信息PowerShell 在这方面明显更好。另外一个原因和第 4 节的报错有关PowerShell 有执行策略的概念CMD 没有。提前用 PowerShell等于把潜在问题提前暴露出来总好过装完才发现脚本跑不了。2.3 检查 Git 和项目路径别装完了才后悔OpenSpec 初始化仓库时要操作 Git所以本机最好有 Git 客户端。安装前随手验证一下git --version如果这行命令都报错先把 Git 装上否则后面openspec init大概率会在初始化阶段失败而且报错信息看起来跟 Git 一点关系都没有容易误判。另外提醒一句如果你的 Windows 用户名是中文或者准备把项目放在带空格的路径下比如C:\Program Files\xxx建议换个位置。这不是 OpenSpec 的锅而是很多 Node 工具链在解析路径时对空格和中文支持不友好。把项目目录放在D:\workspace\项目名这种纯英文、无空格的路径下能省掉很多玄学问题。装之前对照下面这张表过一遍检查项检查命令期望结果Node.js 运行时node -vLTS 版本即可包管理器npm -v能输出版本号Git 客户端git --version能输出版本号终端环境打开 PowerShell正常执行命令项目路径pwd纯英文、无空格这三件事五分钟就能检查完却决定了你后面是一路绿灯还是步步踩坑。3. 从空终端到第一个 spec完整安装路径环境检查没问题就可以开始安装了。这一节我按完整路径走一遍从安装命令到跑通第一个规格文件。3.1 一条命令全局安装但包名要以官方文档为准打开 PowerShell执行全局安装。这里我用一个示意包名举例你实际操作时以官方仓库 README 给出的包名为准npm install -g openspec为什么不装在项目里因为 OpenSpec 属于跨项目使用的流程工具它的职责是管理规格文件、生成变更记录和某个具体业务项目的依赖没有关系。全局安装后在任何目录下都能直接调用省心很多。安装完成后如果终端没有报错理论上命令就已经可用了。此时可以先试探一下版本号openspec --version如果这一步就开始报错别慌直接跳到第 4 节对照排查。如果顺利输出了版本号继续往下走。3.2 验证安装的三种方式有朋友安装完看到版本号就宣布大功告成我建议再多做两步因为 Windows 上很容易出现系统里藏着一个同名旧命令的情况。除了--version我习惯依次做三个验证openspec --version看版本确认工具本体可用。openspec --help看它支持哪些子命令这比翻 README 更直接也顺便暴露命令解析问题。在 PowerShell 里用Get-Command openspec查看命令的完整路径确保你调用的确实是你刚装的那个。第三步尤其重要。Windows 的 PATH 解析顺序可能导致你实际调用的是某个目录下的旧版本或同名程序。看到完整路径等于排除了这个隐患。3.3 初始化仓库并创建第一个规格找一个空目录开始实践mkdir demo-sdd cd demo-sdd git init openspec initopenspec init会在当前目录生成specs/目录结构和基础模板。如果这一步报了 Git 相关错误回去检查第 2.3 节大概率是 Git 没装或者没加入 PATH。初始化成功之后试着创建一个规格文件。不同版本的子命令名称可能略有区别常见形式是openspec create first-feature创建后会生成一个 markdown 模板文件里面通常会包含这些字段背景说明、决策内容、变更范围、验收标准。把模板逐项填完哪怕只是填写一个最简功能也算跑通了最小闭环。填完规格文件后可以再用命令检查一下规格状态。你会发现它已经被识别为一条待处理的变更记录。到这个节点OpenSpec 才算是真正能用而不只是装好。4. Windows 报错全记录我的排查链路与最终修复这一节是重点我不直接给答案而是把每种报错的排查思路一起写出来。因为报错只是表象你真正需要的是下次遇到类似问题怎么定位的方法。4.1 禁止运行脚本PowerShell 执行策略不是玄学现象很经典第一次运行openspec --helpPowerShell 直接拒绝执行报错内容大致是因为在此系统上禁止运行脚本。有关详细信息请参阅 about_Execution_Policies。很多人的第一反应是那我换 CMD 跑。换终端确实能绕过去但治标不治本因为 OpenSpec 后续的辅助脚本、自动化任务仍然要经 PowerShell 执行你不可能每次都切终端。排查链路先看当前执行策略Get-ExecutionPolicy -List。你会看到系统级策略是Restricted而当前用户的策略是Undefined。Undefined意味着继承系统级设置所以整个会话都被限制住了。只修改当前用户的策略不动系统级设置Set-ExecutionPolicy RemoteSigned -Scope CurrentUser重新打开终端再跑一次命令通常就通了。为什么用RemoteSigned而不是BypassBypass等于关闭所有脚本执行限制方便是方便但恶意脚本也可以畅通无阻。RemoteSigned的意思是本机创建的脚本可以运行从远程下载的脚本必须有数字签名这是官方推荐给开发者的折中方案。4.2 EPERM 与 EACCESnpm 全局安装为什么没有权限另一个高频报错发生在安装阶段终端输出一堆红色错误里面带EPERM或EACCES末尾还提示你请尝试以管理员身份运行。我第一次遇到时直接右键管理员重开终端确实装上了但后来每次操作都可能碰到权限问题。后来才搞清楚根治方法不是抬升安装权限而是把 npm 的全局安装目录挪到用户目录。排查链路查看当前全局目录npm prefix -g。默认它指向 Node 安装目录下的node_modules这个目录通常受系统保护普通权限写不进去。在用户目录下新建一个文件夹比如C:\Users\你的用户名\AppData\Local\npm-global。修改 npm 全局前缀npm config set prefix C:\Users\你的用户名\AppData\Local\npm-global把这个目录加到用户 PATH保证命令随处可用。为什么比管理员运行更干净因为管理员运行只是把安装那一步的权限抬高了后续工具运行时写日志、写缓存、写配置文件依然会遇到权限冲突。把全局目录放在用户级别是从根源上避开问题之后装其他命令行工具也一劳永逸。4.3 命令找不到PATH 不刷新与 npm 全局目录排查这个坑的迷惑性最强安装时没有任何报错但重开终端后输入openspec却提示不是内部或外部命令或无法识别。排查链路先确认装到哪了npm prefix -g。如果显示的是刚改过的npm-global目录问题大概率出在 PATH 没包含它。查看当前 PATHecho $env:PATH。确认npm-global目录是否在列表里。如果不在把它加入用户环境变量 PATH。改完一定重开终端而不是在当前会话里手动刷新。因为终端在启动时才读取 PATH不重开就不会生效。如果 PATH 里有这个目录还是不行用Get-Command openspec看看它实际解析到哪个路径。很可能系统里有个同名旧命令排在前面抢了解析权。这个坑的本质是PATH 生效时机 解析顺序问题和 OpenSpec 本身一点关系都没有。遇到这种情况别急着重装先看解析路径。4.4 初始化时的 Git 报错与 Node 版本 engines 报错openspec init阶段常见的报错有两类。第一类提示找不到 Git。OpenSpec 初始化时要操作.git目录如果本机没装 Git 或 Git 不在 PATH 里就会在这一步失败。排查方式就是git --version没有就装一个装完注意勾选添加到 PATH的选项然后重开终端。第二类报错和 Node 版本有关错误信息里通常会直接写出你当前的版本和工具要求的版本范围。这类问题建议用 Node 版本管理工具来切换比卸载重装快得多。装好版本管理工具后在项目目录里锁定一个 LTS 版本再重跑初始化。为什么这类问题集中在初始化阶段爆发因为初始化命令会触发规格目录创建、模板解析、Git 关联等一系列底层操作对运行时的特性要求较高。版本不满足时安装阶段不一定拦得住反而是真正开始干活的时候才会暴露。4.5 容易被误诊的两个坑杀软拦截、路径空格还有两个坑的报错信息非常诡异容易被误判成工具问题。第一个是杀毒软件或系统防护把 OpenSpec 生成临时文件的行为当成可疑操作。表现是命令执行到一半突然中断没有明确的错误码。排查方法是暂时关闭实时防护后再重跑一次如果恢复正常就把变量的工作目录加入白名单。第二个是路径中的空格。项目路径如果是C:\Program Files\xxx这种带空格的路径某些内部脚本在做字符串拼接时会把命令拆断报错千奇百怪。最省心的办法就是把项目放在D:\workspace\xx这种纯英文无空格的路径下。这两个坑的共同特点是报错信息跟实际原因对不上。我的经验是遇到时好时坏、报错怪异的情况优先怀疑三个条件——权限、PATH、路径特殊字符。下面的表可以留着以后排查用现象根因方向快速定位命令修复方式提示禁止运行脚本PowerShell 执行策略Get-ExecutionPolicy -List设置RemoteSigned安装报 EPERM/EACCES全局目录无写权限npm prefix -g改用户级 prefix命令找不到PATH 未生效Get-Command openspec加 PATH 并重开终端init 报 Git 错误Git 未安装/未入 PATHgit --version安装并加入 PATHinit 报版本错误Node 版本不匹配node -v切换 LTS 版本执行中断无报错杀软拦截关闭实时防护测试加入白名单执行命令路径被拆断路径含空格pwd改纯英文路径5. 装完之后最重要的习惯把环境检查当成最小闭环的一部分装完不是终点跑通一个最小闭环才算数。我在新机器上配置完 OpenSpec 之后一定会按固定顺序做一遍验证不让环境问题留到三天后才发现。5.1 安装后立刻跑的五个验证命令每次都执行五个动作node -v确认运行时正常。openspec --version确认工具本体可用。openspec --help确认子命令都可以正常解析。在一个临时目录执行git init openspec init确认规格目录结构能自动创建。创建一个样例规格并打开检查模板完整性。五步全部通过才算真正装好了。只看到版本号就收工的同学后面很容易撞上第 4.4 节那两个初始化报错。为什么推荐把验证做成固定流程因为环境配置最怕的是当时能用过几天不知道动了一下什么又不能用了。有了这个最小闭环环境出问题时可以快速定位是 Node 版本变了还是 PATH 被别的软件改了还是 Git 没装好。每次都在同一套验证基准上排查问题范围会缩得很小。5.2 用版本锁定文件减少团队环境差异如果你打算在团队里推广 OpenSpec一定要让成员的 Node 版本和工具版本保持一致。做法不复杂在项目根目录放一个版本锁定文件或者在项目文档里明确写清楚本仓库要求 Node 版本、OpenSpec 版本分别是多少。这件事看起来很小但团队里最常见的在我机器上是好的问题十有八九是版本不一致造成的。规格文件本身是文本理论上有兼容性但它的读写依赖 CLI 行为不同版本之间可能有差异。统一版本能省掉大量无意义的沟通成本。5.3 我给新人的最小 SDD 启动流程最后分享一个我推荐给新人的启动方式适合刚接触 SDD 的团队选一个中等规模、需求变更频繁的项目当实验田别拿核心业务直接试水。只从一个功能规格开始不要一次性铺开全套流程。规格写完先拉人评审评审通过再开始编码。功能完成后回到规格文件逐条核对验收标准。一旦发现规格和实现有偏差先改规格再改代码把这件事变成习惯。这套流程跑两三个迭代之后你自然能体会 OpenSpec 的价值。环境配置只是第一道门槛真正的门槛是团队愿不愿意在动手前先把事情说清楚。我个人在实践里最大的感受是OpenSpec 这类工具装起来并不难难的是 Windows 上各种环境因素叠加在一起时你很容易把时间花在这个报错到底是谁造成的上面。如果你正被某个报错卡住我建议先别急着反复重装按第 4 节的顺序把 Node、权限、PATH、Git 这四个最基础的环节过一遍效率会高很多。另外一个小技巧每次改完环境变量或执行策略后都重开一个全新的终端窗口再验证很多看起来改了没用的问题其实只是忘了这一步。
如果你第一次听说 OpenSpec (SDD)大概率会冒出一个念头开发不写代码先写规格这不是又回到文档先行的老路了吗。说实话我一开始也是这个想法直到自己在一个需求经常做到一半就改口的项目里被反复坑了几次才意识到规格驱动开发想解决的恰恰是这个痛点。这篇文章不打算给你讲一堆 SDD 概念而是把我在 Windows 上从零安装 OpenSpec 的完整过程、撞过的报错、以及每个报错背后的排查思路原原本本写下来。如果你正被环境配置卡住可以直接跳到第 4 节对号入座。1. SDD 到底改变了什么为什么一个写文档的工具值得折腾很多人对规格驱动开发的第一反应是倒退觉得敏捷都提倡可工作的软件胜过详尽的文档了你还让我先写规格这里其实有个理解偏差。SDD 不是要求你写几十页没人看的 Word 文档而是把系统要做什么、为什么做、怎么验收用结构化的、可评审的文本固定下来让它在编码之前就变成团队共识。1.1 规格驱动的核心不是写文档是风险前置想象一个特别常见的场景需求方口头说了一个功能开发理解成 A测试理解成 B等联调的时候发现完全是两套认知。返工的成本是翻倍的因为代码已经写了测试用例已经写了进度已经报了这时候再改谁都不痛快。SDD 的做法是在动手写代码之前先把系统应该做什么、为什么做、怎么做写成一份足够小、足够明确的规格。它不追求面面俱到只要求把变更说清楚。关键动作是评审——规格写完后不是直接丢给开发而是先让相关角色看一遍把理解偏差消灭在编码之前。这几十分钟的评审时间比后面几天返工划算得多。我以前总以为想清楚了自然就能写清楚后来发现恰恰相反写作这个动作本身就是强制你面对模糊地带的过程。很多好像想清楚了的需求一旦落到纸面上立刻会暴露问题边界条件没定义、失败场景没考虑、验收标准含糊不清。SDD 的隐性价值就在这里。1.2 OpenSpec 在 SDD 工作流里的位置OpenSpec 是一个命令行工具它把 SDD 的流程变成一串可执行的动作新建规格、列出全部规格、生成变更记录、检查规格格式是否合规。规格文件不是躺在某个共享盘里而是和代码放在同一个仓库的specs目录下和 Git 分支、提交记录绑在一起。你大概可以把它理解成建筑施工图。过去我们习惯拿着一张草图就开工结果砌墙砌到一半发现窗户位置不对OpenSpec 做的事不是逼你多写一堆文档而是让图纸先于施工存在并且图纸本身可以被检查、被评审、被回溯。一份规格改过几个版本、为什么改、谁批准的全部有迹可循。所以我说值得为它配置环境。不是因为工具本身多炫酷而是它背后那套流程确实能省下真实的返工成本。工具装好只是一个开始环境问题恰恰是第一个劝退点这也是标题想表达的意思——别让环境配置挡住你。1.3 它和 TDD、ADR 不是一回事有朋友会问这不就是测试驱动开发吗还真不是。TDD 是先写失败测试再写实现让测试变绿它约束的是技术层面的行为SDD 约束的是业务层面的变更描述。测试告诉你代码是否符合预期规格告诉你这个预期本身是不是大家想要的。还有人会联想到架构决策记录ADR。ADR 侧重记录为什么当初选了某个技术方案OpenSpec 的规格则更像这次变更要做什么、改成什么样、验收标准是什么。两者可以共存但关注点完全不同。把这几个概念分清楚你才不会在安装完之后不知道该拿它干嘛。1.4 初期的成本和收益说句实在话刚开始推广 SDD 的团队前几个迭代一定会觉得变慢了。因为要把模糊的需求翻译成结构化描述逼着产品、开发、测试在前期就坐在一起把细节掰扯清楚这比直接闷头写代码要费时间。但收益出现在需求频繁变更的项目里改动的冲击还在纸面上时就被发现而不是在几百行代码里推倒重来。所以我的建议是别拿核心业务的大项目直接试水先选一个中等规模、需求本来就容易变的项目跑两三个迭代环境安装只是第一关后面真正要过的关是团队习惯。2. 安装前最容易忽略的三件事版本、终端、目录在 Windows 上装命令行工具最气人的一点是官方文档明明写着一条命令搞定你照着敲就是报错。原因通常不是工具本身有问题而是 Windows 的环境变量、执行策略、权限模型和文档默认假设的 macOS/Linux 环境差异太大。所以在敲安装命令之前先把三件基础事过一遍。2.1 先把 Node.js 版本对齐而不是能跑就行OpenSpec 是命令行工具跑在 Node.js 运行时上。很多人卡住的第一个点不是安装命令而是本机 Node 版本太老或者太新。老版本缺少新版语法支持太新的版本有时会遇到工具依赖还没适配的情况。我的建议是尽量用 LTS 长期支持版本并且别混用两个不稳定的大版本。安装前先执行两条命令看看家底node -v npm -v如果你看到的 Node 主版本号特别低建议去官网下载当前 LTS 版覆盖安装。覆盖安装一般不会破坏已有项目但装完一定要重开终端确认node -v指向的是新版。这里多说一句为什么版本这么重要CLI 工具本质是跑在 Node 环境里的应用程序它的依赖解析、语法特性、内置 API 全跟随 Node 版本走。版本不对安装阶段可能很顺利运行阶段才爆出莫名其妙的问题到时候你很难联想到是 Node 版本的问题。2.2 终端选择用 PowerShell而不是 CMD装命令行工具终端是绕不开的。Windows 上最常见的两个终端是 CMD 和 PowerShell。OpenSpec 这类工具两者都能用但我强烈建议用 PowerShell 作为主终端。不是说 CMD 无法安装而是 CMD 的输出格式、错误信息展示都弱一些。排查问题的时候你希望终端尽可能提供完整信息PowerShell 在这方面明显更好。另外一个原因和第 4 节的报错有关PowerShell 有执行策略的概念CMD 没有。提前用 PowerShell等于把潜在问题提前暴露出来总好过装完才发现脚本跑不了。2.3 检查 Git 和项目路径别装完了才后悔OpenSpec 初始化仓库时要操作 Git所以本机最好有 Git 客户端。安装前随手验证一下git --version如果这行命令都报错先把 Git 装上否则后面openspec init大概率会在初始化阶段失败而且报错信息看起来跟 Git 一点关系都没有容易误判。另外提醒一句如果你的 Windows 用户名是中文或者准备把项目放在带空格的路径下比如C:\Program Files\xxx建议换个位置。这不是 OpenSpec 的锅而是很多 Node 工具链在解析路径时对空格和中文支持不友好。把项目目录放在D:\workspace\项目名这种纯英文、无空格的路径下能省掉很多玄学问题。装之前对照下面这张表过一遍检查项检查命令期望结果Node.js 运行时node -vLTS 版本即可包管理器npm -v能输出版本号Git 客户端git --version能输出版本号终端环境打开 PowerShell正常执行命令项目路径pwd纯英文、无空格这三件事五分钟就能检查完却决定了你后面是一路绿灯还是步步踩坑。3. 从空终端到第一个 spec完整安装路径环境检查没问题就可以开始安装了。这一节我按完整路径走一遍从安装命令到跑通第一个规格文件。3.1 一条命令全局安装但包名要以官方文档为准打开 PowerShell执行全局安装。这里我用一个示意包名举例你实际操作时以官方仓库 README 给出的包名为准npm install -g openspec为什么不装在项目里因为 OpenSpec 属于跨项目使用的流程工具它的职责是管理规格文件、生成变更记录和某个具体业务项目的依赖没有关系。全局安装后在任何目录下都能直接调用省心很多。安装完成后如果终端没有报错理论上命令就已经可用了。此时可以先试探一下版本号openspec --version如果这一步就开始报错别慌直接跳到第 4 节对照排查。如果顺利输出了版本号继续往下走。3.2 验证安装的三种方式有朋友安装完看到版本号就宣布大功告成我建议再多做两步因为 Windows 上很容易出现系统里藏着一个同名旧命令的情况。除了--version我习惯依次做三个验证openspec --version看版本确认工具本体可用。openspec --help看它支持哪些子命令这比翻 README 更直接也顺便暴露命令解析问题。在 PowerShell 里用Get-Command openspec查看命令的完整路径确保你调用的确实是你刚装的那个。第三步尤其重要。Windows 的 PATH 解析顺序可能导致你实际调用的是某个目录下的旧版本或同名程序。看到完整路径等于排除了这个隐患。3.3 初始化仓库并创建第一个规格找一个空目录开始实践mkdir demo-sdd cd demo-sdd git init openspec initopenspec init会在当前目录生成specs/目录结构和基础模板。如果这一步报了 Git 相关错误回去检查第 2.3 节大概率是 Git 没装或者没加入 PATH。初始化成功之后试着创建一个规格文件。不同版本的子命令名称可能略有区别常见形式是openspec create first-feature创建后会生成一个 markdown 模板文件里面通常会包含这些字段背景说明、决策内容、变更范围、验收标准。把模板逐项填完哪怕只是填写一个最简功能也算跑通了最小闭环。填完规格文件后可以再用命令检查一下规格状态。你会发现它已经被识别为一条待处理的变更记录。到这个节点OpenSpec 才算是真正能用而不只是装好。4. Windows 报错全记录我的排查链路与最终修复这一节是重点我不直接给答案而是把每种报错的排查思路一起写出来。因为报错只是表象你真正需要的是下次遇到类似问题怎么定位的方法。4.1 禁止运行脚本PowerShell 执行策略不是玄学现象很经典第一次运行openspec --helpPowerShell 直接拒绝执行报错内容大致是因为在此系统上禁止运行脚本。有关详细信息请参阅 about_Execution_Policies。很多人的第一反应是那我换 CMD 跑。换终端确实能绕过去但治标不治本因为 OpenSpec 后续的辅助脚本、自动化任务仍然要经 PowerShell 执行你不可能每次都切终端。排查链路先看当前执行策略Get-ExecutionPolicy -List。你会看到系统级策略是Restricted而当前用户的策略是Undefined。Undefined意味着继承系统级设置所以整个会话都被限制住了。只修改当前用户的策略不动系统级设置Set-ExecutionPolicy RemoteSigned -Scope CurrentUser重新打开终端再跑一次命令通常就通了。为什么用RemoteSigned而不是BypassBypass等于关闭所有脚本执行限制方便是方便但恶意脚本也可以畅通无阻。RemoteSigned的意思是本机创建的脚本可以运行从远程下载的脚本必须有数字签名这是官方推荐给开发者的折中方案。4.2 EPERM 与 EACCESnpm 全局安装为什么没有权限另一个高频报错发生在安装阶段终端输出一堆红色错误里面带EPERM或EACCES末尾还提示你请尝试以管理员身份运行。我第一次遇到时直接右键管理员重开终端确实装上了但后来每次操作都可能碰到权限问题。后来才搞清楚根治方法不是抬升安装权限而是把 npm 的全局安装目录挪到用户目录。排查链路查看当前全局目录npm prefix -g。默认它指向 Node 安装目录下的node_modules这个目录通常受系统保护普通权限写不进去。在用户目录下新建一个文件夹比如C:\Users\你的用户名\AppData\Local\npm-global。修改 npm 全局前缀npm config set prefix C:\Users\你的用户名\AppData\Local\npm-global把这个目录加到用户 PATH保证命令随处可用。为什么比管理员运行更干净因为管理员运行只是把安装那一步的权限抬高了后续工具运行时写日志、写缓存、写配置文件依然会遇到权限冲突。把全局目录放在用户级别是从根源上避开问题之后装其他命令行工具也一劳永逸。4.3 命令找不到PATH 不刷新与 npm 全局目录排查这个坑的迷惑性最强安装时没有任何报错但重开终端后输入openspec却提示不是内部或外部命令或无法识别。排查链路先确认装到哪了npm prefix -g。如果显示的是刚改过的npm-global目录问题大概率出在 PATH 没包含它。查看当前 PATHecho $env:PATH。确认npm-global目录是否在列表里。如果不在把它加入用户环境变量 PATH。改完一定重开终端而不是在当前会话里手动刷新。因为终端在启动时才读取 PATH不重开就不会生效。如果 PATH 里有这个目录还是不行用Get-Command openspec看看它实际解析到哪个路径。很可能系统里有个同名旧命令排在前面抢了解析权。这个坑的本质是PATH 生效时机 解析顺序问题和 OpenSpec 本身一点关系都没有。遇到这种情况别急着重装先看解析路径。4.4 初始化时的 Git 报错与 Node 版本 engines 报错openspec init阶段常见的报错有两类。第一类提示找不到 Git。OpenSpec 初始化时要操作.git目录如果本机没装 Git 或 Git 不在 PATH 里就会在这一步失败。排查方式就是git --version没有就装一个装完注意勾选添加到 PATH的选项然后重开终端。第二类报错和 Node 版本有关错误信息里通常会直接写出你当前的版本和工具要求的版本范围。这类问题建议用 Node 版本管理工具来切换比卸载重装快得多。装好版本管理工具后在项目目录里锁定一个 LTS 版本再重跑初始化。为什么这类问题集中在初始化阶段爆发因为初始化命令会触发规格目录创建、模板解析、Git 关联等一系列底层操作对运行时的特性要求较高。版本不满足时安装阶段不一定拦得住反而是真正开始干活的时候才会暴露。4.5 容易被误诊的两个坑杀软拦截、路径空格还有两个坑的报错信息非常诡异容易被误判成工具问题。第一个是杀毒软件或系统防护把 OpenSpec 生成临时文件的行为当成可疑操作。表现是命令执行到一半突然中断没有明确的错误码。排查方法是暂时关闭实时防护后再重跑一次如果恢复正常就把变量的工作目录加入白名单。第二个是路径中的空格。项目路径如果是C:\Program Files\xxx这种带空格的路径某些内部脚本在做字符串拼接时会把命令拆断报错千奇百怪。最省心的办法就是把项目放在D:\workspace\xx这种纯英文无空格的路径下。这两个坑的共同特点是报错信息跟实际原因对不上。我的经验是遇到时好时坏、报错怪异的情况优先怀疑三个条件——权限、PATH、路径特殊字符。下面的表可以留着以后排查用现象根因方向快速定位命令修复方式提示禁止运行脚本PowerShell 执行策略Get-ExecutionPolicy -List设置RemoteSigned安装报 EPERM/EACCES全局目录无写权限npm prefix -g改用户级 prefix命令找不到PATH 未生效Get-Command openspec加 PATH 并重开终端init 报 Git 错误Git 未安装/未入 PATHgit --version安装并加入 PATHinit 报版本错误Node 版本不匹配node -v切换 LTS 版本执行中断无报错杀软拦截关闭实时防护测试加入白名单执行命令路径被拆断路径含空格pwd改纯英文路径5. 装完之后最重要的习惯把环境检查当成最小闭环的一部分装完不是终点跑通一个最小闭环才算数。我在新机器上配置完 OpenSpec 之后一定会按固定顺序做一遍验证不让环境问题留到三天后才发现。5.1 安装后立刻跑的五个验证命令每次都执行五个动作node -v确认运行时正常。openspec --version确认工具本体可用。openspec --help确认子命令都可以正常解析。在一个临时目录执行git init openspec init确认规格目录结构能自动创建。创建一个样例规格并打开检查模板完整性。五步全部通过才算真正装好了。只看到版本号就收工的同学后面很容易撞上第 4.4 节那两个初始化报错。为什么推荐把验证做成固定流程因为环境配置最怕的是当时能用过几天不知道动了一下什么又不能用了。有了这个最小闭环环境出问题时可以快速定位是 Node 版本变了还是 PATH 被别的软件改了还是 Git 没装好。每次都在同一套验证基准上排查问题范围会缩得很小。5.2 用版本锁定文件减少团队环境差异如果你打算在团队里推广 OpenSpec一定要让成员的 Node 版本和工具版本保持一致。做法不复杂在项目根目录放一个版本锁定文件或者在项目文档里明确写清楚本仓库要求 Node 版本、OpenSpec 版本分别是多少。这件事看起来很小但团队里最常见的在我机器上是好的问题十有八九是版本不一致造成的。规格文件本身是文本理论上有兼容性但它的读写依赖 CLI 行为不同版本之间可能有差异。统一版本能省掉大量无意义的沟通成本。5.3 我给新人的最小 SDD 启动流程最后分享一个我推荐给新人的启动方式适合刚接触 SDD 的团队选一个中等规模、需求变更频繁的项目当实验田别拿核心业务直接试水。只从一个功能规格开始不要一次性铺开全套流程。规格写完先拉人评审评审通过再开始编码。功能完成后回到规格文件逐条核对验收标准。一旦发现规格和实现有偏差先改规格再改代码把这件事变成习惯。这套流程跑两三个迭代之后你自然能体会 OpenSpec 的价值。环境配置只是第一道门槛真正的门槛是团队愿不愿意在动手前先把事情说清楚。我个人在实践里最大的感受是OpenSpec 这类工具装起来并不难难的是 Windows 上各种环境因素叠加在一起时你很容易把时间花在这个报错到底是谁造成的上面。如果你正被某个报错卡住我建议先别急着反复重装按第 4 节的顺序把 Node、权限、PATH、Git 这四个最基础的环节过一遍效率会高很多。另外一个小技巧每次改完环境变量或执行策略后都重开一个全新的终端窗口再验证很多看起来改了没用的问题其实只是忘了这一步。
