终端AI编程三件套：OpenCode集成OpenSpec与Superpowers

先说结论在终端里用AI写代码这件事大部分人只停留在“装个CLI、配个模型、开始聊天”的阶段真正让AI从“会聊天”变成“能干活”靠的是外围这一整套约定、技能和配置。OpenCode本身只是引擎引擎再猛没有规范、没有技能库、没有一套趁手的配置体系跑起来也是裸奔。这篇文章把OpenSpec、Superpowers、Oh-My-OpenCode这三样东西逐个拆开讲清楚再把它们组合进OpenCode的完整流程走一遍。适合已经装过OpenCode但觉得“效果就那样”的人也适合正准备从零搭一套终端AI开发环境的朋友。1. 先把这几个项目的关系理顺1.1 OpenCode是底座但它默认状态确实“太素了”OpenCode是一个用Go写的开源终端AI编程助手界面是TUI风格启动后在终端里直接开一个交互会话。它能读文件、改文件、跑命令、看Git状态也能通过opencode run 任务描述这种非交互方式一口气执行任务。跟Web端对话的最大区别在于模型拿到了真实的项目上下文而不是靠你把代码一段段粘进去。很多人的第一反应是“那它本身就够用了为什么还要装OpenSpec和Superpowers”答案很简单OpenCode默认只给了你一个空的会话框架模型虽然有上百K甚至上M的上下文窗口但它不知道你的项目规范是什么、不知道你们团队的开发流程是什么、也不知道“改完代码要跑哪些验证”才算完成。你就等于雇了一个能力很强但完全没培训过的新人所有工作习惯都要现场教。这就是为什么要做二次配置。OpenCode提供了几个扩展点项目级AGENTS.md、全局配置文件~/.config/opencode/opencode.json、以及后来引入的skills技能机制。OpenSpec解决“按什么标准干活”的问题Superpowers解决“有哪些成熟工作方法可以直接调用”的问题Oh-My-OpenCode解决“这一大堆配置怎么管理、怎么一键复用”的问题。1.2 OpenSpec把“需求”变成“规格”让AI不再瞎猜OpenSpec是一套“规范驱动开发”的工具和约定。它的核心想法非常朴素大多数AI编码翻车不是模型能力不行而是需求描述太模糊。模型不是不想做对是根本不知道“对”的定义是什么。OpenSpec的做法是在项目里维护一个openspec/目录用结构化Markdown文件把需求、方案、变更内容、验收条件全部沉淀下来。AI在动手之前先读规范写完代码之后按规范的验收点逐项核验而不是凭聊天记录里的几句话自由发挥。这个思路最打动我的地方在于它把“需求分析”这个本该由人完成的环节重新拉回了开发流程。以前用AI写代码经常是我说一句“帮我加个导出功能”模型就直接开干干出来的东西跟我要的差很远。而OpenSpec强制我先写一份“变更提案”把现状、目标、涉及模块、风险点、验收标准写清楚然后模型才动手。听起来多了一步实际上省了后面好几轮返工。1.3 Superpowers把AI从“通用助手”变成“专业选手”Superpowers最初是给Claude Code设计的一套技能集作者是Jesse VincentGitHub上的obra。它针对编码场景把大量方法论固化成了技能文件每个技能就像一份“岗位培训手册”告诉AI遇到什么场景该用什么流程。例如“brainstorming”技能要求AI先展开多轮发散讨论而不是直接给方案“spec-driven-development”技能强制先写规格再写代码“test-driven-development”技能则要求先写失败测试再实现。OpenCode从v2开始支持原生Skills机制.claude/skills里的技能文件经过少量适配就能被OpenCode读取。这意味着Superpowers里的那几十个成熟技能可以直接搬进OpenCode用。换句话说Superpowers补的是OpenCode的“方法论短板”让模型不止是知道怎么调用工具还知道什么时候该用哪种工作方式。1.4 Oh-My-OpenCode配置界的“收纳师”Oh-My-OpenCode是一个面向OpenCode的配置集项目命名致敬了Oh-My-Zsh。它把社区沉淀下来的主题、快捷键、模型参数、AGENTS.md规则、常用提示词片段打包成一套可切换的“配置档”。以前你要手动往配置文件里塞一堆JSON现在直接引入Oh-My-OpenCode再挑需要的模块启用就行。它解决的是“配置本身变得复杂之后怎么维护”的问题属于配置之上的配置框架。1.5 组合之后开发范式变成了什么样把这套组合装齐以后一次完整的任务通常会走这样的路径我先写一份OpenSpec变更提案明确需求和验收标准然后让OpenCode读取提案按Superpowers里的技能库选择适合的工作方法比如先做技术方案、再逐文件实现、再跑测试验证。整个过程里模型的行为是有章法的输出是可预期的配置是统一管理的。下面从安装开始一步步来。2. 环境准备装好OpenCode并完成初始配置2.1 安装方式与版本选择OpenCode官方推荐一行命令安装macOS和Linux都可以用curl -fsSL https://opencode.ai/install | bash如果你用的是Homebrew也可以走tap方式brew install sst/tap/opencodenpm同样有对应的包早期包名是opencode-ai装完以后终端命令为opencodenpm install -g opencode-ai我的建议是优先用官方脚本或Homebrew。npm方式虽然也能用但OpenCode更新节奏非常快npm包的发布偶尔会比官网渠道慢半拍。安装完成后先确认版本OpenCode v2之后功能变化很大如果你的版本太老后面讲到的skills配置可能对不上opencode --version2.2 配置文件目录先弄清楚每一层放什么OpenCode的配置目录默认在~/.config/opencode/项目级配置则在当前项目的opencode.json。全局配置存放跟个人偏好相关的内容比如默认模型、主题、全局指令项目级配置存放跟仓库绑定的约定比如启用哪些技能、项目的验收流程、禁止修改哪些文件。还有一个容易被忽略但极其重要的文件AGENTS.md。这个文件会被OpenCode自动注入到每次会话的上下文里作用相当于“给AI立规矩”。全局的AGENTS.md放在~/.config/opencode/AGENTS.md项目级的放在仓库根目录。实际项目中我在项目级AGENTS.md里写的是项目技术栈和目录结构说明代码风格约定缩进、命名、测试方式“禁止直接修改哪些文件”等硬性规则完成一项任务前必须执行的验证命令这样每次会话开始AI不需要我重新解释项目背景读一遍AGENTS.md就掌握了基本盘。2.3 接入模型ProviderOpenCode支持多种模型来源。最省事的方式是用官方Console通过opencode auth login登录后可以直接使用内置额度也可以配置自己的API Key用环境变量或配置文件指定。以Anthropic模型为例设置环境变量export ANTHROPIC_API_KEYsk-ant-xxxx再通过配置文件指定默认模型{ $schema: https://opencode.ai/config.json, provider: { anthropic: { models: { claude-sonnet-4-5: { name: claude-sonnet-4-5 } } } }, model: claude-sonnet-4-5 }如果你主要使用本地模型比如通过Ollama跑Qwen、Llama也可以配置本地Provider。对于日常编码我实测下来长上下文模型优势明显因为OpenCode会持续往上下文里堆项目信息上下文窗口不够的话会话后半段模型基本就“失忆”了。2.4 验证基本链路通不通配置完成后先在项目目录里跑一个最简单的任务测试链路opencode run 读取当前目录结构用三句话总结这个项目是做什么的如果模型能正常回答说明OpenCode、Provider、目录读取都正常。这时候先别急着继续装别的把这个最基本的环境稳定下来。我见过不少朋友一口气装了一堆东西最后出问题都不知道是模型没配对还是技能路径配错排查起来特别痛苦。3. 接入OpenSpec把规范驱动开发落到项目里3.1 初始化OpenSpec目录结构OpenSpec通过一套约定来组织规范文件官方文档在openspec.dev。安装CLI后可以全局安装也可以项目内安装首先在项目根目录执行初始化openspec init这个命令会在项目里生成openspec/目录典型结构大致如下openspec/ ├── specs/ │ ├── capabilities.md │ └── ... ├── projects/ │ └── ... └── changes/ └── ...specs/保存领域能力和现有行为的规格说明changes/保存待实施的变更提案也就是每次具体需求的“施工图”projects/则把多个变更聚合成一个项目级的交付计划。上手阶段重点用changes/就够了。3.2 创建第一份变更提案OpenSpec提供了CLI命令来创建变更模板比如openspec new change add-user-export生成的文件里会包含几个固定章节现状Current State、目标Desired State、实现方案Implementation Plan、受影响模块Impacted Areas、验收标准Acceptance Criteria。这些章节不是装饰它们是后续让AI按规范执行的关键。很多人第一次写变更提案时容易犯一个错误把实现方案写得特别细细到“第几行代码改成什么”。这完全走偏了。变更提案的重点是描述“要什么结果”和“怎么验证结果”而不是替AI决定每一行代码怎么写。实现细节应该允许模型在框架内自己发挥验收标准才是必须钉死的。我一般是这么写的现状当前用户列表只能查看无导出功能目标支持按当前筛选条件导出CSV文件文件包含用户ID、姓名、邮箱、注册时间实现方案在用户列表页增加“导出”按钮前端调用后端新增的/api/users/export接口后端从数据库读取数据并生成CSV流式返回验收标准筛选条件为“近30天注册”时导出文件只包含近30天的用户数据导出文件前两行为表头和分隔线字段与需求完全一致导出过程中界面不阻塞这份提案写完后直接丢给OpenCode再补充一句“按照这份变更提案实施”。模型会读取规范内容按照方案和验收标准来干活而不是凭感觉写个导出功能完事。3.3 在OpenCode中执行规范工作流OpenSpec官方还提供了一个配套技能包用来让AI代理直接操作规范文件。原理不难理解通过技能文件告诉模型“你的项目里有一套规格文件动手前先读一下openspec/目录变更前先确认有没有对应的变更提案没有就先写提案写完提案再开始写代码”。实际操作时我在OpenCode里通常这样调用opencode run 先读取 openspec/changes/add-user-export.md然后按提案完成实现最后逐条核对验收标准并在回复中给出核对结果对比一下没有OpenSpec时同样的任务我会写一大段提示词描述需求然后模型自由发挥有了OpenSpec之后我需要写的提示词大幅缩短因为需求的权威描述已经沉淀在规范文件里了。而且验收标准是结构化的模型在执行结束后可以自己去检查比如运行测试、检查导出文件的列头形成闭环。3.4 什么时候需要更新specs当一次变更已经完成并合入主干应该把对应的变更提案状态更新掉并把新的能力同步到specs/里。这一步骤常常被人忽略导致规范文件很快就过期最后没人再信任它。我的习惯是每个功能合入前先确保OpenSpec文档和代码一起提交。代码改了而规范没更新这个PR不应该被合入。很多团队把这个写进AGENTS.md里让模型在收尾阶段自动检查。实测下来这个习惯养成了AI写代码的“稳定性”会有质的提升。4. 引入Superpowers让AI拥有可复用的专业技能4.1 先理解Superpowers的技能机制Superpowers的核心单元是“技能”skill。一个技能本质上是一个包含SKILL.md文件的目录里面用Markdown写清楚这个技能解决什么问题、前置条件是什么、执行流程分几步、每一步要产出什么结果。当OpenCode加载了这个技能目录后模型在应对匹配场景时会自动把对应的流程当作行动指南。例如brainstorming技能会强制模型先收集背景信息、再提出多个备选方案、逐个评估优缺点、最后才确定方案。默认情况下模型总是倾向于直接给出一个“看起来合理”的答案但这个技能会逼它慢下来。对于复杂功能设计慢反而是快。4.2 获取Superpowers技能库并接入OpenCodeSuperpowers项目托管在GitHub上作者是obra。把它克隆到本地git clone https://github.com/obra/superpowers.git ~/.superpowers克隆完成后核心内容在skills/目录下里面是按技能名组织的子目录。接下来把它接入OpenCode。OpenCode的skills目录可以是全局的也可以是项目级的。我推荐放全局这样所有项目都能共享mkdir -p ~/.config/opencode/skills cp -r ~/.superpowers/skills/* ~/.config/opencode/skills/如果你的OpenCode版本比较新直接在配置文件的skills相关字段里指一下路径或者在AGENTS.md里声明技能目录位置即可。不同版本的配置键名略有差异但核心机制是通用的把技能目录放进OpenCode的加载范围让模型在会话中能读到这些SKILL.md文件。Superpowers里有一批技能是直接从Claude Code生态平移过来的OpenCode读取时基本不区分来源只要你确保目录结构里有SKILL.md就行。4.3 常用技能逐个体检挑几个我日常用得最多的技能说一说brainstorming设计新功能时启用别名类似“先发散再收敛”。它适合需求还不明确、需要探索方案的场景。writing-plans把任务拆解成有序步骤并在动手前写出完整计划。适合改动范围较大的任务。executing-plans配合上面的计划使用按计划逐步执行而不是跳着乱改。spec-driven-development和OpenSpec配合的专用技能要求先读规格文档、再写测试、再实现。test-driven-development强制先写失败测试再实现代码对要求高测试覆盖率的项目很实用。request-review代码写完后让AI以审查者身份重新审视改动寻找边界问题和遗漏。这些技能不是每个项目都要全量启用。比如我维护一个内部工具项目没有严格要求覆盖率那test-driven-development就关掉否则每次改动都会额外生成一大轮测试文件反而增加负担。技能是工具不是教条按需启用才合理。4.4 通过Slash命令直接触发技能OpenCode支持在交互会话里用斜杠命令唤起特定技能。例如输入/superpowers:brainstorming或者直接写“使用brainstorming技能讨论一下这个需求”。在非交互模式下则通过自然语言在任务描述里显式点名技能opencode run 使用brainstorming技能围绕登录模块改造产出一份3个方案的技术对比核心技巧是不要指望模型主动想起来该用哪个技能。虽然技能描述会进入上下文但模型在长任务中很容易忽略尤其是在上下文压缩后。显式指定技能是保证行为可控的最有效手段。4.5 按团队情况微调技能内容Superpowers的技能文件默认是为通用场景设计的直接搬进团队项目时我建议按项目特点做微调。比如writing-plans技能默认的输出粒度是“一个步骤一个代码块”但我们团队习惯的是“一个步骤对应一个commit”于是我直接在SKILL.md里加了一条每个步骤结束后都必须运行测试并提交一次commit。这种微调不需要改代码只需编辑Markdown里的描述。有一点要提醒技能文件本身也是会被模型读取的“提示词”修改时注意保持结构清晰不要堆砌无意义的口水话。模型对结构化的流程描述响应最好对抒情式文字基本免疫。5. 用Oh-My-OpenCode统一配置与主题5.1 Oh-My-OpenCode提供的核心内容Oh-My-OpenCode是一个把OpenCode配置变成“模块化”的项目。打开它的仓库会发现它把很多零散的配置项做成了可开关的“模块”多套主题包括Light、Dark、Dracula、Monokai等模型供应商的预设配置一组开箱即用的AGENTS.md规则例如“不要修改锁定文件”“提交信息使用英文”等常用slash命令的预制片段编码风格偏好模板它的价值不在于配置内容多神奇而在于“整理好了”。我见过很多人的OpenCode配置文件越加越乱最后自己都忘了哪些配置是干什么的。Oh-My-OpenCode强制你用模块化结构来组织配置后续加新功能时只在对应的模块目录里加文件不影响主配置文件。5.2 安装与启用安装方式很直接克隆仓库后把配置目录软链接到OpenCode的全局配置目录git clone https://github.com/xxx/oh-my-opencode.git ~/.oh-my-opencode ln -s ~/.oh-my-opencode/opencode.json ~/.config/opencode/opencode.json ln -s ~/.oh-my-opencode/AGENTS.md ~/.config/opencode/AGENTS.md具体路径以项目文档为准不同版本略有差异。启用后重启opencode就能看到新主题和新增的全局规则。5.3 主题切换与模块管理Oh-My-OpenCode通常会在配置文件里支持通过一个字段切换主题比如{ theme: dracula }模块的启用方式一般是增删目录或修改配置文件里的开关项。我的习惯是把项目无关的个性化配置全交给Oh-My-OpenCode管理把项目相关的规则放在项目级AGENTS.md里。前者负责“我个人的偏好”后者负责“这个项目的硬性约束”两者不交叉。5.4 自己的配置如何覆盖默认值OpenCode的配置加载是有优先级的理解这个才能避免“改了没生效”。我的经验里大致优先级从高到低是配置层级说明项目级opencode.json当前仓库生效覆盖全局设置项目级AGENTS.md当前仓库的AI行为约束全局AGENTS.md所有项目的底线规则全局opencode.json含Oh-My-OpenCode作为默认值兜底也就说说如果某个行为在两个层级里冲突了项目级的会赢。比如全局AGENTS.md里写着“所有提交信息用英文”项目里写“项目内提交用中文”模型会优先遵守项目级的规则。这个优先级模型想清楚后配置冲突的问题一下就明朗了。6. 三件套联动从需求到提交的完整实战流程6.1 一次完整任务的分步记录假设我要给项目加一个“从后台导出操作日志”的功能。在没搭这套体系时流程通常是打开opencode说一句“帮我加导出功能”然后焦虑地看它自由发挥。搭了OpenSpecSuperpowers之后流程变成了第一步在OpenCode会话里让模型先把需求变成OpenSpec变更提案opencode run 使用spec-driven-development技能为导出操作日志功能创建一份变更提案写到openspec/changes/add-log-export.md需要包含现状、目标、影响范围、验收标准第二步人工审一遍提案确认验收标准符合预期。这一遍非常关键因为后续AI的全部行为都会围绕这份提案展开提案逻辑有漏洞代码一定跑偏。第三步让模型实施opencode run 读取openspec/changes/add-log-export.md按提案实施。每个文件改完后运行相关测试最后逐条核对验收标准第四步模型汇报核对结果我抽查关键改动确认无误后提交代码。整个过程AI的行为一直有据可依而我不需要在一轮轮的对话里反复纠正。6.2 与Git工作流结合的几个操作习惯OpenCode本身支持读写Git状态配合OpenSpec后我有了几个固定习惯变更提案先提交一次作为任务的分界点实现完成后用opencode run 查看git diff检查是否偏离了变更提案做一次自检让模型生成提交信息时强制它引用变更提案的ID这些习惯最终都是为了让“从需求到代码”的链路可追溯。OpenSpec的规范文件就是这条链路上的锚点代码改动和需求一一对应团队review的时候也不用再猜“这个人为什么写这段代码”。6.3 哪些环节仍然必须人来把关把话说回来三件套再好有几个环节我绝不会完全交给AI变更提案里“目标”的定义必须人工确认AI容易把目标扩大或缩小实现层面的“取舍判断”比如“这个方案性能差但代码简单当前阶段能不能接受”这类权衡必须人来定涉及敏感操作、数据迁移、权限修改的任务AI只能出草案不能自动执行AI是执行者不是决策者。这套配置的本质是把执行环节的质量往上抬而不是把决策环节外包出去。想清楚这一点工具才不会反过来制造麻烦。7. 避坑手册与常见问题7.1 装完Superpowers后技能不生效最常见的原因有三个技能目录放错了位置、SKILL.md格式不对、配置里没有声明技能目录。排查顺序如下确认技能目录在OpenCode的加载范围内全局技能放~/.config/opencode/skills项目技能放项目根目录的.opencode/skills确认每个技能目录下都有SKILL.md文件且文件名大小写正确在交互会话里用“查看你加载了哪些技能”的方式让模型自述能列出说明加载成功列不出就是路径或配置问题还有一个容易被忽略的坑技能数量过多时OpenCode不会把全部技能的详细内容塞进上下文只会按描述做一次粗筛选。所以技能里的描述字段一定要写清楚适用场景描述模糊的技能等于不存在。7.2 OpenSpec提案写得过细或过粗写提案时我见过两种极端。一种是把实现细节写到函数级别模型没有发挥空间遇到意外情况不会灵活处理另一种是验收标准写得太虚比如“功能正常”这种标准等于没写。我的参考标准是验收标准必须能被一个工程师通过跑命令或检查文件来客观验证。比如“点击导出按钮后浏览器下载一个名为log_20250101.csv的文件”就是合格标准“用户体验要好”就是不合格标准。7.3 配置优先级不清导致“改了没用”如果你改了配置文件但行为没变先确认是哪一个层级的配置在生效。特别是Oh-My-OpenCode接管了全局配置之后你可能会在项目里新写一个opencode.json但发现某些全局规则还是被带进来了。这恰恰是优先级设计的一部分项目配置覆盖全局配置但覆盖是字段级的不是文件级的。意思是项目配置里没写到的字段仍然会从全局配置继承。理解了这一点就不会误以为“我写了项目配置全局配置就全部失效了”。7.4 上下文爆炸与费用控制同时开启OpenSpec和Superpowers后上下文占用会比裸OpenCode明显增加因为规范文件和技能文件都会占用token。我的做法是技能只启用团队真正在用的五到六个不搞全家桶大任务拆成多个阶段每个阶段单独启动会话避免上下文越积越长费用敏感时使用更便宜的模型跑“读规范写测试”这类辅助环节但“最终实现”仍然用强模型还有一点不要把整个openspec/目录所有文件都丢给模型读它只需要读当前变更提案和相关的规格文件。在AGENTS.md里写明“只读取openspec/changes目录下最新的变更文件”能省下大量token。7.5 升级OpenCode v2之后的兼容性问题OpenCode v2是最近一次大版本升级配置格式和skills机制都有调整。如果你是从更早版本升上来的升级后要做三件事确认配置文件格式是否符合新schema、重新声明skills目录、检查Provider配置。最稳妥的做法是升级后先跑一遍opencode --version确认版本再新建一个临时目录测一次基础对话和技能加载没问题再切回正式项目。我在升级时踩过一次坑全局配置里用的旧字段被新版本忽略了但OpenCode没有报错只是静默用默认值跑导致我一度以为模型变笨了。后续排查才发现是配置没迁移。自那以后每次大版本升级我都要把配置目录备份一次然后逐个验证核心功能。7.6 常见问题速查表现象可能原因排查/解决技能列表为空skills目录路径不对检查全局和项目级skills目录是否存在模型无视变更提案提案文件内容模糊检查验收标准是否客观可验证配置改了没生效配置优先级覆盖确认项目级配置是否挡住了全局配置上下文过长规范文件或技能读太多在AGENTS.md中限定读取范围升级后行为异常配置文件用了旧字段对比新版本schema并迁移配置模型输出不稳定没有显式指定技能在任务描述里点名技能名称这篇文章写到这里核心配置链路已经全部走完了。最后再分享一个实际体会OpenCode、OpenSpec、Superpowers、Oh-My-OpenCode这四样东西单拎出来每一个都不复杂难的是把它们组合起来并坚持“规范先行、技能驱动、配置收敛”这三个原则。我在团队里推行这套体系时最大的阻力不是技术问题而是人习惯性地想让AI赶紧出代码。但坚持了两周后大家普遍反馈返工次数明显下降代码review也轻松了很多。如果你正准备搭建自己的终端AI开发环境我建议从OpenCode加OpenSpec这一步开始跑顺一个需求闭环之后再加入Superpowers的技能库最后用Oh-My-OpenCode把配置整理好。一步步来比一次性配齐更容易沉淀出真正适合自己的工作流。