更新Codex Superpowers使用技巧以减少确认摩擦

背景

在 AI 辅助编程领域，Codex 与 Superpowers 的结合曾被视为提升开发效率的强力组合。然而，随着 Superpowers 项目在近两个月内的快速迭代（特别是 v5.1.0 版本的更新），原有的使用技巧逐渐失效，甚至可能误导用户。

此前，社区中流传着一种通过“斜杠命令”显式跳过确认流程的技巧，旨在减少 Superpowers 在 Codex 环境下的交互摩擦。但由于原项目架构变化，这种依赖特定命令的方法已不再适用。为了消除信息滞后带来的困扰，作者借助 Grok-Search 工具，基于相同的核心思路对 Superpowers 在 Codex 中的最佳实践进行了全面梳理和更新。

本文档旨在提供一份截至 2026 年 5 月 16 日的最新使用指南，通过覆写 AGENTS.md 或相关配置文件，帮助用户更顺畅地驾驭 Superpowers，避免常见的陷阱和冗余确认。

核心内容

本次更新的核心在于从“命令驱动”转向“自然语言意图驱动”，并针对 Superpowers v5.1.0 及后续版本的具体行为进行了精细化调整。主要差异体现在以下几个方面：

1. 交互范式的转变：放弃斜杠命令

旧版技巧中依赖的“斜杠命令显式跳过”机制已失效。新版模板完全摒弃了对特定命令的依赖，转而通过自然语言明确表达用户的意图。例如，不再使用特定的快捷指令，而是直接告知 AI 任务的性质和期望的执行路径。

2. 任务分级与执行链路

为了平衡效率与质量，新的配置建议将任务分为三个层级，并对应不同的执行策略：

• 轻量任务：
  • 定义：单文件修改、小范围 Bug 修复、配置调整、文案修改或小型测试补充。
  • 策略：默认直接定位代码并实现。仅在关键不确定点提问，且首次提问最多限制为 1 个问题，以最大化减少确认摩擦。
• 中型任务：
  • 策略：保留简短的头脑风暴（brainstorming）和短计划。在当前分支执行，仅进行一次代码审查（review）。
• 大型任务：
  • 策略：完整走通标准链路，包括头脑风暴 → 编写计划（writing-plans）→ 子代理驱动开发（subagent-driven-development）或执行计划（executing-plans）→ 审查。

3. 触发与绕过机制（v5.1.0 适配）

由于 v5.1.0 已移除斜杠命令，用户需通过自然语言指令来绕过冗长的流程：

• 跳过完整链路：明确指示“这是轻量改动”，要求 AI 不进入完整的 brainstorming / writing-plans / using-git-worktrees / subagent-driven-development 链路。
• 避免重复提问：指示 AI “已知上下文充分”，不要重复询问 AGENTS.md 或项目说明中已包含的问题。
• 审查方式调整：若需审查，要求改用“内联自我审查”（inline self-review），而非派遣评审子代理（dispatch review subagent），以减少等待时间和资源消耗。

4. 工作区与 Git 操作优化

针对工作区（Worktree）和 Git 操作，提出了具体的规避策略：

• Worktree 管理：
  • 除非用户明确要求，否则 AI 不应默认创建 worktree。
  • 若已在 harness 原生隔离工作区（如 EnterWorktree 或 Codex worktree handoff）内，禁止再次叠加 git worktree add 操作。
  • Windows 特定警告：在 Claude Code + Windows 环境下，首次 worktree 操作若出现任何异常，必须立即停止并报告，严禁自动重试，以规避已知 Issue #1546。
• Spec/Plan 文档提交：
  • 除非用户明确要求，否则不要默认将 spec 或 plan 文档提交到 git。允许落盘保存，但提交操作需征得用户同意。
• 子代理 Git 操作规范：
  • 子代理使用 git 切换到具体 commit 时，必须使用 git switch -c <branch> <sha> 或显式 checkout 到分支。
  • 严禁使用裸 git checkout <sha>，以规避 Detached HEAD 状态带来的潜在问题（规避 Issue #1518 相关风险，原文提及 Issue #1543）。
  • 停滞检测：若长时间未收到子代理回报，AI 应主动打断，避免无限期等待（规避 Issue #1545）。
  • 平台兼容性：在 Codex、OpenCode 或 Copilot CLI 上，需先确认平台对子代理的支持情况，否则应回退到 executing-plans 串行执行模式。

5. 工具迁移与审查优化

• Claude Code 工具迁移：内部任务管理应使用 TaskCreate / TaskUpdate / TaskList，严禁使用已废弃的 TodoWrite（规避 Issue #1518）。
• 审查性能优化：在 v5.1.0 上，若发现 review 过程异常缓慢，应跳过该步骤或改用 inline self-review，以规避 Issue #1538 导致的性能瓶颈。

6. 不可绕过的高风险操作

尽管上述技巧旨在减少摩擦，但以下高风险操作仍必须经过用户确认，不在自动覆写范围内：

• 删除文件
• 大规模重构
• 修改 git 历史
• 推送远程仓库
• 修改环境配置
• 修改 CI/CD 流程
• 数据库变更

关键要点

• 范式转移：Superpowers v5.1.0 已废弃斜杠命令，必须使用自然语言意图（如“这是轻量改动”）来控制执行流程。
• 任务分级策略：
  • 轻量任务：直接执行，最多问 1 个问题。
  • 中型任务：简短计划 + 单次 review。
  • 大型任务：完整链路（Brainstorming → Plans → Subagent → Review）。
• Worktree 避坑指南：
  • 非明确要求不创建 worktree。
  • 避免在原生隔离区内重复创建。
  • Windows 用户注意：首次 worktree 异常立即停止，勿自动重试（Issue #1546）。
• Git 操作规范：
  • 子代理切换 commit 必须使用 git switch -c 或显式 checkout，禁止裸 git checkout <sha>（Issue #1543）。
  • 长时间无子代理回报需主动打断（Issue #1545）。
• 工具与审查优化：
  • 使用 TaskCreate/Update/List 替代废弃的 TodoWrite（Issue #1518）。
  • Review 慢时改用 inline self-review（Issue #1538）。
• 安全红线：删除文件、重构、改历史、推远程、改 CI/DB 等高风险操作必须人工确认。

意义与影响

这份更新指南对于仍在深度使用 Codex 和 Superpowers 的开发者具有重要的实用价值。

1. 降低认知负荷：通过明确的任务分级和自然语言指令，开发者可以更直观地控制 AI 的行为，无需记忆复杂的命令语法。
2. 提升开发效率：针对 v5.1.0 的特定优化（如跳过冗余审查、优化子代理执行逻辑）显著减少了等待时间和无效交互，使 AI 辅助编程更加流畅。
3. 规避已知缺陷：文档中明确列出了多个已知 Issue（如 #1546, #1543, #1545, #1518, #1538）的规避方案，帮助开发者避开潜在的崩溃、数据丢失或性能瓶颈。