new-design-doc

name	new-design-doc
description	docs/design/YYYYMMDD_NN.md の設計ドキュメントを規約どおり採番・雛形展開して作成する。新しい設計を書き起こすときに使う

設計ドキュメント作成

手順

1. 採番する: docs/design/YYYYMMDD_NN.md。日付は当日、NN は全 doc を通した連番で既存の最大 + 1。ゼロ埋めしない。例 _1, _2, … _65, _66, _67。
   • 日ごとにリセットしない。同じ日に2本作るなら連番が2つ進む。
   • ls docs/design/*.md | sed -E 's/.*_([0-9]+)\.md/\1/' | sort -n | tail -1 で全体の最大番号を確認する。
2. 雛形を使う: docs/design/tmpl.md を土台にする。冒頭の frontmatter を必ず埋める。
   • status: 新規は基本 draft。方針だけ合意済みなら accepted。
   • tags: 領域ラベル。使える語彙は internal/designdoc の KnownTags。ここに無いタグは検証で弾かれるので、増やすときは KnownTags に追加する。
   • auto: 人の判断が要るなら needs-decision、意思決定不要の機械的タスクなら mechanical。ルーチンが無人着手してよいのは mechanical だけ。
   • frontmatter は Issue のラベル兼状態として機能する。go run . designdoc list --open でバックログを一覧できる。
3. 必須セクションを埋める: 背景 / 要件 / 設計 / 変更箇所 / 採用しなかった方法 / コメント。
   • データ定義はコードで示す。struct・型・コンポーネント・フィールドを伴う設計は、散文でなく Go のコードブロックで書き、データの形を一目でわかるようにする。変更を伴うなら変更前後の struct を並べる。振る舞いより「どんなデータを持つか」が設計の骨子なので、まず形を確定させる。
4. 変更箇所テーブルにはファイルパスと変更内容を書く。
5. 末尾に ## 進捗 を設け、変更箇所テーブルの各行に対応するタスクを管理する。粒度が粗ければサブタスクに分解する。
   • チェックボックスの対応フォーマットは3種類に限る。- [ ] 未着手 / - [x] 完了 / - [~] 意図的に着手しない、すなわち不採用・見送り。
   • - [~] は進捗の分母から外れる。- [-] や - [/] は使わず - [~] に統一する。
6. make generate を実行する: doc を追加すると README の設計ドキュメント状況テーブルが変わるので再生成し、README も一緒にコミットする。CI の generate-check が README の再生成を要求するため、怠ると失敗する。frontmatter の検証 designdoc validate も make generate に含まれる。

注意

• ロジック・コメントは日本語で書く。
• データ定義はコードで示す。文章でフィールドを列挙するより、struct をそのまま書くほうが形が正確に伝わり、実装との齟齬も減る。
• 採用しなかった案も理由付きで残す（後から判断根拠を辿れるように）。