iterate-with-prototypes
Iterate With Prototypes
Overview
不確実な機能で危ないのは、机上の設計から始めること。AI は紙の上で自信満々に間違った骨格を作り、設計書はやがて実コードから乖離する。このスキルは順序を反転する: コードを先に 100% 動かし、設計は後でリファクタ、設計書は最後にコードから起こす。doc を working code から導出するので机上設計とコードの初期ギャップは導出時点で消えるが、継続的な drift には doc の再導出 or code-as-SSOT 運用が要る。
spike や throwaway、独立 QA 自体は有能なエージェントが放っておいてもやる。このスキルの効き目は、この反転の順序とそれを崩さない規律にある。
When to use
- PRD/仕様はあるが、実現可能性 / UX効果 /「既存API・データ構造を流用できる」が未検証
- 機能が複数のプラン文書に跨る規模
- 実装の大半を AI エージェントに任せる
使わない場合: 未検証の仮定が無い既知機能(/define-acceptance-criteria → 実装に直行) / 1 つの問いに答える単発 throwaway(/prototype を直接)。
ガードレール(誤適用防止): code-first が正しいのは、危険な未知が feasibility / UX / 流用可否 で、かつ blast radius が小さく Code-A を捨てやすいとき(例: view 層・BE 凍結)。危険な未知が戻しにくい決定(DB スキーマ / migration / 公開 API 契約 / チーム間境界)なら code-first は不可 — 「まず 100% 動かす」と間違った土台を Code-A に焼き込み、リファクタで剥がせない。その場合は **design-first か「狭い spike + ADR を先に固める」**に切り替える(決め手の観測が本番非接触の spike で取れるなら後者、決定が組織合意や他チームの回答に依るなら前者)。ここでの spike は 本番非接触の throwaway(本番リソース/migration/データ・公開エンドポイントを作らない)に限り、結論は ADR に固める(Code-A にしない)。ADR がまだ 1 本も無い周回では、**戻しにくい決定が必要と判明した時点で(周回のどの位置でも)**案件ディレクトリに ADR-0001-<主題>.md を自分で起こす(戻しにくい決定 1 件につき 1 本 — 別々にロールバックしうる決定なら別 ADR、迷ったら 1 本にまとめる。step 5 の /grill-with-docs を待たない)。起票は呼び出し側の依頼範囲の cap に関係なく行う — 決定を失わないため。決め手となる観測がまだ無い段階なら Status: Proposed として、決定に必要な観測を ledger の該当行へのポインタで書く。reversible な部分(UI 等)を code-first で切り出すのは、それが依存する irreversible 決定の ADR が固まった後。