如何用 Superpowers 技能系统让 AI 编程更规范？OpenCode 实操指南

Superpowers是什么？

Superpowers 是一个为 AI 编程智能体设计的软件开发方法论框架。

它覆盖 Claude Code、Codex CLI、Codex App、Cursor、Gemini CLI、OpenCode、GitHub Copilot CLI等。它是一套”技能系统”（Skills System）——通过结构化的 Markdown 文档与各平台各自的 bootstrap 机制，把工作流约束注入到智能体上下文中，从而强制约束智能体的行为模式，使其遵循专业的软件工程实践。

智能体不需要”被建议”怎么做，而是需要”被强制”怎么做。Superpowers 通过 HARD-GATE、Iron Law、Red Flags 等机制，将最佳实践从”建议”升级为”铁律”。

一、OpenCode 配置文件

OpenCode全局配置文件在：

~/.config/opencode/opencode.jsonc

项目级配置则放在项目根目录的 opencode.json 或 opencode.jsonc（jsonc 是 JSON with Comments 的缩写）。两者都支持，项目级优先于全局。

可以查看当前OpenCode 全局配置文件：

cat ~/.config/opencode/opencode.jsonc
{
 "$schema": "https://opencode.ai/config.json",
 "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"],
 "permission": {
 "*": "allow"
 }
}

opencode.jsonc 配置说明

• $schema：指向 JSON Schema 定义，用于 IDE 自动补全和校验。也可从 opencode.ai/config.json 查看完整的 Schema 定义。

• plugin：插件列表，支持字符串或 [插件名, 选项对象] 格式。这里配置的是：”superpowers@git+https://github.com/obra/superpowers.git”，表示从 GitHub 仓库安装 Superpowers 插件。

• permission：权限控制，OpenCode 中最关键的配置项。上面配置 “*”: “allow” 表示全局所有工具都免确认直接执行。

所有 skills 无需手动调用，Agent 会在对应场景自动加载合适的 skill。这意味着你只需要像平常一样说话，Superpowers 会在后台引导 Agent 走规范流程。

二、Superpowers 技能在 OpenCode 中的触发机制

Superpowers 是通过 opencode 的 skill 系统集成进来的。在当前环境中，可以看到系统提示里已经注入了一个 列表，里面包含 brainstorming、systematic-debugging、test-driven-development、using-superpowers 等一组 Superpowers 技能（来自
~/.cache/opencode/packages/superpowers@…/skills/）。

OpenCode 提供了一个原生的 skill 工具（对应 Claude Code 里的 Skill 工具）。当模型决定使用某个技能时，它会调用：skill(name: “”)

三、Skill 触发方式

在 OpenCode 中，Superpowers 技能的触发可以归纳为 4 种方式：

1. 模型自主匹配触发（隐式触发，最常见）

会话启动时，opencode 把所有已安装技能的 name + description 注入到系统提示的 区块。

模型读到用户消息后，按 using-superpowers 的规则：”哪怕有 1% 的可能匹配，就必须调用 skill 工具加载”。

查看 using-superpowers/SKILL.md 文件，其中包含：

If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

例如：

• 用户说”帮我加个功能” → 自动触发 brainstorming

• 用户说”这个 bug 怎么修” → 自动触发 systematic-debugging

• 用户说”开始实现这个 feature” → 触发 test-driven-development

2. 用户显式指名触发

用户在自然语言里直接点名某个技能，例如：

• “用 brainstorming 技能帮我捋一下”

• “走 TDD 流程”

• “用 systematic-debugging 排查”

模型识别后调用 skill 工具加载。

3. 会话启动时强制触发 using-superpowers

这是一个”元技能”。在你当前的系统提示里能看到它的内容已经被预先内联注入（ 包裹的那一大段就是它），并明确说明：

"It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load 'using-superpowers' again."

也就是说，opencode 在每次新会话开始时，会通过 plugin/系统提示注入的方式强制激活 using-superpowers，作为后续所有技能调用的”调度规则”。

4. 技能内部链式触发（技能里调用其他技能）

某些技能（如 brainstorming、writing-plans）在其 SKILL.md 流程里会要求模型继续调用其他技能（如 writing-plans → executing-plans →
subagent-driven-development）。这种是技能驱动技能的级联触发。

在 opencode 中，skill 的入口是 skill 工具调用 + 系统提示里的 描述，没有自动生成 /brainstorming、/tdd 这种斜杠命令。

也就是说，你在 opencode 输入框里输入 /brainstorming 并不会有一个内置的 Superpowers 斜杠命令弹出来。

四、在现有TODOLIST项目中实践

Flux Todo — 一个纯前端（HTML + CSS + JS）的 Todo List 应用，无框架依赖。

技术栈：原生 HTML/CSS/JavaScript，使用 localStorage 持久化数据

功能：添加待办、标记完成/取消完成、删除任务、显示剩余未完成任务数

UI 风格：暖色调玻璃拟态设计（Space Grotesk + IBM Plex Mono 字体），带背景浮动光球动画，响应式布局适配移动端

项目结构：index.html + style.css + app.js，共约 440 行代码

其他：集成了 OpenSpec 工作流（.opencode/ 和 openspec/ 目录），用于结构化的变更管理

下面使用 Superpowers 技能来添加新的功能：

我想在现有功能中添加按照用户管理todolist

从图中可以看出，已经触发了 Brainstorming 技能。

Brainstorming 技能强制在写代码前完成”需求澄清 → 方案对比 → 设计确认”的闭环，避免了凭直觉直接动手导致的返工风险。

每一步都有用户确认，确保最终实现与预期一致。

关于用户切换方案，进行需求澄清，以及方案对比等。

设计确认后，进行代码组织的确认，并写入设计文档。

退出计划模式，写入设计文档，开始实施。

实施完成。变更摘要：

• index.html — 新增用户选择覆盖层、header 用户信息区域、用户列表项 template

• style.css — 新增覆盖层（毛玻璃卡片）、用户列表项、切换按钮、错误提示样式及移动端适配

• app.js — 新增用户管理模块（CRUD、选择/切换、旧数据迁移），todos 按用户 ID 隔离存储

• docs/superpowers/specs/2026-05-31-user-management-design.md — 设计文档

下图是选择用户的界面：

下图是新的Todo List 页面，可以进行用户切换。

五、Brainstorming 技能驱动的变更过程总结

1. 探索项目上下文

先读取了 index.html、app.js、style.css，了解到这是一个纯前端 localStorage 存储的 Todo 应用。

2. 逐个提问澄清需求（3 轮）

• 用户管理范围 → 本地用户切换（无后端）

• 交互方式 → 用户列表选择

• 默认状态 → 必须先选用户才能使用

3. 提出 3 种方案对比

• 方案 A：覆盖层（推荐）

• 方案 B：独立视图切换

• 方案 C：侧边栏

我们选择了方案 A。

4. 分段呈现设计（3 段，逐段确认）

• 数据模型与存储 → localStorage key 设计、数据迁移策略、用户管理规则

• UI 与交互 → 覆盖层结构、主界面变更、新增/删除用户流程

• 代码组织 → 文件变更范围、新增函数列表、不引入新依赖

5. 写入设计文档并自审

输出到 docs/superpowers/specs/2026-05-31-user-management-design.md，检查无占位符、无矛盾、范围聚焦。

6. 用户确认后实施

按设计文档依次修改了 index.html、style.css、app.js，完全遵循设计中的方案。