现在很多团队用 Claude Code 写业务代码最头疼的不是模型能力不够而是两件事一是 AI 上来就写设计不讨论、测试不写、写完就说搞定了二是换个会话它就把上次的决策忘干净两周后想查某个功能为什么这么设计聊天记录翻到底也找不到。Superpowers 和 OpenSpec 就是冲着这两个痛点来的一个用技能框架强制 AI 走「先设计、再计划、后编码、必验证」的流程一个用 specs/ 和 changes/ 双目录把变更决策沉淀成 Git 里的 Markdown。这篇不聊概念直接以 TaoToken 统一 Key 和 API 通道为接入背景把两者装进同一个项目里跑一遍交付可复制的配置片段和逐步验证动作最后给出这套组合到底值不值得落地的判断依据。1. 原问题与场景AI 编码为什么需要「纪律 记录」双保险先说清楚这两个框架各自解决什么不然后面配置会装得莫名其妙。Superpowers 是给 AI 编码代理用的结构化工作流框架作者 Jesse Vincent核心思路是「不让 AI 直接写代码」。它把开发拆成头脑风暴、写计划、git worktree 隔离、子代理执行、强制 TDD、验证后才算完这几个阶段每个阶段由独立的 Skill 驱动AI 不能跳步。最关键的机制是子代理派发主代理把任务派给实现者写代码再派给另一个完全独立的审查者审代码两边互不知道对方干了什么审查结果相对客观。它擅长的是代码质量弱项是知识持久化——设计文档写完丢在docs/superpowers/specs/下没有系统维护机制换会话就断片。OpenSpec 是规范驱动开发框架作者 Tabish Bidiwale背后公司进了 Y Combinator。它的核心是双文件夹模型openspec/specs/记录系统当前真实状态按「能力」组织openspec/changes/放活跃变更提案每个变更一个文件夹里面有 proposal.md为什么改、design.md技术方案、tasks.md实现清单和增量 specs。变更完成后归档增量合并回主规格。它擅长跨会话的知识持久化和变更审计弱项是代码质量——不强制 TDD、不做独立审查、不自动开隔离分支。所以问题就很清楚了Superpowers 管「代码写得对不对」OpenSpec 管「为什么做这个变更」。一个在执行层一个在知识和决策层。真正要验证的是把它们串在同一个项目里流程会不会打架、Token 成本能不能接受、产出物能不能对得上。我试过的场景是一个中等规模的 Node.js 服务已有代码库需要加 OAuth 登录。这个场景同时具备「要改现有系统」和「要保证新代码质量」两个特征正好能压测两者的配合。接入层统一走 TaoToken 的 API 通道这样模型调用只有一个 Base URL 和一个 Key排障时不用在多个供应商之间来回切。需要提前说明的是平台限制Superpowers 最核心的子代理派发能力目前主要在 Claude Code 和 Cursor 上效果最好不是所有工具都支持。OpenSpec 支持 25 工具Claude Code、Cursor、GitHub Copilot、Codex、Windsurf、Gemini CLI 基本都覆盖。所以这套组合的推荐运行环境是 Claude Code下面所有配置都以它为准。2. TaoToken 前置统一 Key 与 API 通道的准备工作在装两个框架之前先把模型调用通道理顺。这一步很多人会跳过结果后面报 401 或者 local proxy failed 的时候分不清是框架配置问题还是 Key 问题。TaoToken 在这里的角色很单纯提供一个统一的 API 入口让你在 Claude Code 里配置一次 Base URL 和 Key后续所有模型请求都走这个通道。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串抄进去。第一步拿 Key。打开 https://taotoken.net/api-keys 创建一个 API Key复制出来存好。这个 Key 只显示一次丢了只能重建。建议按项目建不同的 Key方便后面看用量。第二步确认你要用的模型 ID。这一步很关键因为 Superpowers 的子代理派发会并发发起多个请求如果模型 ID 写错报错信息往往藏在子代理的日志里主会话只显示一个笼统的失败。在 https://taotoken.net/models 或者模型对话页面 https://taotoken.net/chat 里确认可用的模型标识记下来。第三步配置 Claude Code 的环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥改完执行source ~/.zshrc生效。这里有个坑如果你之前配过别的 Base URL一定要确认新变量覆盖了旧值可以用echo $ANTHROPIC_BASE_URL检查。第四步验证通道本身是通的。先别急着装框架用一条最简单的请求确认 Key 和端点没问题curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: 你的模型ID, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }返回体里能看到content数组且有文本内容说明通道正常。如果返回 401先查 Key 是否复制完整、有没有多余空格如果返回 404检查 Base URL 是不是多写了/v1或者少了/api。第五步长期编码场景可以考虑 Coding Plan。如果你打算把 Superpowers 的多代理流程跑在真实项目上Token 消耗会比单代理高不少按量计费容易失控。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 配置细节以文档为准。这一步做完你应该有一个能跑通的 API 通道、一个确认可用的模型 ID、以及 Claude Code 里生效的环境变量。后面两个框架的所有请求都会复用这套配置不需要各自再配一遍。3. 可复制配置Superpowers 与 OpenSpec 的安装与 settings 片段这一节是全文的操作核心所有片段都可以直接复制。顺序上建议先装 OpenSpec 再装 Superpowers因为 OpenSpec 的初始化会生成 AGENTS.mdSuperpowers 的会话加载会读这个文件顺序反了可能要手动补。3.1 安装 OpenSpec 并初始化目录OpenSpec 需要 Node.js 20.19.0先确认版本node -v低于要求就先升级。然后全局安装npm install -g fission-ai/openspeclatest在项目根目录执行初始化cd /path/to/your-project openspec init初始化完成后项目根目录会多出一个openspec/文件夹里面有AGENTS.mdAI 代理行为指引、project.md项目信息和config.yaml配置文件。同时会生成specs/和changes/两个子目录。目录结构大致是这样openspec/ ├── AGENTS.md ├── project.md ├── config.yaml ├── specs/ │ └── auth/ │ └── spec.md └── changes/ └── add-oauth/ ├── proposal.md ├── design.md ├── tasks.md └── specs/config.yaml里可以指定默认工具和模型相关参数。一个最小可用的配置片段如下注意路径和字段名以你本地生成的文件为准不要整段覆盖只改需要改的项# openspec/config.yaml version: 1 tools: - claude-code defaults: change_dir: changes spec_dir: specsproject.md里写清楚项目背景这段内容会被 AI 在生成提案时读取写得越具体proposal 的质量越高。比如# 项目信息 - 技术栈Node.js 20 Express PostgreSQL - 认证现状仅支持邮箱密码登录session 存 Redis - 本次目标新增 OAuth 登录保留原有登录方式 - 约束不引入新的认证中间件复用现有 session 机制3.2 安装 Superpowers 插件Claude Code 里直接输入插件安装命令/plugin install superpowersclaude-plugins-official装完之后每次新开会话会自动加载不需要手动启动。它支持 Cursor、Codex、Gemini CLI 等但子代理派发能力在 Claude Code 和 Cursor 上最完整。3.3 Claude Code settings 片段Claude Code 的项目级配置在.claude/settings.json这个文件可以跟 Git 走团队共享。一个包含 TaoToken 通道和两个框架协作的配置片段如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, permissions: { allow: [ Bash(git worktree:*), Bash(npm test:*), Bash(openspec:*) ] }, includeCoAuthoredBy: false }这里三个点要注意。第一env里的 Key 不要提交到公开仓库团队协作时用环境变量注入或者本地覆盖文件。第二permissions.allow里放行git worktree是因为 Superpowers 会自动创建隔离工作树不放行会卡在权限确认上。第三放行openspec命令是为了让/opsx:*系列命令能顺利执行。如果你用 Cline 或者带 MCP 的客户端配置思路一样Base URL 填https://taotoken.net/apiKey 填同一个Model ID 填你在模型列表里确认的那个。三件套缺一不可Base URL、Key、Model ID少一个都会在请求阶段报错。3.4 两个框架的协作约定装完之后要在项目里明确分工否则两个框架都会抢「需求探索」和「设计」阶段。建议在AGENTS.md里加一段约定## 工作流约定 - 需求探索与变更提案使用 OpenSpec 的 /opsx:explore 和 /opsx:propose - 代码实现与质量保障使用 Superpowers 的 brainstorming 和子代理执行 - 变更收尾使用 OpenSpec 的 /opsx:verify 和 /opsx:archive - 禁止在 OpenSpec 提案未确认前直接进入编码阶段这段约定是给 AI 看的也是给团队看的。没有它AI 很可能在 OpenSpec 还没生成 proposal 的时候就被 Superpowers 拉去写代码两边产出物对不上。4. 验证请求与成功结果跑一遍 OAuth 变更的完整流程配置装好只是开始真正要验证的是流程能不能跑通、产出物对不对得上。这一节按三段式走一遍OpenSpec 想清楚要做什么Superpowers 保证做得对OpenSpec 收尾归档。4.1 第一段用 OpenSpec 生成变更提案在 Claude Code 会话里输入/opsx:explore 我想给现有服务加 OAuth 登录先看看当前认证相关的代码结构这一步 AI 会去读openspec/specs/auth/spec.md和相关源码输出一份现状梳理不会直接改代码。确认现状描述准确后进入提案/opsx:propose add-oauth然后快进生成所有规划文档/opsx:ff执行完检查openspec/changes/add-oauth/目录应该有四个文件。proposal.md里能看到「为什么改、改什么」的说明design.md里有技术方案tasks.md里是实现清单specs/下是增量规格标注了 ADDED / MODIFIED / REMOVED。成功的结果是tasks.md 里的任务粒度足够细每条能对应到具体文件和函数而不是「实现登录功能」这种笼统描述。这一步的验证动作很简单打开tasks.md数一下任务条数。如果只有三五条说明拆得不够细回到/opsx:propose补充约束条件重新生成如果有二三十条且每条都能落地说明提案质量合格。4.2 第二段切到 Superpowers 执行拿到 proposal 和 design 之后进入 Superpowers 的流程参考 openspec/changes/add-oauth/design.md 和 tasks.md进入 brainstorming 阶段AI 会先问一堆问题OAuth 提供商选哪个、已有用户怎么迁移、session 怎么兼容、安全要求是什么。回答完之后它会给出 2-3 种方案让你选。这里有个门禁设计没通过一行代码都不许写。方案确认后让它拆计划把选定的方案拆成 2-5 分钟粒度的执行步骤每步写清楚改哪个文件的哪段代码然后进入子代理执行阶段。Superpowers 会自动创建 git worktree 隔离分支主代理把任务派给实现者写代码写完派给审查者审。审查分两轮先看代码符不符合 design.md 的规格再看代码质量。不通过就打回重做。这一步的成功结果有几个可观察的信号。第一git worktree list能看到一个新的隔离工作树分支名类似superpowers/add-oauth。第二测试文件先于实现文件出现因为强制 TDD没有失败测试就不能写生产代码。第三审查阶段会有独立的审查输出指出具体哪一行不符合规格而不是笼统说「有问题」。4.3 第三段回到 OpenSpec 收尾代码写完、测试通过之后回到 OpenSpec 验证一致性/opsx:verify这一步检查代码实现是否和design.md、增量 specs 对得上。如果实现过程中偏离了设计比如临时换了一个库verify 会指出来你要么改代码要么回头改 design.md 并说明原因。确认一致后归档/opsx:archive add-oauth归档会把changes/add-oauth/specs/下的增量合并回specs/auth/spec.md变更文件夹移到归档区。成功的结果是specs/auth/spec.md里能看到 OAuth 相关的条目changes/下不再有活跃的 add-oauth 文件夹。4.4 验证结果对照表阶段命令成功信号失败信号通道验证curl 请求返回 content 文本401 / 404提案生成/opsx:fftasks.md 任务粒度细任务笼统、文件缺失隔离执行子代理派发worktree 出现、测试先行直接改主分支、无测试一致性检查/opsx:verify实现与 design 对齐报偏离项归档/opsx:archive增量合并进 specs文件夹残留整条链路跑通之后你手上会有三样东西一份可追溯的变更记录proposal → design → specs → tasks、一个隔离分支上的高质量代码TDD 独立审查、以及合并回主规格的系统状态更新。这三样正好对应开头说的两个痛点。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth 报错这一节按真实报错来每个都给出定位路径和修复动作。排障时记住一个原则先确认是通道问题还是框架问题再往下查。5.1 401 Unauthorized最常见的报错出现在 curl 验证或者 Claude Code 首次请求时。原因通常是三类Key 复制不完整、Key 前后有空格、环境变量没生效。定位动作先echo $ANTHROPIC_AUTH_TOKEN看值对不对注意有没有换行符混进去。然后用 curl 单独测一次排除框架干扰。如果 curl 通但 Claude Code 报 401检查.claude/settings.json里的env是否覆盖了 shell 里的变量两者冲突时以配置文件为准。修复重新在 https://taotoken.net/api-keys 复制 Key粘贴时确认没有多余字符改完重启 Claude Code 会话。5.2 local proxy failed这个报错通常出现在请求发不出去的时候本质是网络层或端点配置问题。先检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/带尾斜杠某些客户端对尾斜杠敏感。再确认没有把 UTM 查询串抄进 Base URLAPI 地址就是干净的https://taotoken.net/api。如果端点没问题检查本地是否有其他工具占用了同名环境变量。用env | grep ANTHROPIC看一遍有重复的清理掉。修复后重开会话再试。5.3 reading choices 相关报错这类报错一般出现在响应解析阶段提示读取 choices 字段失败。原因多半是模型 ID 写错返回体结构和你预期的不一致。回到模型列表确认准确的 Model ID注意大小写和版本后缀。在.claude/settings.json或者请求参数里统一改成确认过的 ID。还有一种情况是请求参数里max_tokens设得过大超出模型限制返回体里没有正常内容。把max_tokens降到合理范围比如 4096再试。5.4 OAuth 流程中的授权报错这个不是通道问题是业务代码问题但在验证阶段容易和框架问题混淆。典型表现是/opsx:verify报实现与规格不一致追下去发现是 OAuth 回调地址配错或者 state 参数没校验。定位动作先看design.md里写的回调地址和实际代码里的是否一致再看tasks.md里有没有「校验 state 参数」这一条被跳过。Superpowers 的审查阶段通常会抓这类问题但如果审查被跳过比如手动改了代码没走流程就会漏到 verify 阶段。修复按 design.md 补齐实现或者如果设计本身有问题回头改 design.md 并在 proposal 里补充说明然后重新走 verify。5.5 子代理派发失败Superpowers 的子代理执行阶段如果卡住或者报错先确认平台支持。Claude Code 和 Cursor 支持子代理派发其他工具可能不支持会退化成单代理模式或者直接失败。检查.claude/settings.json的permissions.allow里有没有放行git worktree没放行会卡在创建隔离分支这一步。还有一个隐蔽的坑Token 预算不足时子代理请求会被限流表现为部分任务完成、部分任务超时。这时候去 Coding Plan 页面确认额度或者临时降低并发任务数。5.6 规格漂移不是报错但比报错更麻烦你在工作流之外直接改了代码specs/和实际代码对不上。表现是下次/opsx:verify报一堆不一致或者 AI 基于过时的 spec 生成错误的提案。修复习惯比修复动作重要任何代码改动都走/opsx:propose起头哪怕是小改动。如果已经漂移了先跑/opsx:verify拿到差异清单逐条决定是改代码还是改 spec然后/opsx:archive重新对齐。6. 语义一致 CTA这套组合到底值不值得落地跑完一遍之后判断标准其实很具体不用纠结概念。如果你是全新项目、用 Claude Code、Token 预算宽裕Superpowers 单独上就够从第一天起代码质量有保障TDD 和独立审查是实打实的。如果你是在已有代码库上持续迭代、团队人多、有合规审计需求OpenSpec 单独上更实用变更记录和知识库在大型项目里的价值会随时间放大。两个一起用的前提是你能接受更高的 Token 消耗——OpenSpec 本身很省但叠加 Superpowers 的多代理架构后整体消耗大概是单独用 OpenSpec 的 4-6 倍这个成本要提前算进去。还有一个提醒别过度使用。修个小 bug、改个配置、做个快速原型不需要上这套工作流。杀鸡用牛刀只会拖慢节奏。这两个框架解决的是「AI 编码缺乏系统性」的问题不是所有场景都需要系统化。如果你决定落地接入层建议统一走 TaoToken一个 Key 一个 Base URL 管住所有模型请求排障时不用在多个供应商之间切换。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建接入细节看 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 长期高频编码场景走 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。配置过程中想快速验证模型是否可用直接用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息比在项目里反复试错快得多。最后说一个实操细节两个框架的产出物都在 Git 里建议在 CI 里加一条检查确认openspec/changes/下没有长期未归档的活跃变更以及specs/和代码的 diff 不超过阈值。这条检查能防止规格漂移悄悄积累等发现的时候已经对不上了。