| name | spike |
| description | Run a time-boxed, throwaway experiment to answer ONE concrete technical unknown before real development — 技术预研 / 摸底 / 验证可行性 / 选型对比 / 第三方 API 或库能不能做到 X / 性能够不够. Use when there's a real technical risk to de-risk first, NOT when the requirement is already clear (then just build it) or a doc lookup would answer it. The output is the CONCLUSION; the code is disposable and never ships. Isolate work in spikes/<topic>/, try libraries in a throwaway env (uv run --with) without touching pyproject, no tests, no quality bar. Pure markdown, no new deps; runs on existing bash/read/write/edit/find_files. |
| category | coding |
Spike（一次性抛弃式技术预研）
用这个技能在正式开发前做一次时间盒内的抛弃式实验，只为回答一个具体的技术未知问题：
「这个库/API/方案能不能做到 X？」「性能够不够？」「这两种选型哪个可行？」
核心心智：代码是垃圾，结论才是产出。 spike 写完，你带走的是「行不行 + 为什么 + 建议」，
代码本身丢弃。它和「正式实现」对立——正式开发追求质量、写测试、进主干；
spike 不写测试、不做错误处理、不追质量，够回答问题就停。
没有专门的工具，也不装任何仓库依赖——全靠已有的 bash / read / write / edit /
find_files / search_content。要试第三方库时用临时隔离环境（见 Step 2），不碰 pyproject.toml。
除非用户明显用其它语言，一律用中文回复。
铁律（最高优先级）
- 单一明确问题 + 可判定的判据。 动手前用一句话写下要回答什么，以及「怎样算成功 / 失败」。
问题太宽泛（「试试这个框架」）就先缩窄成能判定的（「用它 20 行内能不能读到 X 字段」）。
- 时间盒。 定一个上限（用户指定则用之，否则默认 30–60 min）。到点必须停下做决策，
不允许「再改一点就好了」无限投入。超时本身就是一个结论（这条路比预期难）。
- 隔离，绝不污染生产。 所有 spike 代码放
spikes/<topic>/，不改任何生产源码、配置、依赖清单。
- 试库用临时环境，不进 pyproject。 例如
uv run --with <pkg> python spikes/<topic>/probe.py
或临时 venv。绝不把实验依赖写进 pyproject.toml / lock / 打包配置——那是正式开发的事。
- 不追质量。 不写测试、不做异常处理、不抽象、不管命名、不管覆盖率。硬编码、print 调试都行。
- 结束必产出结论。 收尾一定要有「结论文档」（Step 5 模板）：可行性 + 发现 + 对正式实现的建议。
- spike 代码永不直接进正式实现。 要落地就在正式流程（tdd / 正常开发）里重写，spike 只喂结论。
何时用 / 不用
- 用：有真实技术风险要先排除——没用过的库/API、不确定的性能、拿不准的集成方式、
两三个方案要快速对比可行性。目的是降风险，不是交付功能。
- 不用：
- 需求已经清楚、无技术未知 → 直接走正式实现（别用 spike 拖延）。
- 查文档 / 读源码 / 一次
WebSearch 就能答 → 直接查，别写代码。
- 要交付能用的功能 → 那是正式开发，用 tdd / 正常流程，不是 spike。
- 大范围预研需要并行铺开多个独立探针 → 用 subagent-orchestration 分派，每路各跑一个 spike。
流程
Step 0 — 定义问题与判据
写下（可以就写在 spikes/<topic>/QUESTION.md 或直接告诉用户）：
- 问题：一句话，具体、封闭。例：「httpx 能否在流式响应下边收边解析 SSE，且断线自动重连？」
- 判据：怎样算答完。例：「能拿到分块事件 + 主动断网后 5s 内重连成功 → 可行；否则不可行/需再探。」
判据不可判定就别开始——先缩窄问题。
Step 1 — 定时间盒
明确上限（默认 30–60 min，或用户指定）。告诉用户这是时间盒实验，到点给结论。
Step 2 — 隔离环境搭最小原型
mkdir -p spikes/<topic>
uv run --with <pkg1> --with <pkg2> python spikes/<topic>/probe.py
只写回答问题所需的最少代码。硬编码、跳过错误处理、print 一切——这是特性不是缺陷。
Step 3 — 跑实验、如实记录
跑起来，观察真实行为，把发现原样记下来（成功的、失败的、意外的、报错、耗时），不要美化，
不要为了让结论好看而调参数掩盖问题。
Step 4 — 到点决策
时间盒到（或更早得到确定答案）就停，从三选一：
- 可行：判据满足 → 给正式实现的建议（用哪个库、注意哪些坑）。
- 不可行：判据不满足 → 说清楚卡在哪、为什么，是否有替代方向。
- 需再探：问题比预想复杂 → 缩窄成更小的问题，再跑一个短时间盒（而不是无限延长当前这个）。
Step 5 — 产出结论 + 处理代码
写结论文档（下方模板），然后处理 spike 代码：丢弃（rm -rf spikes/<topic> 或不提交），
或归档到 spikes/ 并在文档里明确标注「实验代码，不可复用，正式实现需重写」。
删掉临时环境（.spike-venv 等）。不 commit spike 代码进生产路径。
结论文档模板
# Spike 结论：<问题一句话>
- **判据**：<怎样算成功/失败>
- **时间盒**：<上限 / 实际用时>
## 做了什么
<最小原型试了什么、用了哪些临时依赖及版本>
## 发现
- <观察 1：真实行为 / 报错 / 耗时，如实写>
- <观察 2>
## 结论
可行 / 不可行 / 需再探 —— <一句话判定>
## 对正式实现的建议
- <选型 / 架构 / 要避开的坑；spike 代码不可直接复用，需重写>
反模式
| 错误 | 正确 |
|---|
| spike 代码偷偷合进主干当正式实现 | 只喂结论，正式流程里重写 |
| 无时间盒，「再改一点」无限投入 | 定上限，到点必停并决策（超时也是结论） |
| 把实验依赖写进 pyproject / lock / 打包配置 | uv run --with 临时环境，用完即弃 |
| 给 spike 写测试、做抽象、追覆盖率 | 够回答问题就停，不追质量 |
| 问题太宽泛（「试试 X 框架」）无法判定 | 缩窄成封闭、可判定的一句话问题 |
| 验证完只留代码不留结论 | 必产出结论文档（可行性 + 发现 + 建议） |
| 需求本已明确却用 spike 拖延 | 无技术未知就直接走正式实现 |
自检
相关
