1. 为什么 AI 编码助手总在“自由发挥”用 Claude Code 写业务代码的 Node.js 开发者大概率遇到过这种场面你只说“加个登录接口”它顺手把注册、找回密码、邮箱验证、限流中间件全给你铺了一遍最后你花在删代码上的时间比写代码还多。问题不在模型能力而在于你给它的输入是“聊天式的一句话”它只能靠猜。OpenSpec 就是来解决这个猜的问题的——它是一个轻量级规范驱动开发框架核心思路是“在写任何代码之前先就要构建什么达成一致”。它把需求沉淀成openspec/specs/里的权威规范把待做的功能放进openspec/changes/作为变更提案AI 助手按提案和任务清单干活而不是按聊天历史自由发挥。这套框架适合谁适合已经在用 Claude Code、Cursor、Cline 这类工具但被“AI 过度实现”“需求漂移”“重构破坏旧逻辑”折磨过的 Node.js 团队。它只依赖 Node.js不需要额外服务本地就能跑。而要让 Claude Code 稳定连上模型、把 OpenSpec 的斜杠命令跑通你需要一条统一的 API 通道。这篇就按“先配通道、再装框架、最后跑通验证”的顺序把可复制的配置和排障一次讲清。2. TaoToken 前置给 Claude Code 一条统一 Key 通道OpenSpec 本身不需要 API Key它是纯本地 CLI。但它的价值要通过 AI 编码助手释放而 Claude Code 默认走的是 Anthropic 官方通道国内 Node.js 开发者直接配会遇到网络和账号两道坎。TaoToken 在这里的角色是提供一个统一的 Key 和 API 通道让你用同一个 Key 驱动 Claude Code、Cursor 等工具配置一次到处能用。你需要先拿到 Key。打开 https://taotoken.net/api-keys 登录后在控制台创建 API Key复制那串sk-开头的字符串。注意两点一是 Key 只在创建时完整显示一次先存到密码管理器二是不同工具用不同 Key 便于排查别所有工具共用一个。拿到 Key 后Claude Code 的接入方式有两种环境变量和配置文件。环境变量适合临时验证配置文件适合长期使用。下面两节分别给出可复制的骨架。如果你还想先确认模型通道是否正常可以打开 https://taotoken.net/models 用模型对话页发一条测试消息确认 Key 有效再往下配。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 读取配置的优先级是项目级.claude/settings.json 用户级~/.claude/settings.json 环境变量。推荐用用户级配置一次配好所有项目通用。先看用户级~/.claude/settings.json的骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key粘贴在这里, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-4-20250514 }, permissions: { allow: [ Bash(openspec:*), Bash(npm:*), Bash(node:*) ] } }这里几个字段要解释清楚。ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址注意不要带任何查询参数ANTHROPIC_AUTH_TOKEN填你刚创建的 KeyANTHROPIC_MODEL是主模型负责写代码和推理ANTHROPIC_SMALL_FAST_MODEL是轻量模型负责补全和简单判断分开配能省成本。permissions.allow里放行openspec命令避免 Claude Code 每次执行斜杠命令都弹确认。如果你用的是 Cline 或某些支持 TOML 的工具等价配置写成config.toml[api] provider anthropic base_url https://taotoken.net/api api_key sk-你的Key粘贴在这里 [model] name claude-sonnet-4-20250514 fast_model claude-haiku-4-20250514 max_tokens 8192 [behavior] auto_approve_commands [openspec, npm, node]配完保存重启 Claude Code 让配置生效。验证配置是否被读取可以在 Claude Code 里问一句“你现在用的 base url 是什么”它会从环境里读出来告诉你。这一步过了通道就算通了。4. 安装 OpenSpec 并初始化项目通道通了接下来装 OpenSpec。前置要求是 Node.js 20.19.0先确认版本node --version # 期望输出 v20.19.0 或更高 npm --version版本不够就升级 Node.js别硬装OpenSpec 的 CLI 依赖较新的运行时特性。确认后全局安装npm install -g fission-ai/openspeclatest openspec --version # 输出类似 fission-ai/openspec/0.x.x进入你的项目根目录初始化cd your-project openspec init初始化向导会问你用哪些 AI 工具用空格键勾选 Claude Code回车确认。它会自动在项目里生成openspec/目录并给 Claude Code 配置三个斜杠命令/openspec:proposal创建变更提案、/openspec:apply实施任务、/openspec:archive归档变更。初始化后目录结构长这样your-project/ └── openspec/ ├── AGENTS.md # AI 助手工作流指令CLI 自动管理 ├── project.md # 项目上下文需要你手动填 ├── specs/ # 已实现功能的规范初始为空 └── changes/ # 待实施的变更提案 └── archive/ # 已完成变更的归档两个文件要特别关注。AGENTS.md是给 AI 看的工作流说明书里面用!-- OPENSPEC:START --和!-- OPENSPEC:END --标记托管区域别手动改要更新跑openspec update。project.md是给 AI 看的项目上下文初始化后立刻编辑它把技术栈、代码规范、架构模式写进去——这个文件的质量直接决定 AI 生成代码的准确度。比如一个 Express TypeScript 项目可以这样写# 项目上下文 ## 技术栈 - 运行时Node.js 20 TypeScript 5 - 框架Express 4 - 数据库PostgreSQL Prisma - 测试Vitest ## 代码规范 - 使用 2 空格缩进单引号 - 所有导出函数必须有 JSDoc - 错误统一用 AppError 类抛出 ## 架构模式 - 路由层只做参数校验业务逻辑放 service 层 - 数据库访问统一走 repository 层填完跑一下openspec list输出No active changes found.就说明初始化正常。5. 验证请求跑通第一个变更提案配置和初始化都完成后用一次完整的四步工作流验证整条链路。四步是起草提案、审核对齐、实施任务、归档更新。第一步在 Claude Code 里用自然语言描述需求触发提案创建/openspec:proposal 给用户模块添加登录接口。 需求POST /api/login接收 email 和 password校验通过返回 JWT。 约束复用现有 AppError 类密码用 bcrypt 比对不新增注册和找回密码功能。Claude Code 会读取AGENTS.md的指令自动在openspec/changes/下创建变更目录生成proposal.md、tasks.md和specs/下的规范增量。生成后你审查三份文件proposal.md的 Why 是否说清背景、tasks.md的任务顺序是否合理数据库→后端→前端→测试、规范增量里的场景是否覆盖正常和异常。第二步手动跑严格验证确认格式没问题openspec validate add-user-login --strict # 成功输出Change add-user-login is valid第三步实施任务/openspec:apply add-user-loginClaude Code 会按tasks.md逐项写代码每完成一项就在清单里标[x]。这一步生成的代码必须人工审核重点看功能是否符合 spec 里定义的场景、是否遵循project.md里的规范。第四步功能验证通过后归档openspec archive add-user-login --yes归档会把规范增量合并进specs/并把变更目录移到changes/archive/2025-xx-xx-add-user-login/。归档不会自动提交 Git记得手动 commit。整条链路跑通后你可以用openspec view打开交互式仪表板看到当前所有规范和变更的状态。如果 Claude Code 在实施阶段报连接错误回到第 2 节检查 Key 和 base url如果openspec validate报格式错误看下一节的排查清单。6. 本篇常见错排查报错一Error: Requirement xxx must have at least one scenario这是规范增量里某个### Requirement:下面没有#### Scenario:。OpenSpec 要求每个需求至少有一个场景否则无法验证。打开报错指向的spec.md在需求下补一个场景块#### Scenario: 登录成功 - **WHEN** 用户提交正确的 email 和 password - **THEN** 返回 200 和 JWT token报错二Warning: Scenario header format incorrect场景标题必须用四个井号#### Scenario: name写成三个井号或没有Scenario:前缀都会报这个。检查所有场景标题的井号数量。报错三Error: Change must have at least one delta变更目录下的specs/是空的没有规范增量。确认openspec/changes/change-name/specs/capability/spec.md存在且里面有## ADDED Requirements或## MODIFIED Requirements段落。报错四Claude Code 执行/openspec:proposal没反应先确认openspec init时勾选了 Claude Code斜杠命令才会被写入配置。如果勾了还是没反应跑openspec update刷新指令文件然后重启 Claude Code。再不行就检查~/.claude/settings.json里的permissions.allow是否放行了openspec命令。报错五API 请求 401 或连接超时401 通常是 Key 填错或过期去 https://taotoken.net/api-keys 重新生成一个。超时先确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api没有多余斜杠或参数。如果多个工具共用一个 Key 出现限流给 Claude Code 单独分配一个 Key。报错六openspec archive后 specs 没更新检查归档命令有没有加--skip-specs这个参数会跳过规范合并。另外归档只改本地文件不会自动 commit需要你手动git add openspec/ git commit。排障时如果拿不准是通道问题还是框架问题先用模型对话页发一条消息确认通道正常再回来查 OpenSpec 的格式问题能省不少时间。7. 把规范驱动接进日常编码跑通第一个变更后日常使用有几个习惯值得养成。大型需求拆成多个提案单个提案太大审核和实施都累拆成“加数据模型”“加接口”“加前端”三个提案每个都能独立验证和归档。规范增量一旦进入实施阶段就保持不可变发现需求变了就新建一个变更提案而不是回头改原提案这样归档历史才有审计价值。project.md要定期更新技术栈或架构变了就同步它是 AI 理解你项目的入口。长期用 Claude Code 跑 OpenSpec 工作流的话可以考虑 Coding Plan 这类按周期计费的方案比按量付费更适合高频编码场景具体在 https://taotoken.net/coding-plan 看。接入文档和更多配置示例在 https://taotoken.net/doc 遇到通道层面的问题先翻文档再排查。核心原则就一句在写任何代码之前先就要构建什么达成一致。把这句话落到openspec/的目录结构里AI 编码助手才会从“自由发挥的实习生”变成“按图施工的工程师”。