Technical Spike skill for Claude Code
Answer one hard question inside a time box. Claude runs investigations the way a senior engineer would: one sharp question, criteria and thresholds set before testing, a fixed time box, and a throwaway prototype aimed at the riskiest assumption first. Findings come back as a decision memo that leads with a recommendation and confidence level, backed by reproducible benchmarks, cited docs, and named unknowns.
- name
technical-spike - size176 lines · ≈1,800 tokens
- files1
- licenseMIT
- updated
What Claude sees before loading it
This description is the only part of the skill that sits in context all the time. Claude reads it to decide when to load the full playbook below.
description: Runs time-boxed technical investigations that answer one sharp question with evidence, using throwaway prototypes, benchmarks, and documentation checks, and ends in a decision memo with a clear recommendation, confidence level, and next steps. Use when the user asks to evaluate a library, framework, or vendor, check whether an approach is feasible, compare options, de-risk an unknown before estimating, or prototype something to learn rather than ship.Try asking
- Spike whether SSE or GraphQL subscriptions fit our live order updates
- Evaluate Drizzle vs. Prisma for our Postgres service in a day and recommend one
- Can this PDF library handle our 500-page reports? Prototype it and tell me
Use it when
- A library, vendor, or framework needs evaluating before adoption
- Feasibility of an approach is unknown and blocks estimation
- Two or three options need comparing against explicit criteria
- You want a prototype to learn from, not to ship
Skip it when
- The decision is made and needs recording for posterity — use adr-records
- You need a full design document for a known approach — use design-docs-rfc
How to check the result
The memo's opening lines answer the original question, every number links to a reproducible command or script, and the criteria match those written before testing.
The common mistake it prevents
Letting the spike prototype quietly become production code because it mostly worked, untested and full of hard-coded config.
A spike is done when a specific question has an answer backed by evidence gathered within the time box, written as a decision memo someone can act on without rerunning the work. The prototype is a by-product; the memo is the deliverable.
Ground rules
- One question per spike, phrased so it can be answered yes/no or “A over B because”. “Look into GraphQL” is not a spike; “Can GraphQL subscriptions on our current infra push order updates to 5k concurrent clients under 1 s?” is.
- Set the time box and exit criteria before starting. When the box ends, write the memo with what you have, including “inconclusive” and what it would take to conclude.
- Prototype code is throwaway: separate branch or directory, no production quality, never merged as-is. Say so in its README.
- Prefer evidence over opinion: run it, measure it, read the source or official docs. Label anything not verified as an assumption.
- Test the riskiest assumption first. If it fails, the rest of the spike is moot.
Workflow
- [ ] 1. Frame the question, options, and decision criteria
- [ ] 2. Set the time box and exit criteria
- [ ] 3. List assumptions; order by risk
- [ ] 4. Desk research (docs, issues, changelogs, license, maintenance)
- [ ] 5. Build the smallest prototype that tests the riskiest assumption
- [ ] 6. Measure against the criteria
- [ ] 7. Write the decision memo
- [ ] 8. Clean up: archive prototype, file follow-up tickets1. Frame
Write down:
- Question: one sentence.
- Decision it unblocks: what will someone do differently depending on the answer?
- Options: include “do nothing / keep current approach” as a baseline.
- Criteria with thresholds, agreed up front, weighted if there are many:
| Criterion | Threshold / how measured |
|---|---|
| Performance | p95 < 200 ms at 500 rps on staging-sized data |
| Fit | Works with our auth middleware and Postgres 16 without forks |
| Operability | Metrics + structured logs; runs in our container platform |
| Cost | < $X/month at projected volume |
| Maintenance | Release in last 6 months; responsive issue tracker; >1 maintainer |
| License | Compatible with our distribution (MIT/Apache-2.0/BSD preferred) |
| Migration effort | Rough size in days for the full adoption |
2. Time box
| Question type | Typical box |
|---|---|
| Can library X do Y? | 2–4 hours |
| Compare 2–3 options for a component | 1–2 days |
| Feasibility of an architectural approach | 2–5 days |
Exit early when the riskiest assumption fails or one option clearly dominates. Do not extend the box silently; if it needs more time, end with an interim memo and a request.
3. Assumptions
List what must be true for each option to work. Rank by (likelihood of being false) x (cost if false). Typical high-risk assumptions: performance at real scale, integration with an existing auth/data layer, a feature existing in the free tier, behavior under failure (reconnects, retries), and license or compliance constraints.
4. Desk research
Fast, targeted, and cited:
- Official docs for the exact version you would use; migration guides; known limitations pages.
- Issue tracker: search for your use case plus “performance”, “memory”, “production”. Open issues with many upvotes are signals.
- Release cadence, maintainer count, recent commits; security advisories.
- License file in the repo, not just the package metadata.
- Existing usage in your org:
grep -rnacross repos for prior art.
Record links next to each finding. Docs saying it works is a hypothesis; the prototype is the test.
5. Prototype
- Location:
spikes/<date>-<topic>/or branchspike/<topic>. Add a README line: “Throwaway spike code. Do not merge or depend on it.” - Smallest thing that exercises the riskiest assumption against realistic conditions: real data shapes, realistic volume, the actual infra component (or the closest local equivalent via Docker).
- Hard-code everything else. No tests beyond what proves the point, no abstractions.
- Keep a running log of what you tried, what failed, and error messages verbatim; it feeds the memo.
6. Measure
- Benchmarks: same machine, warmed up, multiple runs, report median and p95, include
the command used (
hyperfine,k6,wrk,pytest-benchmark, language bench tools). - Compare against the baseline option measured the same way.
- Capture failures as evidence too: “Connection storms after restart caused 30 s of errors” is a finding.
7. Decision memo
# Spike: <question>
_Date, author, time box: 2 days (used 1.5). Prototype: spikes/2026-10-graphql-subs (throwaway)._
## Recommendation
<One or two sentences: "Use Option B (server-sent events) for order updates; do not
adopt GraphQL subscriptions now." >
**Confidence:** high / medium / low — <why>
## Question and decision
<The question and what this decision unblocks.>
## Options considered
| Criterion | A: GraphQL subs | B: SSE | C: polling (baseline) |
|---|---|---|---|
| p95 push latency @5k clients | 420 ms | 180 ms | 2.5 s |
| Works with current auth | needs custom ws auth | yes | yes |
| Ops impact | sticky sessions required | none | none |
| Effort to adopt | ~3 weeks | ~1 week | 0 |
## Evidence
- Load test: `k6 run spikes/.../sse.js` — results in spikes/.../results.md
- Docs: <link> states <limitation>, confirmed in prototype (log excerpt)
## Risks and unknowns
- <Not tested: behavior behind corporate proxies that buffer streams.>
## Next steps
- [ ] Ticket: production SSE endpoint with auth (est. 3–5 days)
- [ ] Ticket: proxy buffering test in stagingLead with the recommendation. A memo that ends in “it depends” must say on what, and which option to choose in each case.
If the decision is architectural and long-lived, also record it as an ADR (see adr-records) linking the memo.
8. Clean up
- Archive or delete the prototype branch; never let it become the production base.
- File follow-up tickets with the evidence linked; feed effort numbers into work-estimation.
- Remove any cloud resources, API keys, or trial accounts created for the spike.
Gotchas
- Prototype creep: the spike “mostly works”, so it ships. It has no tests, no error handling, and hard-coded config. Rebuild properly using what you learned.
- Toy benchmarks: 10 rows on a laptop say nothing about 10M rows on shared infra. State the conditions and their gap from production.
- Confirmation bias: decide criteria before testing, and try to make the favored option fail.
- Ignoring the baseline: a new tool that is 20% faster but adds a service to operate may lose to the current approach.
- Vendor demos and benchmarks are marketing until reproduced on your workload.
- Unbounded research: reading docs for a day without running anything. Prototype by the first third of the time box.
Verification
- The memo answers the original question directly in its first lines.
- Every quantitative claim has a command, script, or link that reproduces it.
- Criteria and thresholds in the memo match those written before the spike began.
- Prototype is marked throwaway and is not referenced by production code.
About this skill
Written and maintained by the Claude Skills editors to the same editorial standard as every skill in the directory: a selective trigger, a real workflow, known pitfalls and a verification step. First published , last updated . MIT licensed.