DesignDoc 作成

Minispec（何を作るか・なぜ）が確定した後に、「それをどう実装するか」を書く DesignDoc を作る。成果物は Linear のプロジェクトドキュメント 1 本と、チケットへの添付。コードの変更・PR は発生しない。

チケット ID か URL が無ければ「チケットを指定してください（例: /designdoc PROJ-123）」と返して終了する。

フロー

1. チケット・プロジェクト・Minispec の取得
2. コードの裏取り（Explore 委譲可）
3. 構成案と主要な設計判断の提示   ← ★唯一の停止点
4. Linear ドキュメント作成 → チケットに添付 → 完了報告

1. 取得

• Linear MCP でチケットを取得し、所属プロジェクトを特定する
• そのプロジェクト配下のドキュメントを一覧し、[Minispec] を読む。Minispec が無ければここで止まり、先に Minispec を作るか確認する（DesignDoc は仕様の根拠を繰り返さない前提で書くため）
• Figma が無くても進める。UI 節は導線と表示条件だけを書き、「Figma 確定待ち」と明記する

2. コードの裏取り

Minispec の「引き継ぐもの」「実装上の前提」を、対象リポジトリの実コードで確認する。推測で書かない。 以下は必ず押さえる：

• 対象エンティティの生成関数・不変条件（何が固定され、何が引数か）
• Repository の書き込みが触るテーブル数（トランザクション要否の根拠）
• UNIQUE 制約・FK など、素直にコピーすると壊れる制約
• 外部 I/O（オブジェクトストレージ・キュー・他サービス）の既存の呼び方と失敗時の後始末
• 同種の機能の前例（自リポ → 兄弟リポの順）と、その前例のどこを踏襲し、どこを変えるか
• 新規 RPC の配線先（service 登録・authz・DI）と、漏れたときの症状

複数リポジトリにまたがるなら Explore サブエージェントに分けて並列で調べる。ブランチ作業中のリポジトリは origin/main の一時 worktree を scratchpad に切って読み、終わったら git worktree remove する。

3. 構成案の提示（★停止点）

次を 1 メッセージで出し、承認を待つ：

• 主要な設計判断（5〜7 個、裏取りした事実を根拠に）
• 不採用にする案とその理由
• 確認したい点（実装 issue の起票有無、書式の希望など）

承認後は追加の停止なしで 4 を実行する。

4. 作成と添付

• create_document（projectId 指定）で Minispec と同じプロジェクト配下に [DesignDoc] <機能名> を作る
• create_attachment でチケットに URL を添付する
• チケットが未着手なら In Progress にする。着手済みなら変えない
• 完了報告に doc URL・添付結果・未起票の実装 issue 一覧を書く

ユーザーが育てている既存ドキュメントを更新するときは、毎回明示の指示を受けてから行う。「反映しておきます」と宣言して書き込まない。更新は直前に最新を取得してから差分を組む（ユーザーも並行して編集しているため）。

ドキュメントの構成

対象リポジトリ: a / b / c
仕様・背景・PdM 向けの論点は [[Minispec] …](url)。このドキュメントは「その仕様をどう実装するか」だけを書く。

# Context and scope
  Figma リンク（無ければ「未作成」と明記）
  ## Context   — 実装判断の根拠になる前提。コードで裏取りした事実だけを箇条書き（ファイルパス付き）
  ## Scope     — 触るリポジトリと変更の種類
# Goals and non-goals
  ## Goals     — Minispec の Goals を「実装として保証すること」に言い換える
  ## Non-goals — Minispec の Non-Goals + 実装上あえてやらないこと
# The actual design
  ## System-context-diagram — mermaid flowchart。図の後に「変更 / 流用 / 変更なし」を箇条書き
  ## Data storage           — DDL は schema PR リンクに逃す（PR ができたら見出し直下に PR リンクを 1 行で貼る）。doc にはデプロイフロー（後方互換 → アプリ → backfill → NOT NULL 化 など）と不変条件の表だけ
  ## APIs                   — 「RPC 名（新規RPC / 既存RPC・レスポンス拡張）」+ sub bullet。RPC 名は仮と明記（proto PR ができたら「仮」の記述を消して見出し直下に PR リンクを 1 行で貼る）。authz の要否も書く
  ## Sequence-diagram       — RPC ごとに mermaid sequenceDiagram。トランザクション境界と外部 I/O の位置を図に出す
                              メッセージ本文に `;` と `<...>` を書かない（`;` は文の区切りとして読まれて図が壊れ、山括弧は HTML タグとして削られる）。複数の処理は `<br/>` で改行し、プレースホルダは `{...}` にする
  ## Code and pseudo-code   — エンティティ設計・生成関数のシグネチャ・共通/固有の線引き基準・変更箇所の表
  ## Issue 構成（リリース順）— リポ単位の表。依存と「未起票」を明記。起票・PR 作成のたびに該当行へチケットと PR のリンクを追記し、冒頭の「未起票」の記述も更新する（本文側の対応箇所 — Data storage・APIs の見出し直下 — にも同じ PR リンクを貼る）
# Alternatives considered   — 不採用案を「案 — 理由」の形で箇条書き

• Degree of constraint / Cross-cutting concerns は書くことがあるときだけ見出しを置く。結論が APIs に吸収されたら見出しごと消す
• Minispec に書いてあること（引き継ぎ項目の一覧と根拠、PdM 論点）は繰り返さず、リンクで参照する

書き方の原則

• GitHub PR の URL を素のまま（または通常の markdown リンクで）貼ると、Linear が保存時に PR チップ（Linear のレビューページ行き）へ自動変換して GitHub に飛べなくなる。GitHub に直接飛ばすには [owner/repo#N](<https://github.com/owner/repo/pull/N/files>) の形式で貼る（/files を付けると自動変換されない）

• 判断には根拠を付ける。根拠は「既存コードのどこがそうなっているか」か「Minispec のどの決定か」のどちらか

• 前例に倣うときは「倣う理由」ではなく「倣わない箇所とその理由」を書く（倣う箇所は前例のパスで足りる）

• 却下した案の理由はコードや proto のコメントではなく、この doc の Alternatives か PR 説明に置く

• リリース順の根拠（マスタが先・consumer が先 など）は依存の症状まで書く（「先に入れると FK 違反」「逆順は無害」）

• 比喩を使わない。実際の名前・動作・条件で説明する

• 数字や名前を出すときは 1 文に 1 つまで。コマンド・SQL・疑似コードはコードブロックに出す

前提・根拠の箇条書き（Context）の書き方

Context の各箇条は「読み手が実装判断を追うための前提」なので、次を守る：

• まず「何を参照している / 何が起きる」を平易な語で言い、識別子（列名・関数名）は文末の括弧に 1 つだけ添える。ファイルパスは文中に挟まず、落とすか文末に分ける
• 「キー」「エラー」「ID」などの汎用語は 1 つの対象にだけ使う。DB の一意制約・列の値・オブジェクトストレージのキーが同じ文にあるなら「制約」「値」「オブジェクトキー」と呼び分ける
• 因果は読み手に要る段だけ書く。「制約がある → 書くとエラー名 X になる → だからコピーする」の中間段階（エラー名・関数の内部挙動）は How なので Code and pseudo-code 側に置き、前提では「同じ値を 2 行に持てない」までにする
• 名詞止めにしない。各文に動詞を置く
• 前例を複数挙げるときは 1 行に詰めず子箇条に分け、それぞれ「何の前例か」を 1 文で言う