Design doc yaml

設計書作成（YAMLファースト）

設計書を「構造の作成（安価でレビュー可能なYAML）」と「成果物の生成（意図的に簡潔なMarkdown）」に分けて作る。AIが大きく読みにくいMarkdownを一気に吐く失敗を避けるのが狙い。

YAMLは使い捨て・ローカル限定の足場で、チームには見せない。成果物は最終Markdownのみ。

適用範囲

設計書・spec・設計ドキュメント・アーキテクチャノート・proposal・ADR の作成要求。$ARGUMENTS に題材が渡る（省略可）。数文で済むメモには大げさなので、その場合は素直に書く。構成要素・関係・リスク・未解決事項が複数あり、散文化の前にレビューする価値があるときに効く。

フェーズ1: 設計をYAMLに起こす

${CLAUDE_SKILL_DIR}/yaml-schema.md を読み、設計をローカルのYAML足場に書く（例: ./design.yaml）。

• 1 concept = 1エントリ。原子的に分解し、summary を散文で水増ししない。
• トレードオフの根拠は rationale: | ブロックに置く（診断は無視、清書が読む）。
• YAMLはユーザーの設計意図から起こすもので、ソース文書から無批判に抽出しない（抽出は誤読を固定し、以降の全ビューが継承する）。

この ./design.yaml は最終Markdownができたら捨ててよいスクラッチである旨をユーザーに伝える。

フェーズ2: 診断して反復（セルフレビュー）

同梱の診断スクリプトでYAMLをMarkdown＋Mermaidのレビュー補助に変換する。

uv run ${CLAUDE_SKILL_DIR}/diagnose.py ./design.yaml -o ./design-review.md

Mermaid対応プレビュー（Obsidian / Zed）で読める。安価かつ決定的（モデルトークン消費なし）で、以下を炙り出す。

• 関係グラフ（全体形を一目で）
• id未設定concept（参照も検出もできない）
• 孤立concept（繋ぎ忘れ）
• 参照切れrelation（存在しないidを指す）
• 重複concept id（後勝ちで無言マージされる）
• disposition の無いrisk（ノートしたが未対応）
• ブロッキングな open question
• importance順のconcept一覧（低重要度のノイズが下に沈む → 肥大化を発見）

検出内容をユーザーに示し、YAML側を直す（レポートは再生成されるので直さない）。指摘は2種類に分かれる。

• 修正必須の構造欠陥（id未設定concept・孤立concept・参照切れrelation・重複concept id・disposition無しrisk）はYAMLを直して消す。
• blocking な open question は消すべき欠陥ではなく、設計を止めうる未解決事項を意図的に前景化したもの。解決するか、残すと決めてユーザーに明示する。

構造欠陥が無くなるまで再実行する。--strict は blocking question も含めて何か残る限り非ゼロ終了するので、blocking question を意図的に残す間は通らない。ゲートに使うなら「構造欠陥0 かつ blocking question を解消済み」を合格と定義すること（「全指摘0」を目指して正当な blocking question を消さない）。

このフェーズがレビューするのは骨格であり、最終散文ではない。

フェーズ3: Markdownへ清書（成果物）

${CLAUDE_SKILL_DIR}/clean-markdown-rules.md に従ってYAMLを最終Markdownに清書する。可読性・肥大化抑制の規約はそこに集約してあり、YAMLにどれだけ詳細が溜まっても成果物は締まる。要点は、importanceが順序と詳しさを駆動し、synthesisが先頭と前面を決め、棄却案や審議過程は成果物を膨らませない、ということ。

清書後は最終Markdownを通し読みする。清書の散文は診断が検査していない新規出力なので、人間の一読を前提に出す。診断は通し読みを減らすが、なくしはしない。

範囲の注意

• 既定は単一成果物・単一読み手なので synthesis はYAML本体に畳む。同じ設計から読み手別に複数の清書を出したくなったら、そのとき synthesis を読み手別の別ファイルに切り出す（core/view分割の再来）。それ以前には切り出さない。
• YAMLや診断レポートを成果物に貼り付けない。足場は捨て、Markdownが単独で成り立つようにする。