調査→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や再実装の計測で、過去のレポートの結論が覆った場合は、その文書の冒頭に日付付きの訂正を書き、根拠の記録へリンクする。