実装 issue の分割・起票

DesignDoc（どう実装するか）が確定した後に、実装作業を Linear の issue に分ける。成果物はプロジェクトのマイルストーンと issue の一式、および DesignDoc の「Issue 構成」表の更新。コードの変更は発生しない。

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

フロー

1. DesignDoc・Minispec・既存 issue の取得
2. 分割案の提示（粒度・依存・マイルストーン）   ← ★唯一の停止点
3. マイルストーン作成 → issue 起票（既存分は改題・所属変更）→ 依存の設定
4. DesignDoc の Issue 構成表に ID を書き戻す → 完了報告

1. 取得

Linear MCP で DesignDoc を読み、「Issue 構成」の表と、各節（Data storage / APIs / Code and pseudo-code / front）の見出しを控える。issue の説明文はこれらの節を参照して書く
同じプロジェクトの Minispec から、確定済みの仕様と未決の論点を控える。未決の論点は issue の説明に「どちらに決まっても API は変わらない」のように影響範囲を書く
プロジェクト配下の既存 issue を一覧する。DesignDoc の表に既に対応する issue（schema・proto など先行して切ったもの）があれば、新規に作らず改題とマイルストーン設定で揃える
過去に同じ型で切ったプロジェクトがあれば、そのタイトルと説明文の形を踏襲する

2. 分割案の提示（★停止点）

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

マイルストーンの一覧（Phase 0 から順に、何を含むか 1 行ずつ）
issue の表（Phase / タイトル / 依存）
粒度の判断で迷った点（細かすぎないか、まとめすぎていないか）と、その根拠
判断を委ねる点（デバッグモード限定の段階リリースを入れるか、検証会の issue を作るか、など）

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

3. 起票

マイルストーンを先に作る（issue がマイルストーンを参照するため）
issue はプロジェクト直下にフラットに作る。親子にしない
タイトルは [<リポジトリ名>] <内容>。リポジトリ名は owner を除いた名前
既存 issue はタイトルを同じ形式に改題し、マイルストーンに入れる
担当者は指示が無ければ自分
依存は説明文と blockedBy の両方に書く（書き分けは下記）。説明文の依存は issue ID で書く（Linear が自動でリンクにする。タイトル文字列で書くと改題で食い違う）

4. 書き戻し

DesignDoc の「Issue 構成」表を、起票した ID・リンク・状態で差し替える。表の冒頭にある「未起票」の記述も消す
完了報告に、マイルストーンと issue の一覧、外した／残した依存とその理由を書く

分割の原則

単位

リポジトリごとに切る。 1 issue が 1 リポジトリの 1 PR に対応する形にする
フェーズはネストではなくプロジェクトのマイルストーンで表す。 典型は「Phase 0: proto・DDL」「Phase 1: BE 実装」「Phase 2: FE 実装」。データ移行（backfill → NOT NULL 化）や検証会が要る場合はフェーズを足す
同じフェーズ内の issue は並行できる形にする。並行できない理由（同じファイルを触る、など）があれば依存として明記する

粒度

細かすぎる分割は PR の手間だけ増やす。次は独立させず、使う側の issue に含める：

数十行のリファクタや、単独では価値が出ない準備作業（関数の移動、エンティティへのメソッド追加）。使う側の issue の最初のコミットにする。前例で独立させていたとしても、規模（触るファイル数）が違えば倣わない
同じレスポンス組み立てファイルを触る追加。履歴種別を足す issue で同じファイルを触るなら、その種別のレスポンス詰め替えも同じ issue に入れる
同じデータを表示に使うだけの FE 変更。1 つのフラグを注記・警告・ラベルの 3 か所で使うなら 1 issue にする

逆に、次は分ける：

触るファイル数が多い再編（10 ファイル超）。レビューの負荷と巻き戻しやすさのため
マージ順に制約があるもの（マスタ INSERT が先、consumer が先、など）。順序を issue の境界にする
動作確認の経路が違うもの（RPC で確認するものと、画面で確認するもの）

目安は 1 機能で 6〜10 本。超えるなら上の統合ルールを当て直す。

依存の書き分け

依存には 2 種類あり、混ぜると誤解を生む：

種類	意味	書く場所
ブロッカー	ブロッカーが終わるまで着手できない	説明文の「依存:」+ blockedBy リレーション
マージ条件	着手はできるが、マージ前に満たす必要がある	説明文の「マージ条件:」のみ

blockedBy は Linear 上で「今は着手できない」と読まれる。次はブロッカーではないので張らない：

未リリースの proto / 生成コード。PR の head コミットへ pin（dev-pin）すれば実装を進められる。「リリース後に pin を正式版へ差し替えてからマージ」をマージ条件に書く
Done 済みの issue（DDL やマスタ追加の本番反映）。「本番反映済みであること」をマージ条件に書く

次は本当に手が止まるので張る：

同じ value / entity / mapper を追加する issue 同士。重なりを嫌うなら先にマージする側をブロッカーにする
BE が無いと動作確認できない FE issue。BE 側の issue をブロッカーにする
デザインが FIX しないと見た目を確定できない FE issue。デザインの issue をブロッカーにする

迷ったら「その issue に今日着手できるか」で決める。着手できるなら blockedBy は張らない。

説明文の形

<1 段落の要約。何を、どのレイヤーで、どう実現するか>

* 変更箇所: <ファイル・関数・テーブル。DesignDoc の表を要約>
* <設計上の判断で、実装者が迷いそうな点を 1〜3 個。理由付き>
* 依存: <PROJ-123>（<理由>）            ← ブロッカーだけ。無ければ行ごと省く
* マージ条件: <PROJ-124> のリリース後に pin を正式版へ差し替えていること。実装は dev-pin で先に進められる
* 詳細: [[DesignDoc] <機能名>](<url>) の「<節の名前>」

FE issue には「公開制御: 本番ではデバッグモード ON のときだけ表示する（本番への動線解放は別 issue）」のような段階リリースの条件を足す（採る場合のみ）
説明文は DesignDoc の要約であって写しではない。判断の根拠は DesignDoc に置き、issue には「どこを読めばよいか」を書く
未決の論点があれば「<論点> はデザイン確定待ちだが、どちらに決まっても API はこの形で足りる」のように、実装を止めない範囲を書く

Linear MCP の扱い

説明文に issue ID を書くと、保存時に <issue id="…" href="…">PROJ-123</issue> の形に変換される。後から patch で置き換えるときは元の文字列では一致しないので、replace_range で「依存:」から次の箇条までを範囲指定して差し替える
GitHub PR の URL は [owner/repo#N](<https://github.com/owner/repo/pull/N/files>) の形式で貼る（/files を付けないと Linear が PR チップに変換して GitHub に飛べなくなる）
blockedBy の追加は blockedBy、削除は removeBlockedBy。どちらも追記型で、他のリレーションには影響しない
起票直後の issue は Backlog。着手時に In Progress へ進めるのは実装側の作業で、このスキルでは変えない

issue-split

SKILL.md.claude/skills/issue-split/SKILL.md