第十章：常见问题解答

常规问题

Superpowers 支持哪些平台？

Superpowers 设计为可与多个 AI 编程平台配合使用：

平台	状态	备注
Claude Code	完全支持	主要平台；所有功能可用
Cursor	完全支持	官方支持在 v4.3.1 中添加（2026 年 2 月）
Gemini CLI	完全支持	扩展支持在 v5.0.1 中添加（2026 年 3 月）
Codex	实验性	自 v3.3.0 起可用（2025 年 10 月）
OpenCode	支持	在 v3.5.0 中添加

每个平台使用相同的 skill 文件和 CLAUDE.md 配置。特定平台的差异（如有）记录在引入该支持的版本的发布说明中。

Superpowers 与使用普通 AI 编程 agent 有什么不同？

不使用 Superpowers 的 AI 编程 agent，就像使用强大工具却没有安全手册一样。Agent 有能力，但没有关于质量的强制纪律、没有系统化的调试规范，也没有针对最常见失败模式的保障措施。

使用 Superpowers：

每个功能都从失败测试开始。 没有"实现并寄希望于结果"。
每个完成声明都需要证据。 没有"应该能用"。
每个 bug 都需要根本原因调查。 没有猜测。
Skills 执行领域特定的最佳实践。 Agent 自动对每种任务类型遵循正确的方法。
代码前先写计划。 架构决策在纸上做，而不是在生产环境中。

结果不是一个更慢的 agent——而是一个你可以信任其工作成果的 agent。在调试、回滚和整理混乱代码库上节省的时间，远远超过了前期严谨性所花费的时间。

我可以在团队中使用 Superpowers 吗？

可以。Superpowers 特别适合团队环境，因为它在所有使用 AI agent 的团队成员之间强制执行一致的实践。

推荐的团队设置：

将 CLAUDE.md 提交到仓库。 所有团队成员使用相同的配置。在项目上工作的 AI agent 遵循相同的规则。
提交 .claude/skills/ 目录。 Skills 是共享的。为项目创建的自定义 skills 对所有人都可用。
执行 worktree 隔离策略。 每个开发者和每个 AI agent 都在隔离的 worktree 中工作。Main 分支保护规则防止直接 commit。
使用基于 PR 的代码审查。 代码审查规范（第七章）直接与 GitHub/GitLab 工作流集成。

通过这种设置，为一个团队成员工作的 AI agent 遵循与为另一个人工作的 AI agent 相同的标准——或者遵循团队编码标准的人类开发者。

TDD 与质量

TDD 是强制的吗？有例外吗？

是的。TDD 是强制的。没有例外。

这是铁律一："没有先有失败测试，就不得编写任何生产代码。"

常见的例外论点及其被拒绝的原因：

"这只是小变更。" 小变更也会引入 bug。为小变更编写测试的时间成本以分钟计。调试未经测试的小变更造成的回归的时间成本以小时计。

"我们在快速推进，以后再加测试。" 实现后添加的测试是围绕实现而非需求塑造的。它们测试代码做了什么，而不是它应该做什么。它们提供虚假的信心。"以后"很少真的到来。

"代码是 UI，很难测试。" UI 行为是可以测试的。组件测试、快照测试、交互测试和端到端测试都存在。难度不是豁免的理由。

"我知道这段代码是正确的。" 这是最危险的论点。你未来的自己，或一位同事，不会分享你当前的确定性。测试记录了这种确定性并将其保存下来。

每种任务类型推荐使用什么模型？

模型选择取决于任务需求：

任务类型	推荐模型	原因
架构规划、复杂推理	Claude Sonnet 4.5+（思考模式）	扩展推理产生更好的计划
功能实现、TDD	Claude Sonnet 4.5	速度与质量的平衡
代码审查、调试	Claude Sonnet 4.5	强大的分析能力
简单重构、格式化	Claude Haiku 3.5	机械性任务快速且经济高效
多 agent 并行任务	Claude Haiku 3.5（subagents）	大规模成本效益高

对于 Gemini CLI 用户：Gemini 2.0 Flash 推荐用于实现任务；Gemini 2.5 Pro 用于架构和规划。

对于 Cursor 用户：在 Cursor 的 composer 中使用 Claude Sonnet 模型进行功能工作。Cursor 内置聊天可以使用较小的模型来回答快速问题。

安装与更新

如何更新到 Superpowers 的新版本？

Superpowers 作为仓库中的一组文件分发（CLAUDE.md、skills 目录和相关配置）。更新通过从 Superpowers 仓库拉取最新版本来应用。

标准更新流程：

# 1. 创建更新 worktree（遵循第八章规范）
git worktree add ../myapp--superpowers-update -b chore/update-superpowers

# 2. 在更新 worktree 中，下载最新的 Superpowers 文件
# （遵循你的具体设置的安装说明）

# 3. 运行完整的测试套件以验证没有破坏任何东西
npm test

# 4. 查阅 changelog（第十一章）了解破坏性变更

# 5. 遵循正常的代码审查规范通过 PR 合并

更新前：

阅读你要更新的版本的 changelog
注意任何需要配置更新的破坏性变更
在开始更新之前确保所有当前测试通过

如何添加新 skill？

Skills 是 .claude/skills/ 目录（对于 Claude Code）或你平台的等效目录中的文件。

添加新 skill 的流程：

确定领域。 这个 skill 涵盖开发的哪个具体领域？要精确——"React 性能优化"的 skill 比"React"的 skill 更好。
先写失败测试（铁律四）。在编写 skill 之前，定义 skill 应该产生什么行为。
编写 skill 文件。 Skills 是具有特定结构的 markdown 文件：触发条件、上下文、规则和示例。
测试 skill。 在真实会话中调用它。验证它在正确的输入上触发并产生正确的指导。
提交到仓库。 提交到仓库的 skills 对所有团队成员和 agents 都可用。

有关详细的 skill 创建指导，请使用 superpowers:writing-skills skill。

兼容性

Superpowers 可以在 Windows 上使用吗？

可以。Superpowers 可以在 Windows、macOS 和 Linux 上使用。

Windows 用户应注意一些特定平台的注意事项：

路径分隔符： Skills 和配置文件使用正斜杠。Windows 在大多数情况下能正确处理这些，但某些 shell 脚本可能需要调整。
行尾符： 配置 git 以一致地处理行尾符：git config core.autocrlf input。
示例中的 shell 命令： 某些示例使用 bash 语法。Windows 用户应使用 WSL2（Windows Subsystem for Linux）或 Git Bash 以获得最佳体验。
Worktree 路径： 使用不含空格的路径。C:\projects\myapp--feature 可以使用；C:\My Projects\myapp feature 可能会导致问题。

适用时，平台中会包含专用的 Windows 修复，并在 changelog 中注明。

我可以不使用 Claude Code 而使用 Superpowers 吗？

可以。虽然 Superpowers 最初是为 Claude Code 设计的，但核心原则——TDD、系统化调试、完成前验证、代码前先写计划——是平台无关的。

Skill 系统在每个平台上的实现方式不同：

Claude Code： .claude/skills/ 目录，包含 markdown skill 文件
Cursor： 带有适配 skill 内容的 Cursor rules 文件
Gemini CLI： 扩展配置

本指南中描述的铁律和规范，无论你使用哪个平台都适用。具体的调用机制不同，但它们强制执行的行为是相同的。

故障排除

Skill 没有正确触发。该怎么办？

检查 skill 文件是否存在于你平台的正确位置。
验证 skill 文件中的触发描述。 触发条件必须与你用来调用它的语言匹配。
明确指定。 不要期待 agent 推断正确的 skill，而是直接命名它："对此使用 superpowers:systematic-debugging skill。"
检查冲突。 如果两个 skills 具有重叠的触发条件，agent 可能会选择错误的一个。检查你的 skill 配置。
重新阅读 skill 文件。 当代码库更改时，skills 可能会过时。Skill 可能触发正确，但产生的建议不再适用。

测试本地通过但在 CI 中失败。该怎么办？

这是一个根本原因调查问题。遵循调试规范的第一阶段（第六章）：

仔细阅读 CI 错误输出——不要总结
找出本地与 CI 的不同之处（环境变量、Node 版本、操作系统、文件权限、网络访问）
如果可能，在本地重现 CI 环境（Docker、匹配的 Node 版本）
检查依赖全局状态、文件系统状态或时序的测试

最常见的原因：CI 中未设置环境变量、测试对本地文件路径有隐式依赖，以及在 CI 负载下失败的含时序假设的测试。