第十章：团队实战落地、排障与最佳实践

10.1 从个人试用到团队规范

superpowers-zh 的落地可以分三阶段：

个人试用。 在个人项目中安装，验证 AI 是否会先澄清、先测试、先验证。
项目级固化。 把 Skills 和自定义指令放入仓库，让同一项目中的 AI 工具共享规则。
团队制度化。 把关键规则写入 PR 模板、CI、代码审查规范和提交规范。

不要一开始就要求所有人遵守全部 20 个 Skills。更稳妥的方式是先落地最关键的 4 个：

brainstorming
test-driven-development
systematic-debugging
verification-before-completion

等团队适应后，再加入中文文档、中文提交、代码审查和 Git 工作流。

10.2 推荐的项目级配置

在仓库中保留以下内容：

.<tool>/skills/                  # 对应工具的 Skills 目录
CLAUDE.md / GEMINI.md / rules    # 工具自定义指令
.github/copilot-instructions.md  # VS Code Copilot 指令
.github/PULL_REQUEST_TEMPLATE.md # PR 模板

自定义指令中应写清：

本项目使用 superpowers-zh：

- 任何新需求先使用 brainstorming。
- 编码和 Bug 修复遵循 test-driven-development。
- 测试失败和异常行为先使用 systematic-debugging。
- 声称完成前必须使用 verification-before-completion。
- 中文文档遵循 chinese-documentation。
- Commit Message 遵循 chinese-commit-conventions。

如果不同工具读取的规则文件不同，应保证它们内容一致，避免 Claude、Cursor、Copilot 在同一仓库中行为不同。

10.3 PR 模板中的检查项

可以加入：

## Superpowers 检查

- [ ] 新需求已完成需求澄清或引用设计说明
- [ ] 行为变更有测试覆盖
- [ ] Bug 修复有可复现用例或回归测试
- [ ] 已运行相关测试/构建/文档生成命令
- [ ] 已处理代码审查中的 [必须修复] 问题
- [ ] 中文文档符合中英混排规范

这些检查项能把 AI 工作流转化为人类 Review 可见的证据。

10.4 CI/CD 配合

superpowers-zh 不能替代 CI。AI 的本地验证和 CI 应互补：

本地执行快速测试，避免明显失败进入 PR。
CI 执行完整测试矩阵、构建、安全扫描和部署预检查。
PR 描述中记录本地验证命令和结果。
如果 CI 失败，使用 systematic-debugging 调查日志，而不是猜测。

国内平台可以根据 chinese-git-workflow 配置 Gitee Go、Coding CI、极狐 GitLab CI 或 CNB。无论平台如何，核心原则都是：验证自动化、失败可追踪、部署前有门禁。

10.5 常见安装问题

问题一：`npx superpowers-zh` 无法运行

排查：

检查 Node.js 版本是否 >=20。
检查 npm registry 是否可访问。
清理 npm 缓存后重试。
尝试全局安装后运行。
在企业内网中确认代理和证书配置。

问题二：安装成功但 AI 不使用 Skill

原因可能是：

工具不支持自动 Skill 发现。
自定义指令没有引用 Skills。
工具没有重启或重新加载工作区。
用户提示没有要求先检查 Skill。

处理：

检查目标目录是否有 SKILL.md。
在工具规则中显式写入 Skill 路由。
重启工具。
用一个小任务测试行为。

问题三：只复制了 Skills，没有 bootstrap 文件

某些手动安装方式只复制 skills/。这时应补充工具对应指令文件，例如 CLAUDE.md、GEMINI.md、.github/copilot-instructions.md 或 Cursor/Trae 规则文件。

10.6 常见使用问题

AI 说使用了 TDD，但没先跑失败测试

这不是 TDD。要求它回到 test-driven-development，删除先写的实现，从失败测试开始。

AI 修 Bug 时直接改代码

要求它使用 systematic-debugging：先复现、读错误、查近期变更、提出假设，再修复。

AI 说完成但没跑构建

要求它使用 verification-before-completion，运行能证明结论的命令。若命令不可用，应说明原因。

AI 对审查意见盲目附和

要求它使用 receiving-code-review，先验证反馈是否适用于当前代码库。

中文文档读起来像机翻

使用 chinese-documentation 检查：短句、结构化、中英空格、术语保留、避免被动和欧化长句。

10.7 最小可行落地方案

如果团队时间有限，可以先做一个最小方案：

在仓库安装 superpowers-zh。
在项目指令中只启用 4 条硬规则：设计先于编码、测试先于实现、调试先找根因、完成先验证。
PR 模板增加验证命令填写项。
每周 Review 1-2 个 AI 生成 PR，总结规则是否生效。
一个月后再增加中文文档和提交规范。

这种渐进方式比一次性导入全部流程更容易成功。

10.8 衡量效果的指标

可以用以下指标判断 superpowers-zh 是否有效：

AI 直接编码的次数是否减少。
需求澄清问题是否更集中。
Bug 修复是否有回归测试。
PR 中「忘记跑测试」的情况是否减少。
代码审查中低级问题是否减少。
中文文档格式问题是否减少。
团队成员是否能复用 AI 产出的设计和计划。

不要只看生成速度。真正的收益是返工减少、审查成本下降和交付可信度提高。

10.9 与现有团队规范的关系

superpowers-zh 应服从项目已有规范。如果团队已有：

分支命名规则。
Commit Message 规范。
PR 模板。
测试命令。
发布流程。
文档风格指南。

应把这些写入 AI 自定义指令，让 Skills 与团队规范叠加，而不是替代。若发生冲突，以用户和项目明确规则为准。

10.10 安全与合规注意事项

使用 AI 编程工具时要注意：

不把密钥、Token、客户数据写入提示词或仓库。
MCP Server 不返回敏感数据明文。
日志脱敏。
危险操作需要确认。
代码审查关注注入、越权、路径遍历、命令执行等风险。
完成前运行安全相关测试或扫描（如果项目已有）。

superpowers-zh 的流程能提醒 AI 做安全检查，但不能替代团队的安全制度。

10.11 学习复盘模板

每次用 AI 完成较大任务后，可以复盘：

## 任务

本次完成了什么？

## 使用的 Skills

- brainstorming：是否充分澄清？
- writing-plans：计划是否可执行？
- TDD：是否看到红灯？
- systematic-debugging：是否找到根因？
- verification-before-completion：验证证据是什么？

## 有效做法

哪些步骤减少了返工？

## 问题

AI 绕过了哪些规则？提示词如何改进？

## 下次改进

更新项目指令、PR 模板或团队规范。

复盘能把个人经验沉淀为团队规范。

10.12 最佳实践清单

10.13 本章小结

superpowers-zh 的价值不在于一次安装，而在于持续把工程纪律注入 AI 工作方式。个人使用能减少草率实现，团队落地能统一文档、提交、审查和验证流程。只要坚持「设计、测试、调试、验证」四个基本门禁，就能显著提升 AI 编程的可靠性和可维护性。