yasyf/design-doc（設計ドキュメント）

design-doc（設計ドキュメント） は何をしますか？

すべての散文（サマリー、プレインツイン、ハンドル、リビジョンノート、公開テキストを含む）は gemini-4-argon モデルが執筆および改訂します。セッションは事実とルール（ライティング契約、スロップコップルール、長さ制限）を gemini -m gemini-4-argon --skip-trust -p を通じてモデルに渡し、返答をそのまま取り込み、証拠の収集と結果の公開は自身で行います。散文ヘルパーも同じモデルを gemini --skip-trust -p で呼び出し、フォールバックモデルは使用しません。

アーキテクチャ設計とは、一連の前提条件の上に積み重ねられた一連の意思決定です。このスキルは設計を対話として実行します（ユーザーがすべてを決定し）、すべての主張が前提条件、意思決定、およびそれを生み出した質問ラウンドに遡れる文書を生成します。

以下のコマンドが機械的な部分を実行します。

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <name>   # 新規の ./<slug>/ ディレクトリをこの設計ドキュメント用に作成
$TOOL scaffold --example        # ./tinyq/ に、小さな入力済みの実例を作成
$TOOL check <dir>               # レジスタ、プレインツイン、ダイアグラムソース、サマリーデッキをリント。エラーがあると非ゼロで終了。--strict で公開をブロックする警告もエラーに
$TOOL summary-text <dir>        # デッキをMarkdownとして出力。パネルごとに ## セクション。ゲートへの入力。
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # 散文で使用されているが用語集にない用語を候補として出力
$TOOL build <dir>               # components/*.tsx を components.js にコンパイル。components/ ディレクトリがあるドキュメントのみ
$TOOL render-check <dir>        # ヘッドレスChromeですべてのMermaidブロックをレンダリング。パースエラーまたはページ例外で失敗
$TOOL pdf <dir>                 # テンプレートの印刷用スタイルシートを使用して、ドキュメントを <dir>/design-doc.pdf に印刷
$TOOL snapshot <dir> --note "…" --item "…" # 変更履歴ビューの差分対象となるリビジョンスタンプ。note は読者向け見出し、--item ごとに1つの変更
$TOOL links <dir> [--fetch] [--missing] # すべての意思決定と未解決項目をプルリクエストリンクとステータスとともに表示。--fetch で各リンクのマージ状態と乖離をGitHubに問い合わせ、--missing でまだリンクしていないエントリを一覧表示

フェーズ1の前に reference/method.md を、フェーズ5の前に reference/writing.md を、フェーズ6の前に reference/publish.md をお読みください。methodファイルはラウンド/レジスタプロトコル、writingファイルは声の契約、publishファイルはホスティングフローです。reference/schema.md はJSONファイルのフィールドごとの契約です。埋められたレジスタをスキーマの横で参照したい場合は、tinyqの例をスキャフォールディングしてください。

用語

• レジスタ (Register) — registers.json 内の構造化リストで、エントリには安定したIDが付与されます：A#（前提条件）、DQ#（意思決定）、Q#（未解決の質問）、V#（スパイク）、c-<slug>（アーキテクチャカード）。
• ラウンド (Round) — ユーザーに提示される1つのボードで、逐語的に qa-log.json に記録されます。各ラウンドは、すべての未解決の分岐を同時に質問し、それぞれを design-doc.fork ブロックとして扱います。それ以外は質問しません。新しい分岐を開く回答は、再度すべてを一度に質問する次のラウンドを開始します。qa-log.json はラウンドを順に記録するため、後のボードは前の回答に依存できます。
• 継承 (Supersession) — 変更された意思決定は新しいエントリを取得し、古いエントリは s: "superseded" と by ポインタを持ちます。ドキュメントでは「Replaced by」と後継のタイトルとしてレンダリングされます。インプレース編集がないため、履歴は常に判読可能です。
• スター (Star) (★) — 最も重要な前提条件をマークします。これが失敗するとドキュメント全体が無効になります。
• スパイク (Spike) — 名前付きで時間制限のある実験 (V#) で、(E) とマークされた見積もりを測定値に変換します。
• エグゼクティブサマリー (Executive Summary) — summary.html。registers.json の横にある手書きのHTML断片です。デフォルトでは全画面パネルのデッキとして、設計が単一のアイデアと図である場合は1枚のポスターとして表示されます。データとしてパースされることはありません。check はその形状、ワードバジェット、引用をリントします。
• プレインツイン (Plain Twin) — エントリの正確な表現の横にある p フィールド。エントリの意味を、それを読まない人向けに1～2文で説明します。ドキュメントはデフォルトでプレインツインを表示し、切り替えで正確な表現を表示します。
• キー (Key) と テーマ (Theme) — key: true は、ドキュメントがカードとして開く3～8個の意思決定と前提条件をマークします。theme はすべてのエントリを、フェーズ0で命名され themes マップで定義された設計の3～5個のテーマのいずれかに分類します。
• ダイアグラム (Diagram) — システム図のMermaidソース。diagram レジスタキーに格納され、ドキュメントはこれをレンダリングし、読者はパンやホバーが可能で、リクエストパスをステップ実行できます。diagram.overview は概要カードが描画する10ノードのサブセットで、完全なグラフはワンクリックで表示できます。手書きの sysd.svg は diagram.kind: "svg" として有効です。
• ハンドル (Handle) — すべての意思決定、前提条件、未解決項目、アーキテクチャカード、数値テーブルの h フィールド。読者がそれを呼ぶであろう2～5語の名前です。引用とチップ行はハンドルを表示し、IDはホバーカードに表示されます。
• コンポーネント (Component) — components マップで宣言されたインタラクティブな図です（dd.tabs、dd.before-after、dd.whatif、dd.steps、dd.timeline、dd.matrix、2つの比較パネル図 dd.flow、dd.lanes、手書きシステムマップ dd.system、公開されたアーキテクチャドキュメントを埋め込む dd.arch）。デッキ内またはエントリ上にidで配置され、components/ 以下のTSXファイルがエスケープハッチとして build でコンパイルされます。
• 図の概要 (Figure Brief) と 批評 (Critique) — デッキの基盤となり、それに照らして読まれる2つのNOTES.mdセクションです。ブリーフは図が描かれる前に書かれ、図ごとに5行：その図が伝えるポイント、それが提供する意思決定のID、ポイントを伝える最小のビュー、省略しているもの、使用する実際のラベル。最初の2行は <figcaption> になります。批評はパネル、図、テーブル、統計ごとに1行で、ゲートの前に書かれます：それが提供する意思決定、それが行う主張、読者が残される質問、そして修正または削除。check はこれらの見出しがない場合に警告します。
• リンク (Link) — 意思決定、未解決項目、または調査結果の行の links[] エントリです。プルリクエスト、イシュー、コミット、またはそれを確定するドキュメントを指します。未解決項目のリンクの closes: true は、それを終了するリンクをマークします。ドキュメントは各リンクをGitHubの状態とともにチップとして表示し、各未解決グループの先頭にその項目のうちクローズされた数を表示します。
• ステータス：意思決定は resolved | superseded | open で、ドキュメントでは「決定済み」「置き換え済み」「未解決」と表示されます。前提条件は working | validate で、「想定済み」「確認が必要」と表示されます（ドキュメント外の誰かが確認する必要があります）。未解決項目は open | closed で、「未解決」「クローズ済み」と表示されます。マージされた closes リンクは、s で示される前に項目をクローズします。散文は表示される単語を使用し、JSONは値をそのまま使用します。

スコープ

このスキルは設計で終了します。その出力は意思決定記録とドキュメントです。実装コードは、提案がレビューを通過した後に開始される別のタスクです。4つのゲートが記録の誠実さを保ちます。

• 設計の分岐はユーザーが決定します。たとえ1つのオプションが明らかに正しいように見えても、すべての分岐はラウンドを経由します。「なぜ」の記録は、節約されたやり取りよりも価値があります。
• qa-log.json は逐語的で追加のみです。回答のスペルを修正し、内容は変更せず、説明のみのやり取りはスキップします。これは意思決定ログであり、トランスクリプトではありません。
• 敵対的レビューの成果物は、レンダリングされたドキュメントには残りません。それが推進した意思決定のみが出荷されます。調査結果セクションは自己満足のように読まれ、読者に何も伝えません。
• ドキュメントには虚栄のカウント（「27エントリ」「9スパイク保留中」）は含まれません。数字はシステムを説明する場合にのみ表示され、努力を説明するためではありません。

フェーズ0 — スキャフォールディングと診断

$TOOL scaffold --title <name> を実行します。すべての設計ドキュメントは独自の新しいディレクトリに格納されます。scaffold は ./<slug>/ を作成し（位置引数で明示的なパスを指定することで別の場所に配置可能）、空でないターゲットを拒否するため、1つの設計が別の設計のファイルや既存のプロジェクトに混ざることはありません。提案を行う前に、現在のシステムについてユーザーにインタビューします：何が存在するか、何が問題か、そしてなぜか。診断をNOTES.mdに根本原因として記述し（症状ではなく）、決してボードに載せません。診断をNOTES.mdに直接書き込み、ユーザーはレンダリングされたドキュメントでそれをレビューし、彼らが行うすべての修正は彼らの言葉で折り返されます。診断を締めくくるのは、エグゼクティブサマリーが依存する1つの分類です：今日存在するシステムへの変更 (change) か、要件以外に何もない新規 (net-new) か。同じ流れで設計の3〜5個のテーマを命名します（「ストレージ」「ディスパッチ」「テナンシー」など）。これらは themes マップとなり、意思決定と前提条件が分類されます。診断が命名できないテーマは、設計が持っていないテーマです。誤った診断に基づいて設計することは、後のすべてのフェーズを無駄にします。

終了条件： プロジェクトディレクトリが存在すること。ユーザーがレンダリングされたドキュメントで診断（変更か新規か、テーマを含む）を読み、同意していること。

フェーズ1 — 前提条件

最初のラウンドの前に、利用可能なスキルリストで cc-present:present（/cc-present ボードスキル）を確認し、リストされている場合はSkillツールでそれを呼び出します。インタビューは最初の質問からライブボードとして実行され、AskUserQuestionはcc-presentがない場合のフォールバックとしてのみ使用されます。このプラグインは独自のブロックパックを同梱しています — cc-present pack list を実行し、design-doc のリファレンスフラグメントを読んでください。その design-doc.fork ブロックがインタビューサーフェースであり、インタビューボードが持つ唯一のブロックです。

前提条件は直接 registers.json に書き込みます。ボードが確認したり挑戦したりすることはありません。design-doc.claims ブロック、確認/挑戦スイープ、またはレジスタダンプをユーザーの前に表示しないでください。ユーザーはレンダリングされたドキュメントで前提条件をレビューし、彼らが行う修正は彼らの言葉で折り返されます。設計が選択なしでは進めない前提条件は分岐であり、design-doc.fork ブロックとしてフェーズ2のボードに配置されます。診断インタビュー、コード、およびユーザーがすでに言ったことからグラウンドトゥルースを収集します：設計が満たさなければならない制約、スケールとワークロードに関する事実、ユーザーが信じているが検証していないこと。それぞれが A# エントリ（ステータス working または validate）になります。最も重要なものにスターを付け、各 validate エントリを誰が確認する必要があるかを未解決項目として記録します。ユーザーが前提条件を不安定とフラグした場合、そのフラグはエントリに入ります。ユーザーに代わって解決することは、レジスタの目的を損なうことになります。

終了条件： ユーザーがレンダリングされたドキュメントで前提条件をレビューし、それらがユーザーの知っていることをカバーしていること。$TOOL check がクリーンであること。

フェーズ2 — 設計ラウンド

質問ラウンドによる設計。インタビューは1つの cc-present ボードで、すべての未解決の分岐を同時に質問し、それぞれを design-doc.fork ブロックとして、豊富なオプション（各オプションの結果、賛否、ちょうど1つの推奨、未解決リストへのエスケープ）とともに提示します。ボードはフォークブロックのみを持ち、他は何も持ちません。フォーク以外のものは欠陥です：design-doc.claims ブロック、確認/挑戦スイープ、design-doc.registers ダンプ、またはコンテキストブロック。フォーク自体の質問、結果、賛否が、必要なコンテキストを提供します。新しい分岐を開く回答は、同じ方法で構築された次のボードに送られます。

ラウンドはライブの cc-present ボード上で実行されます。最初のラウンドの前に（フェーズ1とここで再度）、利用可能なスキルリストで cc-present:present（/cc-present ボードスキル）を確認し、Skillツールでそれを呼び出します。その指示がボードの構成とプッシュを管理し、以降のすべてのラウンドはボードを経由します。1つのフォークは1つの design-doc.fork ブロックであり、そのオプションは結果をインラインで伝え、エスケープハッチは {defer: {title, why}} を返します。人間が未解決の質問に名前を付けるため、Q# はそれに何と呼ぶかを尋ねるラウンドを費やすことなく作成されます。パックがない場合、プレーンな choice ブロックが同じ形状を手動で伝えます — すべてのオプションに結果の説明があり、ちょうど1つが "(Recommended)" とマークされ、最後のオプション "Add to open list" が実際に Q# をキューに入れます — そして AskUserQuestion は最後の手段のサーフェースであり、cc-present:present がスキルリストにない場合にのみ使用されます。ボードスキルが存在する間、設計フォークは AskUserQuestion を経由しません。各フォークを、人がその場で答えられるプレーンな質問として尋ねます（「ワーカーはどのようにジョブを受け取るべきですか？」）。それが解決するレジスタIDはブロックの decides フィールドに、または AskUserQuestion の header に続けて配置され、決して質問テキストには含まれません。オプションの結果は何が起こるかを示し、どのエントリを継承するかは示しません。ラウンドはインタビューであり、調査ではありません。現在のドラフトの欠陥を指摘し、ユーザーが挙げなかった代替案を提案し、証拠が一致しない場合は反論し、自分では何も決定しません。各回答は DQ# となり、解決策、拒否された代替案、およびラウンド番号を持ちます。後のラウンドが以前の決定を変更する場合は、継承します：新しい DQ#、古いものに by ポインタ。

終了条件： 未解決リスト以外に未決定のフォークがないこと。すべての DQ# が qa-log.json のラウンドに遡れること。

フェーズ3 — 敵対的レビュー

中間ドラフトを攻撃します。磨きをかけると欠陥が見えにくくなる前に行います。利用可能な場合は codex プラグインスキルを使用します。そうでない場合は、設計に利害関係がなく、懐疑的なシニアエンジニアとして攻撃するように指示された、新しいコンテキストのサブエージェントを生成します。正しさのバグ、欠落した障害モード、不当な数値を探します。出力を <reviewer>-review-<date>.md として逐語的に保存し、各発見を findings レジスタにインデックス付けし（データのみ、決してレンダリングしない）、それぞれを処分します：新しい意思決定、未解決項目、または理由付きの記録された拒否。コードによって修正された発見は、その行の5番目の要素として、修正したプルリクエストを links[] エントリと同じ形状で持ちます。ユーザーの判断が必要な発見は、他のラウンドと同様のラウンドになり、その質問はレビュアーが何を見つけたかを言葉で述べます。発見番号…

[原文が途中で切れています。翻訳は原文のマークダウン構造を尊重し、翻訳可能な部分のみを翻訳しています。]

フェーズ4 — 数値とスパイク

[翻訳元の原文が不足しています]请提供完整的原始 SKILL.md 内容以完成翻译。

フェーズ5 — 散文

[翻訳元の原文が不足しています]

フェーズ6 — 公開

[翻訳元の原文が不足しています]

リファレンス

このスキルが使用するリファレンスファイルについては、スキルディレクトリ内の reference/ サブディレクトリを参照してください。

• reference/method.md — ラウンド/レジスタプロトコル
• reference/writing.md — 声の契約
• reference/publish.md — ホスティングフロー
• reference/schema.md — JSONファイルのフィールドごとの契約