research

GitHub issue ( $ARGUMENTS ) に対して、実装に着手する前の技術調査を行う。

本スキルは 事実収集 に責務を絞る。実装方法の候補は列挙して推奨度を付けるが、選択は行わない(選択は /plan の責務)。また、issue とユーザーの頭の中にある「未知(unknowns)」をこの段階でできるだけ発見・言語化することが、後工程の手戻りを防ぐ最大の防御になる。

引数

$ARGUMENTS は <issue> [mode] [tier] の形式で受け取る。

• <issue>: issue 番号(123、#123)または URL。空の場合はユーザーに質問する
• [mode]: auto / normal。auto の場合はユーザーに質問せず、質問したかった内容を「未確認の仮定」として research.md に明記する。省略時は質問してよい
• [tier]: /dev から渡される難易度(M / L / XL / fixed:<model>[/<effort>])。並列調査で起動する Agent の model / effort を決めるためだけに使う(後述)。省略時は opus/low
• subagent として実行され AskUserQuestion が使えない場合(/dev から起動されたとき): normal でも直接は質問できない。質問は呼び出し元の指示どおり tmp/issues/<issue番号>/questions.json(AskUserQuestion と同じ構造: question / header / multiSelect / options[])に書き、最終メッセージを status: needs-input として一旦終了する。回答(answers)が渡されたら文脈を保ったまま続きから進める

手順

1. tmp/issues/<issue番号>/research.md(無ければ research.html)が既にある場合はその内容を確認し、更新が必要か判断する
2. gh issue view で issue を取得する
3. issue の目的・要件・受け入れ条件を分析する
4. 受け入れ条件(AC)の確定 — issue から AC を抽出し、検証可能な粒度に具体化する。AC に番号を振り、後段の /plan が「AC番号 → タスク」のマッピングを作れるようにする
   • issue に AC が記載されていない、または曖昧で検証可能な粒度に落とせない場合は AskUserQuestion でユーザーに質問する(候補となる AC をこちらから提示し、選択・追加・修正してもらう形が望ましい)
   • 既存の research.md に AC が既に記載されている場合は、その内容を尊重して必要に応じて差分のみ更新する
5. インタビュー(不足情報の解消) — 実装計画を進める上で不足している情報(仕様の曖昧な点、未定義の振る舞い、外部依存の確認事項など)を洗い出し、ユーザーに質問する
   • 回答次第でアーキテクチャ(実装方法の選択)が変わる曖昧点を最優先し、AskUserQuestion で 1 テーマずつ段階的に質問する(一度に大量の質問を並べない。回答が次の質問を変えることがあるため)
   • あわせて「参考にしてほしい既存実装・過去の類似変更・デザインはあるか」も確認する(ユーザーの頭の中にだけある慣習や参照先を引き出すため)
   • auto の場合は質問せず、こちらで置いた解釈を「未確認の仮定」として記録して先へ進む
6. コードベース調査 — 影響範囲(変更対象のファイル・関数、呼び出し元、依存関係)を特定する
7. リファレンス収集 — 「書かれていない慣習」を issue 単位で具現化する
   • コードベース内の類似機能・類似パターンの既存実装(この issue の実装が従うべきお手本)
   • 過去の類似 PR(gh pr list --search "<キーワード>" --state merged 等で探す)
   • step 5 でユーザーから得た参照先
   • 見つかった各リファレンスに「何を参考にすべきか」(構成 / 命名 / エラー処理 / テストの書き方など)を 1 行添える
8. 盲点候補の自己点検(blind spot pass) — issue にもユーザーの回答にも現れていない「unknown unknowns」を、観点リストで走査して洗い出す
   • 観点の例: 運用(デプロイ・feature flag・切り戻し)/ データ移行・後方互換 / 権限・認可 / 並行性・競合 / エラーパス・リトライ / 非機能(性能・監視・ログ)/ エッジケース(空・境界値・多重実行)/ 他機能への波及
   • プロジェクト固有の観点としてプロジェクト(git root)の .agents/skills-config/plan/config.json の attentions も参照する
   • 影響が大きい盲点は確認事項としてユーザーに質問する(auto では「未確認の仮定」として記録)
   • 該当なしの観点は書かなくてよい。もっともらしく埋めるのではなく、本当に見落としていそうな点に絞る
9. 実装方法の候補を 3 つ程度洗い出し、それぞれの Pros / Cons を整理する。各候補に 5 段階の推奨度を付ける(選択はしない)
10. 結果を tmp/issues/<issue番号>/research.md に書き出し、同じ内容を research.html としてレンダリングする(「出力」参照)

調査の並列化

step 6(影響範囲)・step 7(リファレンス)・step 8(盲点候補)は互いに独立した調査なので、コードベースが大きい場合は Agent ツール(general-purpose / Explore)で並列に実行してよい。Agent の model / effort は tier で決める: M → opus/low、L / XL → opus/medium、fixed:<model>[/<effort>] → その値、省略時 → opus/low(grep と要約が仕事で、本スキルより判断力を要しない)。subagent_type は dev-<model>-<effort>(/dev が ~/.claude/agents/ に置く、model をフル ID で固定した定義。model 引数は渡さない — エイリアス opus は環境により Opus 5 に解決されるため)。定義が無い場合は Opus 5 に落ちうる general-purpose + model で代替せず、並列化を諦めて inline で順に調査する。各エージェントには調査対象・観点・返してほしい形式(ファイルパスと根拠)を明示して依頼し、結果を本スキルで統合する。小規模なら inline で順に行って構わない。依頼時には「検索は Grep ツールまたは git grep / rg を使い、Bash の grep -r / find <dir> は使わない(gitignore された .secret.local 等の deny ルール対象ファイルを走査して承認待ちになる)」を制約として含める。

出力(md + html の 2 種生成)

• research.md が正: スキル間の伝達媒体。後続スキル(/plan / /review-plan 等)はこちらを読む
• research.html はビュー: md の内容を人間のレビュー用にレンダリングしたもの(CSS・Mermaid 図・テーブル装飾などのリッチ表現はこちらに)。内容の更新は必ず md → html の順で両方に反映する(html だけを編集しない)

レイアウトやスタイル、図表の有無・種類は調査内容に応じて自由に設計してよい(テンプレートは置かない)。ただし他スキルが情報を抽出できるよう、以下のセクションは md の見出し(##)として含めること(html も同構成にする)。

• 概要: issue の目的と背景
• 受け入れ条件: 番号付きの AC リスト(実装手段に依存しない要件レベル)
• 確認事項: ユーザーに確認した事項とその回答
• 未確認の仮定: 質問できなかった・しなかった事項について、こちらで置いた解釈(auto 時は特に必須。/review-plan とチェックポイント停止時の検証対象になる)
• 影響範囲: 変更対象ファイル / 関数(テーブル推奨)と、呼び出し元・依存関係
• リファレンス: 参考にすべき既存実装・過去 PR・デザインと、それぞれ何を参考にするか
• 盲点候補: blind spot pass で見つかった検討漏れの可能性(観点付き)
• Unknowns マップ: 上記の集約表 — 確認事項(known unknowns)/ リファレンス(unknown knowns)/ 盲点候補(unknown unknowns)/ 未確認の仮定 の 4 分類で現状を一望できるようにする
• 実装方法の候補: 3 つ程度の候補それぞれの概要・Pros/Cons・推奨度(★ 5 段階)。選択はしない
• 補足・懸念事項: 実装時に検討が必要な事項
• 難易度シグナル: /triage <issue> confirm が tier 判定の state に使う件数ベースの一覧。所見や tier そのものは書かない(判定は基準を固定した triage に任せ、再現性を保つため)。次の項目を - 項目名: 値 の箇条書きで出す
  • 変更対象ファイル数(影響範囲の表の行数)
  • 書き込み系 identifier(件数と一覧。コレクション名 / イベント名 / キュー名 / 設定キー等、書き込み系 API 呼び出しから見つかったもの)
  • 実装方法の候補間の推奨度差(最上位と次点の ★ 差。例: 2)
  • 未確認の仮定(件数)
  • 影響大の盲点候補(件数)
  • UI 変更(あり(画面 N) / なし)
  • AC 数

依存関係図やコールグラフが理解を助ける場合は、md には Mermaid コードブロックで、html にはレンダリング済みの図(CDN 読み込み)として追加してよい。

注意事項

• issue の内容が曖昧な場合は、ステップ 4-5 でユーザーに確認を取ってから先に進む(auto は仮定を明記して進む)
• 受け入れ条件は「実装の選び方に依存しない」要件レベルで記述する(特定の関数名や実装手段に依存しない)
• コードベースが大きい場合、調査は issue に関連する部分に絞る
• 既存のテスト・型定義・ドキュメントも調査対象に含める
• 調査結果は事実とコードの根拠に基づくこと。推測が含まれる場合は明示する
• 実装方法の 選択は本スキルでは行わない。選択は /plan が行う