1. 为什么 Claude 写代码总在“返工”需求漂移的真实代价用 Claude 写代码最让人抓狂的不是它不会写而是它写得太“自由”。你明明说的是“给登录接口加个失败次数限制”它给你顺手重构了整个鉴权模块你说“把文章列表按时间倒序”它把分页逻辑也一起改了还引入了项目里根本没用的状态管理库。几轮对话下来代码越改越乱最后只能git checkout .从头再来。我试过在一个已经跑了两年的老项目里加一个“文章管理”功能当时只丢给 Claude 一句“做个后台写文章、前台展示的功能”。结果它直接生成了一套带评论、点赞、用户等级的完整博客系统数据库表结构和现有 ORM 完全对不上删掉重写花了整整一个下午。问题不在 Claude 的能力而在于需求没有变成可执行的规范——AI 只能靠猜猜错就是返工。这类问题的根源有三个。第一是需求模糊自然语言本身有歧义“优化一下”可以指性能、可读性、还是修 bugClaude 无法像人一样追问确认。第二是上下文丢失聊天记录驱动的开发几轮之后早期约定就被挤出上下文窗口Claude 开始“失忆”你又得重新解释一遍。第三是缺少可追溯的决策记录改了什么、为什么改、影响哪些文件全散落在对话里团队协作时根本对不上账。OpenSpec 要解决的就是这三件事。它是一套轻量级的规范驱动工作流核心思路是“先把要做什么写清楚再让 AI 动手”。它不替代 Claude Code而是给 Claude 一份结构化的项目上下文和变更提案让每次代码生成都有据可依。配合 Claude 使用时需求漂移会显著减少因为 Claude 在写第一行代码之前已经读过project.md里的技术栈约定和proposals里的变更范围。这一篇会从 OpenSpec 的初始化配置讲起给出 Claude 对接规范文件的完整参数再用一个文章管理功能的案例演示需求变更前后如何验证代码一致性。适合正在用 Claude Code、Cursor、Cline 等工具做开发但被反复返工困扰的团队和个人。下面先从环境准备和 TaoToken 接入讲起因为 Claude 的稳定调用是整条链路的前提。2. Claude 接入前置用 TaoToken 拿到稳定可用的 API 通道OpenSpec 本身不需要 API 密钥它只负责生成规范文档和提案。真正调用 Claude 生成代码的是 Claude Code 这类客户端所以你需要先给客户端配一个可用的模型通道。这里用 TaoToken 做接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式Claude Code、Cline、Codex 都能直接对接。先拿 Key。打开https://taotoken.net/api-keys带上下文的 deep link 是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后在控制台创建一个新的 API Key复制出来形如sk-xxxxxxxx。这个 Key 就是后面所有配置里的ANTHROPIC_AUTH_TOKEN或OPENAI_API_KEY取决于你用的客户端。拿到 Key 之后记下三个核心参数后面配置会反复用到参数值说明Base URLhttps://taotoken.net/api所有请求的根地址不要加尾斜杠API Keysk-xxxxxxxx在 api-keys 页面创建Model IDclaude-sonnet-4-5-20250929按控制台模型列表填写实际 ID如果你用的是 Claude Code它读取的是环境变量。在~/.claude/settings.json或项目级.claude/settings.json里写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-xxxxxxxx, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }如果你用的是 Cline 或 Roo Code 这类 VS Code 插件在设置面板里选 “Anthropic” 作为 ProviderBase URL 填https://taotoken.net/apiAPI Key 填刚才复制的值Model ID 填claude-sonnet-4-5-20250929。Codex 用户则编辑~/.codex/auth.json{ OPENAI_API_KEY: sk-xxxxxxxx, OPENAI_BASE_URL: https://taotoken.net/api }配置完成后先用一条最小请求验证通道是否通。在终端里执行curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-xxxxxxxx \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回的 JSON 里content字段包含OK说明 Key、Base URL、Model ID 三件套都对。如果返回 401检查 Key 是否复制完整、有没有多余空格如果返回local proxy failed或连接超时检查 Base URL 是否写成了https://taotoken.net/api/多了尾斜杠有时会 404以及本机网络是否能正常访问该域名。这一步通了再往下装 OpenSpec否则后面 Claude 调不通会误以为是 OpenSpec 的问题。3. OpenSpec 初始化与 Claude 对接规范文件的完整配置环境通了之后装 OpenSpec。前提是本机有 Node.js 18 以上版本执行node -v确认。然后全局安装npm install -g fission-ai/openspeclatest openspec -v能打印出版本号就说明装好了。接着进入你的项目根目录执行初始化cd /path/to/your-project openspec init初始化时会让你选择使用的 AI 工具选 Claude Code如果列表里没有就选 Other后续手动配。完成后项目根目录会多出一个openspec/文件夹结构如下openspec/ ├── project.md # 项目上下文技术栈、约定、目录规范 ├── AGENTS.md # AI 助手工作流说明 ├── proposals/ # 变更提案存放处 │ └── (每个变更一个子目录) └── archive/ # 归档的历史提案project.md是整个工作流的基石Claude 每次生成代码前都会读它。你需要把项目的真实情况填进去比如技术栈、包管理器、代码风格、禁止使用的库。一个填好的示例# Project Context ## Tech Stack - 后端Node.js 20 Express 4 Prisma ORM - 数据库PostgreSQL 15 - 前端原生 EJS 模板 少量 Alpine.js - 包管理pnpm禁止使用 npm install ## Conventions - 所有数据库操作必须通过 Prisma Client禁止裸 SQL - 路由文件放在 src/routes/控制器放在 src/controllers/ - 新增接口必须写 JSDoc 注释 - 禁止引入 React/Vue 等前端框架 ## Directory Rules - 文章相关代码放在 src/modules/article/ - 公共工具放在 src/utils/这份文件写清楚之后Claude 就不会再给你生成 React 组件或者裸 SQL 了。接下来配置 Claude Code 读取 OpenSpec 的规范。在项目根目录创建或编辑CLAUDE.md加入以下内容让 Claude 每次会话自动加载规范# Claude 工作约定 本项目使用 OpenSpec 规范驱动开发。每次开始任务前必须 1. 读取 openspec/project.md确认技术栈和约定 2. 读取 openspec/AGENTS.md了解工作流 3. 涉及变更时先读取 openspec/proposals/ 下对应的提案文档 4. 生成代码必须符合 project.md 中的 Conventions不得引入未声明的依赖 变更流程 - 新功能先创建 proposal再执行 - 修 bug在提案的 tasks.md 中记录再修改AGENTS.md是 OpenSpec 自动生成的里面定义了提案的生命周期proposal → review → apply → archive。你不需要改它但要让 Claude 读它。配置完成后在 Claude Code 里发一条验证指令请读取 openspec/project.md 和 openspec/AGENTS.md用三句话总结本项目的技术栈和变更流程。如果 Claude 能准确说出“Node.js Express Prisma”“先提案后执行”说明规范文件已经成功注入上下文。这一步是整个方案的关键很多人跳过它直接让 Claude 写代码结果又回到需求漂移的老路。配置对了后面每次生成都会自动带上项目约束。4. 实战验证用提案驱动 Claude 开发文章管理功能规范配好之后走一遍完整流程。假设要给现有网站加一个文章管理功能需求是“后台登录写作前台按分类展示”。不要直接让 Claude 写代码而是先创建提案。在 Claude Code 里输入我想添加文章管理功能后台登录后可写文章前台按分类展示。 请按照 OpenSpec 流程在 openspec/proposals/ 下创建变更提案。Claude 会读取project.md和AGENTS.md然后在openspec/proposals/下生成一个子目录比如add-article-management/里面包含三个文件openspec/proposals/add-article-management/ ├── proposal.md # 需求描述、影响范围、技术方案 ├── design.md # 数据模型、接口设计 └── tasks.md # 拆解后的开发任务清单proposal.md会写明这次变更涉及哪些现有文件、新增哪些文件、是否影响首页。design.md会给出 Prisma 的 Article 模型定义和路由设计。tasks.md把开发拆成可勾选的小项比如“创建 Article 模型”“实现后台登录中间件”“实现前台分类查询接口”。你先审查这三个文件确认无误后再让 Claude 执行提案已确认请按照 openspec/proposals/add-article-management/tasks.md 逐项实现每完成一项在 tasks.md 中标记。Claude 会按任务清单逐条生成代码并且因为project.md里写了“禁止裸 SQL”“路由放 src/routes/”它生成的代码会自然落在正确的位置。生成过程中你可以随时让它停下来解释某一步或者修改design.md后重新执行。这就是规范驱动的价值需求变更先改文档再改代码代码和文档始终一致。功能跑通后验证需求变更前后的一致性。假设后来要加一个“文章标签”功能不要直接让 Claude 改代码而是新建一个提案新增需求文章支持标签前台可按标签筛选。 请在 openspec/proposals/ 下创建新提案并说明对现有 Article 模型和前台路由的影响。Claude 会生成新提案并在proposal.md里列出需要修改的文件prisma/schema.prisma加 Tag 模型、src/modules/article/下的控制器加筛选逻辑、前台模板加标签入口。你审查后执行完成后用git diff对比会发现改动范围严格限定在提案声明的文件内没有误伤首页或其他模块。这就是“需求变更前后代码一致性验证”的落地方式提案是契约diff 是证据。最后归档提案请将 add-article-management 提案归档到 openspec/archive/。归档后openspec/archive/里保留了这次变更的完整决策记录以后接手的人翻 archive 就能知道当时为什么这么设计。整个流程走下来从提案到功能可用大约一小时其中大部分时间花在审查提案上而不是反复修改 AI 生成的乱代码。5. 常见报错排查401、local proxy failed、reading choices 怎么解接入和运行过程中最容易卡在几个固定报错上。下面按真实遇到的顺序列出来对照排查。401 Unauthorized / invalid api key。这是 Key 的问题。先确认sk-开头有没有复制完整前后有没有空格或换行。然后确认 Base URL 是https://taotoken.net/api不是https://taotoken.net/api/v1路径会重复。如果用 Claude Code检查settings.json里的ANTHROPIC_AUTH_TOKEN字段名有没有写错有些版本读的是ANTHROPIC_API_KEY两个都写上最稳。改完重启 Claude Code 再试。local proxy failed / ECONNREFUSED。这个报错通常出现在客户端配置了本地代理端口但代理没启动或者 Base URL 指向了localhost。检查你的客户端设置里有没有http.proxy之类的字段清空它。如果用的是 Cline在 VS Code 设置里搜 “proxy”把http.proxy和https.proxy都设为空。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api不是本地地址。reading choices of undefined。这个报错说明客户端按 OpenAI 格式解析响应但服务端返回的是 Anthropic 格式或者反过来。Claude Code 用 Anthropic 格式Cline 选 Anthropic Provider 时也用 Anthropic 格式。如果你在 Cline 里选了 “OpenAI Compatible” 却填了 Anthropic 的 Base URL就会报这个。解决办法是 Provider 选 AnthropicBase URL 填https://taotoken.net/apiModel ID 填claude-sonnet-4-5-20250929。三件套对齐就不会报。OAuth error / authentication failed。Claude Code 某些版本会尝试 OAuth 登录如果你已经用 API Key 配置了环境变量它会冲突。在settings.json里加上forceApiKey: true或者删除~/.claude/下的 OAuth 缓存文件重新登录。确认ANTHROPIC_AUTH_TOKEN存在且有效OAuth 流程就不会被触发。OpenSpec 命令找不到 / openspec: command not found。说明全局安装没成功或者 npm 的全局 bin 目录不在 PATH 里。先npm list -g fission-ai/openspec确认是否装上如果装上了还找不到执行npm config get prefix拿到全局路径把这个路径下的bin目录加到 PATH。Windows 用户用管理员权限重开终端再试。提案生成了但 Claude 不读。检查CLAUDE.md里有没有写“每次任务前读取 openspec/proposals/ 下对应提案”。如果没写Claude 不会主动读。另外确认提案目录名和你在指令里写的一致大小写敏感。可以在指令里直接给出绝对路径比如“读取 openspec/proposals/add-article-management/proposal.md”这样最稳。排障的核心思路是先确认三件套Base URL Key Model ID对齐再确认客户端 Provider 格式和服务端一致最后确认 OpenSpec 的规范文件真的被 Claude 读到了。这三层都通了基本不会再有玄学报错。6. 把规范变成习惯让 Claude 长期稳定干活的接入方式走到这里你已经有了完整的链路TaoToken 提供稳定的 Claude 调用通道OpenSpec 提供规范驱动的变更流程Claude Code 负责按规范生成代码。剩下的就是把它变成日常习惯。每次新需求先写提案再动手每次改 bug先在tasks.md里记一笔再改每次功能完成归档提案。坚持两三周你会发现返工次数明显下降因为 Claude 不再靠猜而是按你写好的规范执行。如果你还在选客户端Claude Code 适合终端党Cline 适合 VS Code 用户Codex 适合习惯 OpenAI 生态的人三者都能对接 TaoToken。想先试试模型对话效果可以打开https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite直接体验。需要长期跑编码任务或 Agent 的建议看 Coding Plan额度更划算地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各客户端的详细配置示例。控制台在https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteKey 管理和用量查询都在那里。最后给一个实用技巧把openspec/project.md当成项目的“宪法”每次 Claude 生成代码跑偏不要急着改代码先回头看project.md里有没有写清楚对应的约束。约束写清楚了Claude 自然就听话了。规范不是负担是让 AI 少犯错的最省力方式。