SuperAPI AI 工具集

spike

编程与开发

查看项目

更新于 10-29 17:25

技能介绍

Spike 是一个在开发早期用于方案验证的技能,核心目标是在真正动手构建之前,先确定应选择哪种实现路径。它区别于 falsify:falsify 用于探测不受自己控制的系统,例如服务商是否接受某种数据形状或 API 的实际行为;而 spike 探测的是自己代码库对某种方案的容忍度,并且只产出一次性代码,这些代码会被删除,绝不合并。

何时使用

Spike 的触发条件是客观的,不依赖用户是否明确要求运行。满足以下任一条件即可运行:第一,存在一个以上似乎可行的方案,且需要看到其中一个实际运行才能做出选择;第二,无法指出将会修改哪些文件,如果文件列表只是猜测,那么估算也只能是猜测。

不应运行 spike 的情况包括:阅读文档或源码就能真正回答该问题,或者用户明确要求进行生产环境实现。需要注意一种失败模式:阅读代码常常让人感觉已经足够,但当上述客观触发条件满足时,它们应优先于这种主观感觉。

执行循环

Spike 按以下步骤推进:

  1. 提问:用一句话陈述具体的可行性问题。例如,不是“轨道应该如何工作”,而是“以对话为中心的轨道能否从已有的对话存储中读取条目,而不需要新接口?”
  2. 调研:阅读足够的文档和源码,以便挑选可信的候选方案;当能够命名这些候选方案时即可停止。
  3. 构建:制作最小的可运行产物来验证或推翻该想法,例如可运行的命令行工具、极小的 HTML 页面、一个接口或一个聚焦的测试。不要引入包依赖蔓延、Docker、环境变量文件、应用框架或生产环境清理。
  4. 压力测试:尝试一个边界情况或失败模式。仅在正常路径下有效的方案并未得到验证。
  5. 结论:给出 VALIDATED(已验证)、PARTIAL(部分验证)或 INVALIDATED(已推翻),并写入磁盘。

应该先按风险顺序依次运行最危险的问题。对最危险问题得到一个 INVALIDATED 结论,就能直接淘汰该方向,省去其他所有 spike。一次性并行展开所有问题,相当于为了得到第一个问题本可以给出的答案,却付出了五个答案的成本。

产出位置

一次性原型代码放在 .claude/spikes/<slug>/ 目录中。结论写入 .claude/plans/<ticket>-spike.md。结论文件与 <ticket>-falsify.md 放在同一位置是有意为之:同一阶段、同一读者、在下一次 /clear 时面临同样的命运。审阅者必须看到的内容应放在已提交的 ADR 或 PR 描述中。

结论格式

结论文件应包含:结论标记(VALIDATED | PARTIAL | INVALIDATED)、一句话的可行性问题、比较的方案列表、证据(每个方案对应的确切命令、确切输出和确切测量值)、哪些做法有效、哪些失败或出乎意料,以及建议(发布 / 调整 / 避免)和下一步生产步骤。

只有观察结果才能作为证据。类型检查通过、CI 运行成功或阅读模式定义都属于推理,而不是观察。应说明你拥有的是哪一种。

结论作为 ADR 的输入

Spike 在原型运行起来时并未结束。它的输出是 docs/decisions/NNN-<slug>.md 处 ADR 的输入,并且 ADR 应在实现之前撰写,而不是之后。如果 ADR 在某方案被构建三次之后才出现,那它记录的是已发生的事,而不是一项决策。

使用子代理比较方案

A/B 比较是 spike 中值得并行处理的部分。为每个候选方案分配一个子代理,输入相同、测量相同。独立性是关键:没有见过方案 A 的代理不会把方案 B 合理化地拉向方案 A。父级只保留结论,不保留过程记录。

不要并行展开多问题拆分中的风险排序 spike,因为这会丢弃让 spike 成本低廉的提前停止机制。也不要把 spike 交给同级会话(队友):spike 只需要几分钟到一小时,其价值在于用户看到证据并改变想法。

如果工作量超过一个小型原型,在构建所有变体之前应先询问。

规则

  • INVALIDATED 的 spike 是成功的。它以证据排除了一条路径,成本是一个原型而不是一个拉取请求。
  • 永远不要合并 spike 代码。如果某个方案胜出,应在构建步骤中正常重写它。spike 工作区会被删除,而不是被提升。
  • 拆分为 2 到 5 个独立问题是可行的,先运行风险最高的那个。
  • 在评估外部依赖时,也要检查其健康状况:最近的发布或提交、真实的文档、许可证、安装摩擦。

适用场景

Spike 适用于需要快速判断技术方向是否可行的开发场景,例如在多个架构方案之间做选择、验证某个想法能否用现有代码库实现、评估外部依赖是否值得引入。其限制在于它只产出一次性代码,不适用于直接进行生产实现,也不应用于已有明确文档答案的问题。