| name | doc-design |
| description | ゲームの値を Doc（*.kind.json などの JSON）へ出すときの設計指針。新しい Doc やスキーマを作るとき、既存の Doc にフィールドを足すとき、エディタ（Studio）でフォームが出ない・タブが多すぎて使えないときに参照する |
| user-invocable | true |
Doc 設計 — 何を外に出し、どう分け、どう見せるか
外形の規約（version / スキーマ / fail-open / note / project.json の登録 / 保存即反映）は
docs/doc-conventions.md が担当範囲。ここは設計の判断を扱う。
1. 外に出すか、コードに置くか
| 外に出す | コードに置く |
|---|
| 繰り返し調整する数値（テンポ・閾値・収支・確率） | 描画アルゴリズム・演出の振り付け |
| 個数が増減するデータ（配置・敵・アイテム） | 導出できる値（明るい色は基準色から導く） |
| 色テーマ・文言 | 一度決めたら触らない構造 |
判断軸は「保存即反映で調整できると嬉しいか（エディタや非プログラマ、未来の自分）」。
振る舞い（ルール・当たり判定・生成）はコードのまま。 ロジックを JSON に書き始めたら
設計の匂い — データとコードの境界を考え直す。
2. どう分けるか（1 Doc = 1 関心）
切る物差しは「いつ読み直したいか」。同時に読み直したい物だけを 1 つの Doc に入れる。
実例: harvest.kind.json は 29 個の設定を平らに持っていた。中身は「歩く速さ・暦」（手触り）と
「ふち光・接地影・粒・光の向き・落ち影・画素」（絵の仕上げ）の 2 つの関心で、後者は
絵を生成し直すときだけ読めばよい。harvest.kind.json（11）と harvest.paint.json（19）に
割ったら、エディタのタブは 29 枚から 5 + 6 枚になった。
割れの合図:
- 同じ接頭辞のキーが 5 個以上並ぶ（
shade* shadow* *Grain*）
note に「これは○○のとき 1 度だけ効く」と書きたくなる（＝別のライフサイクル）- スカラーが 30 個を超える
- 一覧型（
sprite.json / 配置 / 敵表）で項目が 16 個・20KB を超える。
割る線は「同じタイミングで描き直すか」 — 地面のタイルと建物と人は直す時が違う。
エディタは 1 筆の確定ごとにその Doc の項目を全部組み直すので、同居させた
無関係な項目の分だけ手触りが鈍る（JSON の読み書き自体は 50KB でも 0.6ms で誤差）
3. どう見せるか
大きさの目安と group の書き方は
docs/doc-conventions.md の「大きさの目安」「タブの束ね方」を見る。
要点だけ:
- 単一値が 5 個以上なら
group で束ねる（タブが値の数だけ増えるのを防ぐ）
- 後から名前が増えるデータは
catalog（フィールドを 1 つずつ宣言しない）
group は Doc を割らない言い訳にしない。まず 1 Doc = 1 関心で割れないか考える
4. スキーマ方言の早見表
Studio がフォームにできるのはこの 5 種類。それ以外の kind は生 JSON 編集に落ちる。
kind | 形 | 使いどころ |
|---|
value / field | セクション自体が 1 個の値 | スカラー。group で束ねる |
record | 文書直下のキーの下に入れ子の値 | まとまった 1 かたまり（start: {x, y}） |
catalog / map | 名前 → 中身の辞書 | 後から名前が増える物（色票・敵の種類） |
list | 並び順に意味がある列 | 行・配置・波 |
書き間違えやすい所（どれも黙ってフォームが出なくなる）:
fields を item と書く（list だけは両方の方言がある）- 型名は
float / int / text / bool / color / vec2 / grid / enum / ref
（number / string / boolean ではない）
order は整数だけ。42.5 と書くと黙って無視されて並びが崩れるproject.json の登録キーは schema（schemaPath ではない）
5. 作ったあとの確認
