mvp-docs

PLAN.md と JUDGE.md を対で作り、実装中に育てる。新規実装を「こういうのを考えている」と対話で始めるとき、既存リポの整理・改修を計画するとき、および実装中に設計判断を下した直後に使う。2文書の目的・作成タイミング・記録する判断の粒度(増やしすぎない基準)とテンプレを持つ。README へ昇華する側は repo-readme。

SKILL.md

GitHub

mvp-docs

PLAN.md と JUDGE.md は対で作る。片方だけ作らない。

  • PLAN.md — 何ができたら終わりか。着手前に書き、完成条件を先に固定する。
  • JUDGE.md — なぜその実装なのか。実装中、判断を下したその場で1件ずつ追記する。

どちらも足場であり永続しない。README へ昇華した時点で削除する(repo-readme スキル §6)。

0. 前提:JUDGE.md の中身を私が創作しない

JUDGE.md は user の判断の記録であって、AI への指示ファイルではない。私が「なぜ X を選んだか」を埋めた時点で文書の意味が消え、その捏造が README の Design Decisions と docs/design-decisions.md にそのまま流れ込む。

私の役割は聞き取って記録すること。判断の理由が対話に出ていなければ、埋めずに user に聞く。選択肢の洗い出しと trade-off の提示は私がしてよい。選ぶのは user。

PLAN.md は叩き台を私が書いてよい。ただし完成条件とスコープは対話で確定させる。

0.5. フェーズとの接続(着手前に判定する)

この Skill は文書を書くだけで、実装の可否を決めない。 誰が実装するかは、リポの CLAUDE.md が宣言するフェーズと local-issue スキルの担当分離に従う。判定はそちらを読む。ここに転記しない。

書いた PLAN からそのままコードに入らないこと。ルートA(改修提案)は MVP 期の駆動文書ではないので、フェーズを問わず書いてよい。

ファイル衛生は repo-standardize スキル §3 に従う。枠だけ作って放置しない。

1. ルートの判定

ルート 起点
A 整理・改修 既存リポの土台に手を入れたい
B 新規実装 「こういうのを考えている」から始まる対話

置き場所はどちらも PLAN.md / JUDGE.md をリポ直下に置く。使い捨ての足場であり、目に入る場所に無いと更新されないまま腐る。docs/ へ入れない(あそこは README を1本の主張に保つための退避先で、公開後も残るもの。repo-readme スキル §7)。

判断はリポ単位で1本にまとめる。改修計画が複数並走する場合だけ PLAN-{topic}.md で分ける。

2. 作るタイミング

PLAN.md

  • ルートA: 対象の現状を実測・実読してから書く。数値は推定でなく実測を入れ、見込みには「見込み」と明記する。
  • ルートB: 対話で方向が見えた直後、コードを書く前。1行もコードを書いていない段階で完成条件を固定する。

JUDGE.md

  • 最初の1件が出た時点で作る。空の枠を先に commit しない(repo-standardize スキル §3)。PLAN を書く過程で捨てた選択肢があれば、それが1件目になることが多い。
  • 以後、判断を下したその場で追記する。実装が一段落してからまとめて書き起こさない(後からだと粒度が落ち、件数が膨らむ)。

3. ルートB の対話の順序

種別(Type A / B / C)が効くのはこのルートだけ。ルートA は既存リポの土台を直す計画なので種別を問わない。

この順で確定させる。飛ばした項目は「未確定」節に残し、埋めたことにしない。

  1. リポの種別(Type A / B / C)を決める — 判定木とリトマス試験は repo-readme スキル §1。ここに転記しない。DoD の形が種別で変わる(「作れた」か「使える」か「分かった」か)ため、完成条件より先に決める。決めた種別と、そう判断した理由は PLAN の冒頭に1行残す。
  2. 誰が何に使うか(1〜2文)
  3. 完成条件(DoD) — その種別の下限(repo-readme スキル §2)を README が満たせる状態から逆算する。加えて「実利用者が1日使える」×「第三者が価値を30秒で理解できる」(.claude/skills/module-dev/SKILL.md)。Type C は「結果の表が README 本文に出ている」が DoD に必ず入る(測るまで結論が未知なので、数字が出ない限り終われない)
  4. やらないこと — ここで切らないと後から膨らむ
  5. 概念の名前と境界 — エンティティ・処理段・情報ソースの区分。公開後 context/domain.md へ移す部分なので、PLAN 内でも独立した節に隔離して書く
  6. 段取り — 依存関係つき

4. 粒度(この文書の本体)

JUDGE.md — 記録する判断の条件

次をすべて満たすものだけ書く。

  1. 実在する選択肢が2つ以上あり、片方を捨てた
  2. 後から変えるとコストがかかる(データ形式・公開面・依存の追加・境界の位置・外部との契約)
  3. コードを読んでも理由が分からない

書かないもの:

  • 規約・既存構成で自動的に決まったこと(conventions.md に書いてある、環境が Nix 管理、等)
  • 実質1つしか選べなかったこと
  • 実装中に自然に決まった細部(変数名・関数分割・ライブラリの API の使い方)
  • 後から無コストで変えられること
  • バグ修正の経緯・試行錯誤の記録(git log の領分)

件数の上限

目安は1リポ 7±2 件。10 件を超えたら粒度が落ちているサインとして、追記する前に既存項目を読み返し、統合できないか見る。統合できないなら、その追記自体が条件3件を満たしていない可能性を疑う。

上限は「重要な判断を落とすため」ではなく、細かい判断で大きな判断を埋もれさせないためにある。20 件並んだ JUDGE.md は、README にも docs/design-decisions.md にも昇華できない。

1件の分量

3〜6行。テンプレの4項目(判断 / 選択肢 / 決め手 / 再検討の境界)で収まらないなら、それは複数の判断が混ざっている。

「再検討の境界」(どの条件が変わったらこの判断を見直すか)を書けない項目は、そもそも判断ではなく作業メモである。この1行が粒度のフィルタとして一番効く。

PLAN.md — 作業単位の粒度

アクションプランの1行は「完了の目安が1行で書けるか」で切る。書けないなら粗すぎるので割る。逆に、完了の目安がコードの1箇所を指すだけなら細かすぎるので束ねる。

5. テンプレ

  • templates/PLAN-cleanup.md — ルートA。各項を「現状 / 改善策 / 効果」で揃え、末尾に依存関係つきアクションプラン
  • templates/PLAN-new.md — ルートB
  • templates/JUDGE.md — 共通

節はテンプレの見出しから該当するものだけ使う。埋まらない節は消す。プレースホルダのまま commit しない(repo-standardize スキル §3)。

6. 出口

実装へ渡すとき: Issue ドリブン期なら、PLAN のアクションプラン1行を1 Issue として local-issue へ渡す。それ以外は相談者がそのまま実装し、判断を下すたび JUDGE.md に戻る。

README を書く段になったら repo-readme スキルへ渡す。PLAN の3仕分け(進捗は捨てる / スコープは README / 概念定義は context/domain.md)と削除はそちらの担当で、このスキルではやらない。