古法编程

要验证 subagent-driven-development 技能是否真正按流程执行，Superpowers 项目采用分层测试策略。快速测试脚本通过问答验证技能规则定义无误；集成测试则构建真实项目，运行 Claude Code 执行计划，通过解析会话记录（JSONL）来验证技能是否驱动代理完成了子代理派遣、自审、顺序审查和结果交付的完整闭环。

Claude Code 技能集成测试源码解读：如何验证 subagent-driven-development 真正按流程执行

技能文档（SKILL.md）定义了 AI 代理的工作流理想模型，但真正的挑战在于确保代理在实际运行中严格遵守这些规则。Superpowers 项目为 subagent-driven-development 技能构建了一套完整的自动化验证体系，通过“快速问答测试”验证代理对规则的“理解”，再通过“端到端集成测试”验证其实际“执行”，辅以 token 分析工具量化工作流的经济性。这套体系确保了技能从定义到实践的一致性。

第一层验证：快速测试脚本（test-subagent-driven-development.sh）

tests/claude-code/test-subagent-driven-development.sh 是一个快速行为测试（约2分钟完成）。它不运行完整的代码实现，而是通过 test-helpers.sh 中的 run_claude 函数以无头模式向 Claude 提出关于技能的关键问题，并用断言函数验证其回答，从而确保技能的核心规则已被正确加载和表述。

该脚本覆盖了技能定义的九个关键方面，每项测试都针对一个具体的设计决策：

  1. 技能加载（Skill Loading）：验证代理能识别技能名称并提及“加载计划”等核心步骤。
  2. 工作流顺序（Workflow Ordering）：使用 assert_order 函数断言输出文本中，“规范符合性审查”（spec.*compliance）必须在“代码质量审查”（code.*quality）之前被提及，确保审查优先级正确。
  3. 自审要求（Self-review requirement）：验证技能要求实施子代理（implementer）在汇报前进行自审，并检查“完整性”（completeness）。
  4. 计划读取效率（Plan reading efficiency）：确保控制器（controller）只在开始时读取一次计划文件，以优化 token 使用。
  5. 审查者心态（Skeptical reviewer mindset）：验证规范审查者对实施者的报告持怀疑态度（skeptical），并会独立阅读代码（read code）。
  6. 审查循环（Review loop requirements）：确认技能描述了审查是一个循环过程，直到通过为止。
  7. 任务上下文提供方式（Task context provision）：通过 assert_contains 和 assert_not_contains 共同验证，控制器将完整的任务文本直接提供给子代理，而非让子代理自行读取文件。
  8. 工作树前提要求（Worktree requirement）：检查 using-git-worktrees 是否作为前置依赖被提及。
  9. 主分支警告（Main branch red flag）：验证技能是否警告不得直接在主分支上开始实现。

这些测试本质上是确保技能的“说明书”是清晰、完整且无歧义的，为后续的执行验证打下基础。

第二层验证：端到端集成测试（test-subagent-driven-development-integration.sh）

test-subagent-driven-development-integration.sh 是真正的“实战演练”，耗时10-30分钟。它模拟了一个真实的开发场景：在临时创建的 Node.js 项目中，使用 subagent-driven-development 技能执行一个包含两个任务（add 和 multiply 函数）的实现计划。

集成测试的工作流分为几个明确阶段，其验证逻辑与快速测试有本质区别，它依赖于对 Claude Code 会话记录的解析：

  1. 环境搭建与执行：

    • 使用 create_test_project 创建临时目录，并初始化 git 仓库。
    • 设置一个简单的 package.json 并编写包含两个详细任务的 implementation-plan.md 计划文件。
    • 构造一个明确的提示（prompt），要求 Claude 使用该技能执行计划，并列出了需要验证的五个关键点。
    • 使用 timeout 1800 claude -p ... 命令运行 Claude Code，捕获输出并保存。

  2. 会话记录捕获与定位：

    • 测试脚本通过 TEST_PROJECT_REAL 和特定的路径编码规则，在 ~/.claude/projects/ 下定位本次会话产生的 .jsonl 格式的会话记录文件。

  3. 基于记录的行为验证：与快速测试检查文本回答不同，集成测试通过 grep 分析 JSON 会话记录来验证实际发生了什么：

    • 技能调用：检查记录中是否有调用 superpowers:subagent-driven-development 技能的条目。
    • 子代理派遣：统计 Task（或 Agent）工具的调用次数（grep -cE '"name":"(Agent|Task)"'），确保至少派遣了 2 个子代理对应两个任务。
    • 任务跟踪：检查 TodoWrite 工具的使用，验证了任务清单在流程中被动态管理。
    • 结果验证：在测试项目目录中检查 src/math.js 和 test/math.test.js 文件是否被创建且内容正确，并运行 npm test 验证测试通过。
    • 流程完整性：检查 git 提交历史，确保有多次提交，体现了任务完成的流程。
    • 规范符合性：检查最终代码中是否没有出现计划外的“额外功能”，侧面反映了规范审查的效果。

测试基础：test-helpers.sh 提供的断言工具

test-helpers.sh 是整个测试套件的基石，它封装了通用函数，使得测试脚本编写更简洁、一致：

  • run_claude：封装了 Claude Code 的无头模式调用（claude -p），支持设置超时和允许的工具。
  • assert_contains / assert_not_contains：用于验证输出文本是否包含或不包含特定模式，是快速测试的核心。
  • assert_order：通过比较两个模式在输出中首次出现的行号，验证它们的顺序关系。
  • create_test_project / cleanup_test_project：管理临时测试目录的生命周期。

量化洞察：analyze-token-usage.py 的统计逻辑

集成测试的最后一步是调用 analyze-token-usage.py 脚本，它对会话记录进行深度分析，将抽象的流程遵守转化为可量化的成本数据。

该脚本的分析逻辑如下：

  1. 遍历会话记录（.jsonl）的每一行。
  2. 当遇到 type: "assistant" 的消息时，将其 usage 中的 token 数据累加到主会话（控制器） 统计中。
  3. 当遇到包含 toolUseResult 和 agentId 的用户消息时，表明这是一个子代理任务的结果。脚本将该 usage 中的 token 数据累加到对应 agentId 的子代理统计中，并从 prompt 的首行提取子代理的任务描述。
  4. 最后，分别计算主会话和每个子代理的 token 总量，并基于固定的 token 单价估算成本。

这个分析提供了关键的效率洞察：可以观察子代理派遣是否产生了预期的 token 模式；验证“控制器只读一次计划”是否真的降低了主会话的输入 token 消耗；并为评估技能的整体成本效益提供了客观依据。运行集成测试后，会输出一份详细的报告，按主会话和每个子代理列出消息数、输入/输出 token、缓存 token 和估算成本。

运行测试的环境要求

根据项目文档（docs/testing.md 和 tests/claude-code/README.md）的说明，运行这些测试需要满足以下条件：

  • 必须在 Superpowers 插件目录内运行测试（cd tests/claude-code），以确保技能能被正确发现和加载。
  • 本地需要安装 Claude Code CLI（claude 命令可用）。
  • 需要在 ~/.claude/settings.json 中启用本地开发插件市场，例如设置 "superpowers@superpowers-dev": true。
  • 集成测试需要较长的执行时间（10-30 分钟），应适当设置超时（脚本中已设置 timeout 1800）。

总结：一个从定义到验证的完整闭环

Superpowers 对 subagent-driven-development 技能的测试，构建了一个从理念定义到实际执行再到量化评估的完整验证链条。快速测试确保技能规则被清晰传达；集成测试在真实场景中验证规则是否被严格执行；而 token 分析工具则提供了执行过程的经济性与效率洞察。这套组合拳不仅验证了当前技能的有效性，也为开发新的 skills 的贡献者提供了可复用的测试模式和信心保障。

FAQ

Q: 为什么集成测试需要 10-30 分钟，能否加速？ A: 集成测试需要运行真实的 Claude Code 会话来完成代码实现、测试和审查，涉及多次子代理交互和模型思考。耗时主要取决于模型响应速度和任务复杂度，测试脚本已设置 timeout 1800（30分钟）作为上限。

Q: 运行这些测试需要什么环境？ A: 需要本地安装 Claude Code CLI，并确保命令行可用。必须在 Superpowers 插件目录内运行测试，同时需要在 ~/.claude/settings.json 中启用本地开发插件市场。

Q: 如何找到并分析一次集成测试产生的会话记录？ A: 会话记录保存在 ~/.claude/projects/ 下，路径基于测试项目目录编码而成。可以使用 find ~/.claude/projects -name "*.jsonl" -mmin -60 查找最近的记录，然后使用 python3 tests/claude-code/analyze-token-usage.py <session-file.jsonl> 进行分析。