spike-prototype
Spike Prototype
Section titled “Spike Prototype”HARD GATE — HARD GATE — Spikes are time-boxed experiments, not shipping code. Results must be throwaway or clearly isolated. Do NOT merge a spike without a plan to integrate it or replace it with a proper implementation.
A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in specs/archive/spikes/SPIKE-<name>.md.
The spike produces learning, not code to ship. If you find yourself cleaning up spike code for production, stop — run plan-work and develop-tdd instead with the insights you gained.
When to spike
Section titled “When to spike”- The technology is unfamiliar (new library, API, infrastructure)
- The approach is uncertain (multiple solutions exist; none has been tried)
- Estimates are impossible without seeing how the thing actually behaves
- A key assumption needs to be validated before committing to a design
Process
Section titled “Process”1. Define the question
Section titled “1. Define the question”Before writing a single line, state the question the spike must answer:
“Can we [specific thing] using [specific approach] within [constraint]?”
Examples:
- “Can we stream large files from S3 to the client without buffering in memory?”
- “Does the Stripe webhook SDK handle signature verification correctly in our edge runtime?”
- “Can we achieve < 100ms p99 response time for the search endpoint with a naive Postgres full-text search?”
A spike with no question is just unplanned coding. Refuse to start if the question isn’t clear.
2. Set a timebox
Section titled “2. Set a timebox”Agree on a timebox with the user: 30 minutes, 1 hour, 2 hours. When time is up, stop — even if the question isn’t fully answered. Partial learning is still learning.
3. Experiment
Section titled “3. Experiment”Write the simplest code that could answer the question. Ignore:
- Error handling
- Test coverage
- Code quality
- Production concerns
Focus entirely on answering the question.
4. Write specs/archive/spikes/SPIKE-<name>.md
Section titled “4. Write specs/archive/spikes/SPIKE-<name>.md”Save the learning to specs/archive/spikes/SPIKE-<name>.md. Create the specs/ directory if it doesn’t exist.
<spike-template>
Spike: [name]
Section titled “Spike: [name]”Question
Section titled “Question”[The specific question this spike was answering]
Result
Section titled “Result”[Answered / Partially answered / Not answered]
Findings
Section titled “Findings”[What you learned — concrete observations, not opinions]
Evidence
Section titled “Evidence”[Code snippet, benchmark result, API response, or screenshot that proves the finding]
Implications for the plan
Section titled “Implications for the plan”[How this changes the approach, the design, or the estimate]
What was NOT explored
Section titled “What was NOT explored”[Known gaps — things the spike didn’t validate]
Recommendation
Section titled “Recommendation”[Should we proceed with this approach? If yes, what does plan-work need to account for?]
</spike-template>
5. Delete the spike code
Section titled “5. Delete the spike code”After writing the findings, delete or discard the spike code. It is not meant to ship.
6. Feed back into plan-work
Section titled “6. Feed back into plan-work”The spike findings are the input to plan-work. Call plan-work next, informed by specs/archive/spikes/SPIKE-<name>.md.