Minispec 作成

機能を作る前に「何を作るか・なぜ作るか・何を作らないか」を 1 本にまとめる。成果物は Linear のプロジェクトドキュメント [Minispec] <機能名> 1 本と、チケットへのリンク。コードの変更・PR は発生しない。実装の「どう作るか」は書かない（それは /designdoc の仕事）。

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

フロー

1. チケット・プロジェクト・添付資料の取得
2. 現状の裏取り（既存プロダクトに何があるか）
3. Goals / Non-Goals 候補と論点の提示   ← ★唯一の停止点
4. Linear ドキュメント作成 → チケットにリンク → 完了報告

1. 取得

• Linear MCP でチケットを取得し、所属プロジェクトの説明文を読む。背景・補足・「すぐ本番公開しない」などの制約はプロジェクト側に書かれていることが多い
• プロジェクト・チケットに添付された資料（PDF マニュアル・Figma・Slack スレッド）をすべて読む。PDF は pdftotext -layout でテキスト化し、目次で全体を掴んでから本文を読む。ユーザーがデスクトップなどに置いた資料も同じ扱い
• 同じプロジェクト配下に既に [Minispec] があれば、新規作成ではなく更新かを確認する
• 直近の別プロジェクトの [Minispec] を 1 本読み、見出し構成と文体を揃える

2. 現状の裏取り

Minispec は「既にあるもの」の上に書くので、推測で現状を書かない。対象プロダクトのリポジトリで次を確認する：

• 関係するエンティティと持っている項目（proto の message、学生・求人・企業など）。「現状は氏名と学科しか持っていない」のような前提を表にできる粒度まで
• 関係する RPC の一覧（grep -rhoE '^\s+rpc [A-Za-z]+' で足りる）。同種の機能が別ユーザー種別（学校側・企業側・学生側）に既にあるか
• 既存の通知・連携の仕組み（LINE 通知、デジタル送付、連携企業など）。新機能で「チャットが要る」と思ったときに既存で代替できるかの判断材料
• 模倣元（他社プロダクトのマニュアルなど）がある場合、模倣元の機能一覧と、それぞれが自社の既存データで代替できるかを対応表にする

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

3. 候補の提示（★停止点）

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

• ユーザー種別ごとの Goals 候補
• Non-Goals 候補と、落とす理由
• PdM に確認が要る論点（3〜10 個）と、開発側の案
• 模倣元があれば「模倣する / 変える / 落とす」の仕分け

ユーザーが最初の指示で「ブラッシュアップしつつ不要な仕様を整理して書いて」のように判断を委ねている場合は、停止せずに 4 へ進み、仕分けの結果を完了報告で示す。

4. 作成とリンク

• save_document（project 指定）でチケットの所属プロジェクト配下に [Minispec] <機能名> を作る。icon / color はプロジェクトに合わせる
• save_issue の links でチケットに doc URL を付ける
• チケットのステータスは変えない（Minispec 作成チケットは完了判断がユーザー側にあるため）
• 完了報告に doc URL・落とした仕様とその理由・PdM 論点のうち判断が重いもの 2〜3 個を書く

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

ドキュメントの構成

> **YYYY-MM-DD 初版**。資料の出所と、確定事項が無いこと（論点の合意後に Figma・DesignDoc へ進むこと）を 1〜2 文

## Context
  なぜ必要か（誰が困っているか、ビジネス上の理由）。プロジェクト説明の背景を自分の言葉で書き直す
  * プロジェクトへのリンク、本番公開の条件、基本方針（模倣元があれば何を模倣するか）
  ### 現状の <プロダクト> で使えるもの（この Minispec の前提）
  | 対象 | 現状 | の表。裏取りした事実だけ

## Goals
  ### <ユーザー種別>（学生 / 先生 / 企業 など）ごとに見出しを分ける
  * 「〜できること」で書く。観察できる結果だけ。UI の細部は書かない

## Non-Goals
  * **落とす機能**: 理由。模倣元にあるものを落とすときは、既存の何で代替するか・なぜ今は不要かを必ず書く

## Workflow
  ### 1. <誰が何をする>
  番号付き手順。分岐（学校推薦かどうか、企業アカウントの有無など）は手順の中で明示する
  項目一覧・状態一覧は表にする。状態は「誰がいつ変えるか」の列を付ける

## UI Design
  Figma があればリンクと FIX 日。無ければ「未作成」と明記し、画面の一覧と導線・表示条件だけ書く

## <模倣元>との対応表（模倣元があるときだけ）
  | 模倣元の機能 | ハンディでの扱い | の表。「入れる / 変える / 入れない / 既存で代替」

## PdM に確認する論点と案
  | # | 論点 | 案 | 根拠 | の表。案は開発側の提案と明記し、確定は PdM と相談と書く

## 実装上の前提（エンジニア向け、DesignDoc で詳細化）
  集約の切り方・スナップショットの要否・既存の仕組みの流用先・権限・authz 登録など、DesignDoc で詳細化する前提を箇条書き

• 確定した論点は表の行を消さず、案の列に確定内容と日付・出所（Slack リンクなど）を残す。冒頭の注記も「更新」として追記する
• 旧案を捨てたときは「旧案（不採用）」の節に残す。後から経緯を追えるようにするため

書き方の原則

• 受け入れ条件（Goals）は簡潔に。Figma を見れば分かる UI 詳細は書かず、振る舞いだけを書く
• ユーザー種別ごとに Goals・Workflow を分ける。先生と学生で観点が違う機能を 1 つの箇条に混ぜない
• 落とす仕様には必ず理由を付ける。理由は「既存の X で代替できる」「要望の出所が無い」「別企画」のどれかに落とす。「後で」だけの理由は書かない
• 模倣元の UX の弱点（問い合わせになっている、学生に伝わらない など）は、模倣元の資料の Q&A や注意書きから拾い、変える根拠にする
• 比喩を使わない。実際の名前・動作・条件で説明する
• 1 文に識別子は 1 つまで。汎用語（通知・キュー・エラー）は何を指すか具体名で書く
• 顧客名・学校名・個人名は、プロジェクト説明に書かれているものだけを使う。Minispec は社内ドキュメントなので実名でよいが、スキルや公開リポジトリには持ち出さない
• 仕様に根拠のない制約（件数上限・固定の並び順など）を入れない。入れるなら根拠を表に書く