Issue 深掘りフォーマット（issue #37 基準）

思いつきの箇条書きをそのまま issue タイトルにしない。1issueは「あとで読んだ人（自分含む）が 背景と判断根拠を再現できる」ミニ設計ドキュメントにする。

使う場面

• ユーザーとのブレインストーミングで出たアイデアを issue化するとき
• 技術的な課題（パフォーマンス・アーキテクチャ選択等）を調査して記録するとき
• CLAUDE.md の開発フロー「1. Issue作成」を実施するとき

軽い誤字修正や1行バグ修正のような自明な作業には、このフォーマットは過剰。 「実装方針に複数の選択肢がある」「背景を説明しないと妥当性が伝わらない」規模の issueにだけ適用する。

手順

1. 先にコードを読む。該当箇所を実際に Read/Grep してから書く。推測で 「〜だと思われる」と書かない。関数名・ファイルパス・行番号・実コードの スニペットを引用し、根拠を示す。存在しないと思ったデータ（例: 業種分類フィールド）は「無い」と実際に確認してから断定する。
2. 外部の一般的な対策を調べる（該当する場合のみ）。ライブラリ選定・ 既知のアーキテクチャパターンが絡む話題なら WebSearch/WebFetch で 一般的な解法・定番ライブラリを調べ、リンク付きで引用する。純粋に このプロジェクト固有の判断（UIの出し分け等）で外部調査が意味を 持たない場合は省略してよい — 無理に「調査」節を作らない。
3. 候補を2つ以上、トレードオフ付きで比較する。「現状維持」や 「もっと簡単な代替案」も候補に含め、なぜ採用しない／するかを書く。 見送る候補にも理由を残す（後で「なぜこれをやらなかったか」の 質問に再調査せず答えられるようにするため）。
4. 推奨方針を1つに絞る。複数候補の組み合わせでもよい。改修範囲 （触るファイル・おおよいそ規模感）と期待効果を具体的に書く。 「やってみないと分からない」を減らす。
5. 関連issueをRefsで繋ぐ。既存の似た issue・元になった issue が あれば Refs #N を本文末尾に入れる。
6. ラベルはこのリポジトリの既存ラベルのみ使う（新規ラベル作成は しない）。gh label list で一覧を確認してから選ぶ。 priority: high/medium/low、area: frontend/backend/agent/infra、 type: feature/enhancement/bug が代表例（増えている場合もあるので 都度確認する）。

本文テンプレート

# 背景・課題

（現状のコードを引用しつつ、何が問題/機会なのかを具体的に。
「〜だと思う」ではなく実際に読んだ結果を書く）

# 調査: 外部の一般的な対策  ※該当する場合のみ

（ライブラリ・定番パターンをリンク付きで）

# 候補比較

## 候補A: ...（推奨/見送り）
- メリット/デメリット

## 候補B: ...
- メリット/デメリット

（「現状維持」「もっと単純な代替」も候補として検討したなら明記）

# 推奨方針

（採用する候補、改修範囲の目安、期待効果）

# 参考リンク
（あれば）

Refs #N

ブレストからissue化する際の流れ

複数アイデアを一度にissue化する依頼を受けたとき、いきなり全件をこの フォーマットで書き切らない（コストが高く、ユーザーが不要と判断した案に 時間を使ってしまう）。

1. まず軽量な一覧（タイトル・1〜2行の概要・優先度案）をユーザーに提示し、 どれを・どの粒度でissue化するか合意を取る。
2. 合意が取れたものだけ、このテンプレートで深掘りして gh issue create する。
3. 作成後にユーザーが「もっと深掘りして」と言ったものは、該当issueを gh issue edit --body-file で本テンプレートに沿って書き直す（作り直して 番号を変えない — 議論の参照先が変わってしまうため）。

実装作業に進む場合

issue作成自体はコード変更を伴わないため git-workflow スキルの対象外だが、 issueの推奨方針に沿って実装に着手する際は git-workflow スキルに従う （ブランチを切ってから着手、一区切りで commit + push）。