spike

Spike

当用户想在真正开始构建之前试探一个想法时，使用此技能——验证可行性、比较方案，或找出无论做多少研究都无法解答的未知问题。Spike 天生就是一次性的。达到目的后就丢弃。

当用户说“让我试试这个”“我想看看 X 是否可行”“先做个 spike”“在我决定做 Y 之前”“快速为 Z 做个原型”“这到底有没有可能？”或“比较一下 A 和 B”之类的话时，加载此技能。

何时不使用此技能

• 从文档或阅读代码中就能得知答案——直接做研究，不要构建
• 工作属于生产路径——改用 plan 技能
• 想法已经验证——直接进入实现

如果用户安装了完整的 GSD 系统

如果 gsd-spike 作为同级技能出现（通过 npx get-shit-done-cc --hermes 安装），且用户想要完整的 GSD 工作流，请优先使用 gsd-spike：它支持持久化的 .planning/spikes/ 状态、跨会话 MANIFEST 跟踪、Given/When/Then 判定格式，以及与 GSD 其余部分集成的提交模式。对于没有安装（或不想使用）完整系统的用户，本技能是轻量独立版。

核心方法

无论规模大小，每个 spike 都遵循以下循环：

decompose  →  research  →  build  →  verdict
   ↑__________________________________________↓
                  iterate on findings

1. 拆解

将用户的想法拆分为 2-5 个相互独立的可行性问题。每个问题对应一个 spike。用 Given/When/Then 的结构整理成表格：

#	Spike	验证内容（Given/When/Then）	风险
001	websocket-streaming	给定一个 WS 连接，当大模型流式传输 token 时，则客户端会在 100ms 内收到分块	高
002a	pdf-parse-pdfjs	给定一份多页 PDF，当使用 pdfjs 解析时，则可以提取结构化文本	中
002b	pdf-parse-camelot	给定一份多页 PDF，当使用 camelot 解析时，则可以提取结构化文本	中

Spike 类型：

• standard — 一种方案回答一个问题
• comparison — 同一问题采用不同方案（共用编号，使用字母后缀 a/b/c）

**好的 spike 问题：**具体的可行性问题，且有可观察的输出。 **不好的 spike 问题：**范围过广、没有可观察的输出，或只是“阅读 X 的文档”。

按风险排序。 最有可能让整个想法无法成立的 spike 应最先运行。如果难点无法奏效，就没必要先为简单部分制作原型。

仅当用户已经明确知道要 spike 什么并说明了这一点时，才跳过拆解。此时将他们的想法作为单个 spike 处理。

2. 对齐（适用于包含多个 spike 的想法）

展示 spike 表格。询问：“按此顺序全部构建，还是需要调整？” 在编写任何代码之前，让用户删除、重排或重新表述。

3. 研究（每个 spike 在构建之前进行）

Spike 并非不需要研究——先进行足够的研究以选定合适方案，再开始构建。每个 spike：

1. 简要说明。 用 2-3 句话说明这个 spike 是什么、为什么重要，以及主要风险。

2. 列出有竞争力的方案（如果确实存在选择）：

   方案	工具/库	优点	缺点	状态
   ...	...	...	...	维护中 / 已弃用 / Beta

3. 选定一种方案。 说明原因。如果有 2 种或更多可信方案，就在该 spike 中快速构建多个变体。

4. 对不依赖外部组件的纯逻辑，跳过研究。

使用 Hermes 工具进行研究：

• web_search("python websocket streaming libraries 2025") — 查找候选方案
• web_extract(urls=["https://websockets.readthedocs.io/..."]) — 阅读实际文档（返回 Markdown）
• terminal("pip show websockets | grep Version") — 检查项目虚拟环境中已安装的版本

对于没有文档页面的库，通过 read_file 克隆并阅读其 README.md / examples/。Context7 MCP（如果用户已配置）也是不错的信息来源——先调用 mcp_*_resolve-library-id，再调用 mcp_*_query-docs。

4. 构建

每个 spike 单独放在一个目录中，并保持独立。

spikes/
├── 001-websocket-streaming/
│   ├── README.md
│   └── main.py
├── 002a-pdf-parse-pdfjs/
│   ├── README.md
│   └── parse.js
└── 002b-pdf-parse-camelot/
    ├── README.md
    └── parse.py

优先选择用户可以交互的形式。 如果唯一的输出只是一行表示“它能用”的日志，spike 就会失败。用户想要亲身感受到 spike 的效果。默认选择按优先级排序如下：

1. 可运行的 CLI，接收输入并打印可观察的输出
2. 能演示该行为的精简 HTML 页面
3. 只有一个端点的小型 Web 服务
4. 能通过易于识别的断言检验问题的单元测试

重视深度，而非速度。 不要只跑通一次理想路径就宣称“它能用”。测试边缘情况。跟进意外发现。只有调查过程足够诚实，结论才值得信赖。

避免以下内容，除非 spike 明确需要：复杂的包管理、构建工具／打包工具、Docker、环境文件、配置系统。全部硬编码——这只是一个 spike。

构建一个 spike——典型的工具调用顺序：

terminal("mkdir -p spikes/001-websocket-streaming")
write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...")
write_file("spikes/001-websocket-streaming/main.py", "...")
terminal("cd spikes/001-websocket-streaming && python main.py")
# Observe output, iterate.

并行对比 spike（002a / 002b）——委派执行。 如果两种方案可以并行进行，且都需要真正的工程实现（而非 10 行原型），就通过 delegate_task 分派任务：

delegate_task(tasks=[
    {"goal": "Build 002a-pdf-parse-pdfjs: ...", "toolsets": ["terminal", "file", "web"]},
    {"goal": "Build 002b-pdf-parse-camelot: ...", "toolsets": ["terminal", "file", "web"]},
])

每个子 Agent 都会给出自己的结论；你来撰写正面对比。

5. 结论

每个 spike 的 README.md 都应以以下内容结尾：

## Verdict: VALIDATED | PARTIAL | INVALIDATED

### What worked
- ...

### What didn't
- ...

### Surprises
- ...

### Recommendation for the real build
- ...

VALIDATED = 核心问题得到肯定答复，并有证据支持。
PARTIAL = 它在 X、Y、Z 等约束条件下可用——请记录这些条件。
INVALIDATED = 因以下原因无法使用。这也是一次成功的 spike。

对比 spike

当两个方案回答同一个问题时（002a / 002b），先依次构建，然后在最后进行正面对比：

## Head-to-head: pdfjs vs camelot

| Dimension | pdfjs (002a) | camelot (002b) |
|-----------|--------------|----------------|
| Extraction quality | 9/10 structured | 7/10 table-only |
| Setup complexity | npm install, 1 line | pip + ghostscript |
| Perf on 100-page PDF | 3s | 18s |
| Handles rotated text | no | yes |

**Winner:** pdfjs for our use case. Camelot if we need table-first extraction later.

前沿模式（选择下一步要做的 spike）

如果已有 spike，且用户问“下一步应该做什么 spike？”，就检查现有目录，并寻找：

• 集成风险 — 两个已验证的 spike 涉及同一个资源，但分别独立测试过
• 数据交接 — 假设 spike A 的输出与 spike B 的输入兼容，但从未验证
• 愿景缺口 — 有些能力被认为存在，却尚未得到验证
• 替代方案 — 针对 PARTIAL 或 INVALIDATED spike 的不同思路

用 Given/When/Then 的形式提出 2-4 个候选项。让用户选择。

输出

• 在仓库根目录创建 spikes/（如果用户采用 GSD 规范，则创建 .planning/spikes/）
• 每个 spike 一个目录：NNN-descriptive-name/
• 每个 spike 的 README.md 记录问题、方案、结果和结论
• 代码保持一次性使用的状态——如果一个 spike 需要花 2 天“清理成可用于生产的代码”，那它就是一个糟糕的 spike

署名

改编自 GSD（Get Shit Done）项目的 /gsd-spike 工作流——MIT © 2025 Lex Christopherson（gsd-build/get-shit-done）。完整的 GSD 系统提供持久化的 spike 状态、MANIFEST 跟踪，以及与更广泛的规范驱动开发流程的集成；使用 npx get-shit-done-cc --hermes --global 安装。