mvp-docs
PLAN.md と JUDGE.md を対で作り、実装中に育てる。新規実装を「こういうのを考えている」と対話で始めるとき、既存リポの整理・改修を計画するとき、および実装中に設計判断を下した直後に使う。2文書の目的・作成タイミング・記録する判断の粒度(増やしすぎない基準)とテンプレを持つ。README へ昇華する側は repo-readme。
SKILL.md.claude/skills/mvp-docs/SKILL.md
GitHubmvp-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 は既存リポの土台を直す計画なので種別を問わない。
この順で確定させる。飛ばした項目は「未確定」節に残し、埋めたことにしない。
- リポの種別(Type A / B / C)を決める — 判定木とリトマス試験は
repo-readmeスキル §1。ここに転記しない。DoD の形が種別で変わる(「作れた」か「使える」か「分かった」か)ため、完成条件より先に決める。決めた種別と、そう判断した理由は PLAN の冒頭に1行残す。 - 誰が何に使うか(1〜2文)
- 完成条件(DoD) — その種別の下限(
repo-readmeスキル §2)を README が満たせる状態から逆算する。加えて「実利用者が1日使える」×「第三者が価値を30秒で理解できる」(.claude/skills/module-dev/SKILL.md)。Type C は「結果の表が README 本文に出ている」が DoD に必ず入る(測るまで結論が未知なので、数字が出ない限り終われない) - やらないこと — ここで切らないと後から膨らむ
- 概念の名前と境界 — エンティティ・処理段・情報ソースの区分。公開後
context/domain.mdへ移す部分なので、PLAN 内でも独立した節に隔離して書く - 段取り — 依存関係つき
4. 粒度(この文書の本体)
JUDGE.md — 記録する判断の条件
次をすべて満たすものだけ書く。
- 実在する選択肢が2つ以上あり、片方を捨てた
- 後から変えるとコストがかかる(データ形式・公開面・依存の追加・境界の位置・外部との契約)
- コードを読んでも理由が分からない
書かないもの:
- 規約・既存構成で自動的に決まったこと(
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— ルートBtemplates/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)と削除はそちらの担当で、このスキルではやらない。