Spike Rebuild

---
name: spike-rebuild
description: "技術的な不確実性が大きい実装（方式が使えるか、仕様やライブラリが実際にどう振る舞うか、性能や精度が足りるかが動かさないと分からない）を、調査→使い捨てMVP→精査と実験→仕様→MVPの破棄→再実装→報告の順に進める。作業の重さがレベルRのときに使う。'MVPを作ってから作り直して'、'一度試作して捨てて'でも使う。要件が曖昧なだけの作業、既知のパターンで書ける作業、調査だけの依頼には使わない。"
---

# 調査→MVP→再計画→再実装→報告

分からないことを、調べて、作って、測って、確かめる。そのうえで、学んだことだけを持って作り直す。MVPのコードは学ぶための道具で、成果物ではない。

各フェーズの記録は`.tmp/research/YYYYMMDD_{topic}_NN_*.md`に番号付きで残す。番号は、調査が`00`（統合）と`01`〜、MVPが`20`、精査が`30`、破棄と再実装が`40`、報告が`50`。

## 00/10 調査

`research`で、仕様、先行実装、使えるライブラリ、設計の判断点を調べる。トピックが多ければ文書を分け、`00`に統合レポートと各文書への索引を置く。

調査の最後に、**MVPで確かめる問い**を一覧にする。調べても答えが出ず、動かして測らないと決まらないものに限る（例: このライブラリでこの入力が読めるか、この方式でサイズや速度が足りるか）。

MVPの前提のうちユーザーにしか決められないもの（作業場所、実データやテストデータを用意できるか、対象の実行環境など）が決まっていなければ、調査の最後にまとめて確認する。決まっているか、既定で進めてよいものは確認しない。

調査の結論が「作る価値がない」「技術的に成立しない」になったら、MVPに進まずにここで報告する。そうでなければ、問いの一覧を示して、確認を待たずにMVPへ進む。

## 20 MVP

- 新しく作るものは、使い捨てのブランチ`spike/{topic}`で作る。ブランチの作成はユーザーの依頼か承認を経る。
- 既存のコードを改善する場合は、scratchpadにリポジトリを複製して作り、本体には触れない。候補が複数あれば、環境変数やフラグで切り替えて同じデータで比べる。
- 端から端まで動くことを優先する。テストは書かない。エラー処理や細部の作り込みは、問いに答えるのに必要な範囲だけにする。
- 問いごとに計測し、数値を残す。性能の数値は、次の3点を確かめてから使う。
  - ボトルネックを名指しする。変更で数値が動かなかったときも、理由はボトルネックが説明する。
  - 比べる両方の側を、本番と同じ条件（リリースビルド、設定、キャッシュの状態、同じ版とデータ）にそろえる。片方だけ既定の設定なら、比べたのは実装ではなく設定である。
  - 計測した区間で処理が本当に実行されたかを、出力や副作用で確かめる。エラーや空の結果も数える。
- 実装して初めて分かった問題を、見つけた順にすべて記録する。設計を変えるものには印を付ける。

記録には、結論、実装した範囲、計測値、見つかった問題、未確認のことを書く。

## 30 精査と実験

MVPをレビューし（正しさ、性能、設計上の問題）、残った問いを実験で決める。実験はMVPのブランチ上で行ってよい。

設計判断を、**判断・採用・根拠**の表で決める。根拠には計測値を書き、「良さそう」で決めない。実験の数値も、20の3点を確かめてから使う。候補を比べた場合は、採らなかった案と理由も残す。

## 計画: 仕様

`spec`で仕様を書く。

- 受け入れ条件は、MVPで計測した数値から作る（例: 既知点の誤差が1 cm以内、validatorのエラー0）。各条件に`[test]`/`[check]`/`[human]`を付ける。計測値やvalidatorで確かめる条件は、MVPから引き継ぐ検証スクリプトで確かめる`[check]`にする。`[test]`はユーザーがテストケースを示した条件だけに付ける。
- 30の判断表を、設計の根拠として引用する。
- 本体の設計とは別に、MVPから引き継ぐ検証資産（スクリプト、テストデータ、ビューア）を列挙する。

仕様はユーザーの承認を待つ。承認されるまで、破棄と再実装に進まない。

## 40 破棄と再実装

**破棄**

1. MVPの最終状態を、`git bundle`とパッチで`.tmp/research/YYYYMMDD_{topic}_mvp_archive/`に退避する。
2. ブランチで作った場合は、ブランチを削除する。`git branch -D`は承認プロンプトの対象なので、ユーザーの承認を経る。scratchpadの複製で作った場合は、複製を残したまま本体で作業する。
3. 仕様で列挙した検証資産だけをbundleから戻し、新しい実装に合わせて直す。**本体のコードは戻さない。** MVPのコードを見ながら書き写すことも避け、仕様と判断表から書く。

**再実装**

`spec`の「`[test]`がある場合の進め方」に従う。`[test]`の条件があればテストを書き、ユーザーが確認したら固定してから実装する。reviewerには、受け入れ条件に加えて、MVPのコードがそのまま持ち込まれていないかも確認させる。

記録には、退避先、戻したもの、受け入れ条件ごとの合否と根拠、実装中に分かったことを書く。

## 50 報告

最終レポートに、次を書く。

- 受け入れ条件ごとの合否と根拠
- 計画から外れたことと、その理由
- MVPとの比較（コード量、性能、機能の差）
- 残るリスクと未確認のこと
- 各フェーズの記録への索引

MVPや再実装の計測で、過去のレポートの結論が覆った場合は、その文書の冒頭に日付付きの訂正を書き、根拠の記録へリンクする。