教程概述

Planning-with-files 和 Superpowers 都是优秀的 AI 编程工具，但它们的定位不同。本教程将介绍如何让两个框架协同工作，发挥各自优势。

你将学到

• ✅ 两个框架的定位差异
• ✅ 协同使用的场景
• ✅ 配置方法
• ✅ 最佳实践

框架定位对比

核心理念差异

flowchart TB
    subgraph Superpowers
        A1[技能驱动] --> B1[设计优先]
        B1 --> C1[TDD 流程]
        C1 --> D1[系统化调试]
        D1 --> E1[代码审查]
    end

    subgraph Planning-with-files
        A2[文件驱动] --> B2[持久化记忆]
        B2 --> C2[阶段追踪]
        C2 --> D2[错误记录]
        D2 --> E2[会话恢复]
    end

    style A1 fill:#e1f5ff
    style A2 fill:#fff3e0

功能覆盖对比

适用场景差异

flowchart LR
    subgraph Superpowers 适合
        A1[功能开发]
        A2[测试驱动开发]
        A3[系统化调试]
        A4[代码审查]
    end

    subgraph Planning-with-files 适合
        B1[研究型任务]
        B2[复杂多步骤任务]
        B3[长会话任务]
        B4[代码库探索]
    end

    subgraph 两者都适合
        C1[新功能实现]
        C2[项目重构]
        C3[技术调研]
    end

协同使用场景

场景 1：复杂功能开发

flowchart TD
    A[用户需求] --> B{Superpowers brainstorming}
    B --> C[设计文档]
    C --> D{Planning-with-files /plan}
    D --> E[创建 task_plan.md]
    E --> F{Superpowers TDD}
    F --> G[编写测试]
    G --> H[实现功能]
    H --> I[更新 progress.md]
    I --> J{Superpowers verification}
    J --> K{Stop Hook 验证}
    K -->|通过| L[完成]
    K -->|未通过| F

    style B fill:#e1f5ff
    style D fill:#fff3e0
    style F fill:#e1f5ff
    style J fill:#e1f5ff

工作流程：

1. Superpowers brainstorming - 澄清需求，生成设计文档
2. Planning-with-files /plan - 将设计转化为阶段计划
3. Superpowers TDD - 按阶段执行 TDD 流程
4. Planning-with-files 追踪 - 记录进度、错误、测试结果
5. Superpowers verification - 验证功能正确性
6. Stop Hook - 确认所有阶段完成

场景 2：Bug 修复

flowchart TD
    A[Bug 报告] --> B{Planning-with-files /plan}
    B --> C[创建 task_plan.md]
    C --> D{Superpowers systematic-debugging}
    D --> E[定位根本原因]
    E --> F[记录到 findings.md]
    F --> G[修复 Bug]
    G --> H[更新 Errors 表格]
    H --> I{Superpowers verification}
    I --> J{Stop Hook 验证}
    J -->|通过| K[完成]

    style D fill:#e1f5ff
    style B fill:#fff3e0

工作流程：

1. Planning-with-files - 创建 Bug 修复计划
2. Superpowers systematic-debugging - 系统化定位根因
3. Planning-with-files - 记录发现和修复过程
4. Superpowers verification - 验证修复有效
5. Stop Hook - 确认完成

场景 3：技术调研

flowchart TD
    A[调研需求] --> B{Planning-with-files /plan}
    B --> C[创建研究计划]
    C --> D[调研执行]
    D --> E[更新 findings.md]
    E --> F{2-Action 规则}
    F --> G[记录决策]
    G --> H[输出研究报告]
    H --> I{Stop Hook 验证}
    I -->|通过| J[完成]

    style B fill:#fff3e0

工作流程：

1. Planning-with-files - 创建研究计划
2. 执行调研 - 使用 2-Action 规则记录发现
3. 输出报告 - 生成可复用的研究报告
4. Stop Hook - 确认研究完成

场景选择指南

协同配置方法

文件结构

project/
├── .claude/
│   ├── settings.json          # Hooks 配置
│   ├── plugins/
│   │   └── superpowers/       # Superpowers 插件
│   └── skills/
│       └── planning-with-files/  # Planning-with-files 技能
├── .project/
│   └── designs/               # Superpowers 设计文档
├── task_plan.md               # Planning-with-files 计划
├── findings.md                # Planning-with-files 发现
└── progress.md                # Planning-with-files 进度

配置示例

Claude Code settings.json：

{
  "hooks": {
    "SessionStart": {
      "command": "bash ~/.claude/hooks/session-start.sh"
    },
    "PreToolUse": [
      {
        "matcher": "Write|Edit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-tool-use.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/post-tool-use.sh"
          }
        ]
      }
    ],
    "Stop": {
      "command": "bash ~/.claude/hooks/check-complete.sh"
    }
  },
  "skills": {
    "enabled": [
      "superpowers:brainstorming",
      "superpowers:writing-plans",
      "superpowers:test-driven-development",
      "superpowers:systematic-debugging",
      "superpowers:verification-before-completion",
      "planning-with-files"
    ]
  }
}

优先级设置

当两个框架有冲突时，按优先级处理：

# .claude/config.yaml
priority:
  # 设计阶段优先使用 Superpowers
  design: superpowers
  # 任务追踪优先使用 Planning-with-files
  tracking: planning-with-files
  # 调试优先使用 Superpowers
  debugging: superpowers
  # 研究优先使用 Planning-with-files
  research: planning-with-files

协同工作流设计

brainstorming + task_plan.md

sequenceDiagram
    participant User
    participant SP as Superpowers
    participant PWF as Planning-with-files
    participant File as 文件

    User->>SP: 我想添加评论功能
    SP->>SP: brainstorming 触发
    SP->>User: 苏格拉底式提问
    User->>SP: 回答问题
    SP->>File: 生成设计文档
    File->>PWF: 读取设计文档
    PWF->>File: 创建 task_plan.md
    File->>User: 显示阶段计划

集成点：

• brainstorming 生成的设计文档可作为 task_plan.md 的 Goal 和 Phases 输入
• task_plan.md 记录 brainstorming 的决策

TDD + progress.md

sequenceDiagram
    participant User
    participant SP as Superpowers TDD
    participant PWF as Planning-with-files
    participant File as 文件

    User->>SP: 实现这个功能
    SP->>SP: TDD 触发
    SP->>File: 先写测试
    SP->>File: 再写实现
    SP->>File: 重构
    File->>PWF: 更新 progress.md
    PWF->>File: 记录测试结果

集成点：

• TDD 的测试结果记录到 progress.md 的 Test Results 表格
• TDD 的实现动作记录到 progress.md 的 Session Log

verification + Stop Hook

sequenceDiagram
    participant User
    participant SP as Superpowers verification
    participant PWF as Planning-with-files
    participant Hook as Stop Hook

    User->>SP: 功能完成了
    SP->>SP: verification 触发
    SP->>User: 验证功能正确性
    User->>Hook: 尝试停止
    Hook->>Hook: 检查 task_plan.md
    alt 有未完成阶段
        Hook->>User: 警告未完成
    else 全部完成
        Hook->>User: 验证通过
    end

集成点：

• verification 确认功能正确
• Stop Hook 确认所有阶段完成

最佳实践

1. 明确使用边界

# 推荐的使用边界
design_phase: Superpowers brainstorming
planning_phase: Planning-with-files /plan
implementation_phase: Superpowers TDD + Planning-with-files tracking
debugging_phase: Superpowers systematic-debugging
research_phase: Planning-with-files findings
completion_phase: Superpowers verification + Stop Hook

2. 统一文件位置

# Superpowers 设计文档
.project/designs/

# Planning-with-files 文件
./task_plan.md
./findings.md
./progress.md

3. 决策同步

• Superpowers 的设计决策 → 记录到 task_plan.md Decisions
• Planning-with-files 的研究发现 → 可作为 Superpowers 的输入

4. 错误追踪闭环

1. Superpowers debugging 发现问题 → 记录到 task_plan.md Errors
2. 解决问题后 → 更新 Errors 状态
3. Stop Hook → 检查 Errors 是否都已解决

5. 测试结果统一

• Superpowers TDD 的测试 → 记录到 progress.md Test Results
• Planning-with-files 追踪测试覆盖率变化

完整协同案例

案例：实现用户认证系统

Step 1：Superpowers brainstorming

用户：我想添加用户认证系统

AI（Superpowers）：好的，在设计之前，让我问几个问题：
1. 认证方式：邮箱/用户名/OAuth？
2. 会话管理：JWT/Session？
3. 安全要求：双因素认证？
...

生成设计文档：.project/designs/auth-system-2026-03-26.md

Step 2：Planning-with-files /plan

用户：/plan 实现用户认证系统

AI（Planning-with-files）：基于设计文档，创建任务计划...

生成：

• task_plan.md：5 个阶段（设计、数据库、后端、前端、测试）
• findings.md：记录认证方案决策
• progress.md：初始化

Step 3：Superpowers TDD 执行

用户：开始实现 Phase 2: 数据库

AI（Superpowers TDD）：先写测试...

同时更新 progress.md：

| Time | Action | Files Modified |
|------|--------|----------------|
| 10:00 | 编写用户模型测试 | tests/user.test.ts |
| 10:30 | 实现用户模型 | src/models/user.ts |

Step 4：遇到错误

AI：数据库迁移失败...

（记录到 task_plan.md Errors）
| Error | Attempt | Resolution | Date |
|-------|---------|------------|------|
| 迁移失败：外键约束 | 1 | 调查中... | 2026-03-26 |

Step 5：Superpowers debugging

用户：调试这个错误

AI（Superpowers systematic-debugging）：
1. 复现问题
2. 隔离变量
3. 定位根因
4. 验证修复

更新错误解决方案：

| 迁移失败：外键约束 | 2 | 先创建表再添加约束 | 2026-03-26 |

Step 6：Superpowers verification + Stop Hook

用户：功能完成了

AI（Superpowers verification）：
✅ 邮箱注册测试通过
✅ 登录测试通过
✅ JWT 验证测试通过

AI（Stop Hook）：
检查 task_plan.md...
✅ Phase 1: complete
✅ Phase 2: complete
✅ Phase 3: complete
✅ Phase 4: complete
✅ Phase 5: complete

任务验证通过，可以停止。

小结

协同核心要点

1. 定位互补：Superpowers 规范流程，Planning-with-files 持久化状态
2. 场景选择：根据任务类型选择合适的工具
3. 文件协调：统一文件位置，避免冲突
4. 决策同步：两个框架的决策要互通
5. 验证闭环：verification + Stop Hook 双重确认

检查清单

• 两个框架都已正确安装
• 文件位置统一配置
• Hooks 配置完成
• 了解各自适用场景
• 团队有统一的使用规范

系列导航：

• ← 上一篇：教程 9：Hooks 机制深度配置
• 返回：教程系列索引

系列完结

恭喜你完成了 Planning-with-files 教程系列！希望这个系列能帮助你更好地管理 AI 编程任务。欢迎在评论区分享你的使用经验！