Claude Codeでタスク分解しGitHub Issueに起票する手順

仕様書を渡して「Issueに分けて」と頼むと、Claude Codeはその場でgh issue createを何本も走らせようとします。分け方に人の目が入らないまま、リポジトリに起票が積み上がる形です。

安全に進めるには、案を出す段階と起票する段階を切り分けます。案はplan modeで作らせ、人が直してから、gh issue createだけを許可して依存順に起票します。この記事はその手順を、プロンプト、権限設定、起票コマンドまで通して示します。

Issue案に入れる項目を先に決める

分解の質は、案の「形」を先に指定したかどうかで決まります。形を指定しないと、Issueの粒度が揃わず、順序も読めません。

次の4項目を、Issue1本ごとに必ず書かせます。

粒度の目安は、1本のIssueが1つのPRで閉じることです。複数のPRにまたがるなら分け、1行の修正なら隣と束ねます。

完了条件は本文に箇条書きで置きます。「テストが通る」だけでなく、どのテストか、どの画面で何が見えるかまで書かせると、後でレビューする人が閉じてよいか判断できます。

手順1: plan modeで仕様を読ませてIssue案を作る

plan modeは、Claudeがファイルを読み、計画を書き出すだけで、ソースを編集しないモードです。計画を承認するまで編集はブロックされます。案出しの段階に向いています。

起動は次のどちらかです。

claude --permission-mode plan

起動済みのセッションなら、Shift+Tabを押してステータスバーに⏸ plan mode onが出るまで切り替えます。1つのプロンプトだけ計画にしたいときは、先頭に/planを付けます。

仕様書がまだ文章になっていないなら、先に聞き取りから始める手もあります。ベストプラクティスの例には、思いつきの段階で「仕様が書けるところまで質問してほしい」と頼み、SPEC.mdに書き出させるプロンプトが載っています。仕様書が手元にある場合は次のように頼みます。

@docs/SPEC.md を読んで、実装を GitHub Issue に分割してください。
まだ起票はしません。Issue案を一覧で出してください。
 
各Issueに次を含めてください。
- タイトル(動詞で始める)
- 本文(背景、作業範囲、完了条件を箇条書き)
- 依存するIssue(案の中の番号で)
- ラベル案
 
条件:
- 1つのIssueは1つのPRで閉じる大きさにする
- 依存のないIssueから順に並べる
- 仕様書に書かれていない要件は足さず、不明点は末尾に質問として列挙する

「起票しない」と「仕様書にない要件は足さない」の2行が要です。前者で段階を分け、後者で案がふくらむのを抑えます。

出てくる案の形は、たとえば次のようになります。これは書式を示す例で、実際の出力はリポジトリと仕様書で変わります。

1. ログイン画面のAPI契約を型定義に落とす  [依存: なし]  label: backend
   完了条件: openapi.yaml と型が一致する / 型チェックが通る
2. ログインAPIを実装する                    [依存: 1]     label: backend
   完了条件: 正常系と認証失敗のテストが通る
3. ログイン画面を実装する                   [依存: 1]     label: frontend
   完了条件: 入力エラーが画面に表示される

手順2: 人が案を直してから承認する

計画が出ると、Claudeは進め方を尋ねます。選択肢は3つです。

• 自動承認系のモードに切り替えて進める
• 編集を1件ずつ確認しながら進める
• No, keep planningで計画を続ける

Issue案に不満があるうちはNo, keep planningを選び、「4番を2つに割る」「5番の完了条件を具体的にする」と言葉で直させます。直接書き換えたいときはCtrl+Gで案をテキストエディタに開けます。エディタで直した内容がそのまま次の工程の入力になります。

見るべき点は4つです。

• 1つのIssueに、独立して終えられる作業が2つ以上入っていないか
• 依存の向きが循環していないか(AがBを待ち、BがAを待つ形)
• 完了条件が「実装する」の言い換えになっていないか
• 仕様書の要件が、どこかのIssueに入っているか

最後の項目は、仕様書の節見出しを並べて、Issueとの対応を表にさせると抜けが見えます。

手順3: gh issue createだけを許可する

承認後の起票では、許可の範囲を狭くします。Issueの起票は、リポジトリの共有の場に外から見える書き込みを足す操作です。許可の範囲を広げすぎると、意図しない起票まで通ります。選択肢は2つあります。

1本ずつ確認する: 何も設定しなければ、gh issue createは実行のたびに許可ダイアログが出ます。Issueが5本前後なら、この方法で十分です。ダイアログにはタイトルと本文を含む実コマンドが表示されるので、起票前の最後の確認になります。

案の承認を済ませたうえで、まとめて通す: 本数が多いときは、プロジェクトの.claude/settings.jsonに許可ルールを足します。

{
  "permissions": {
    "allow": ["Bash(gh issue create *)"],
    "deny": ["Bash(gh issue delete *)"]
  }
}

ルールの読み方に、次の点があります。

• ワイルドカードの前の半角スペースはルールの一部です。Bash(gh issue create *)はgh issue create単体にも引数付きにも一致します
• *は引数の全文に一致するので、--repoで別のリポジトリを指定した呼び出しも通ります。起票先のリポジトリは、案を承認する時点で依頼文に明記し、実行時のダイアログでも見比べます
• ルールは「deny、ask、allow」の順に評価され、最初に一致したものが結果になります。denyに入れたコマンドは、より狭いallowがあっても止まります
• 複合コマンドは、区切られた各部分が個別にルールと照合されます。gh issue create ... && gh issue close ...のように繋いだ呼び出しは、close側が許可されていないので確認が出ます
• Bashのルールは、Claudeが書いたコマンドの文字列に対して効きます。gh以外の経路で同じ操作を試みた場合は、別の呼び出しとして扱われます

gh issue deleteの拒否は念のための保険です。起票を許可しても、削除まで任せる理由はありません。

作業後は、許可ルールを消すか、起票用のセッションだけで使います。永続的に残すと、別の作業中にもgh issue createが確認なしで通ります。

手順4: 依存順に起票する

起票の順序には制約があります。--blocked-byには、すでに存在するIssueの番号かURLを渡すからです。番号はGitHubが起票時に採番するので、案の中の「1番」は、実際に作るまで本当の番号が決まりません。

そこで、依存のないIssueから先に起票させ、返ってきた番号を次のコマンドに渡す形にします。

承認したIssue案を、依存のないものから順に gh issue create で起票してください。
1本起票するたびに、返ってきたURLと案の番号の対応を控えてください。
依存があるIssueは、控えた番号を --blocked-by に指定してください。
途中でエラーが出たら、そこで止めて報告してください。

gh issue createの出力にはIssueのURLが含まれるので、Claudeはそれを控えて次のコマンドに使えます。

gh issue createには、依存と構造を表すオプションがあります。

仕様全体を束ねる親Issueを1本作り、各作業を--parentでぶら下げると、進捗が1画面で追えます。まず親を起票し、その番号を子の起票に使います。依存の線は--blocked-byで別に引けるので、「束ねる関係」と「待つ関係」は混ぜずに済みます。

実行されるコマンドは、たとえば次のような形です。

gh issue create \
  --title "ログインAPIを実装する" \
  --body $'背景: ...\n完了条件:\n- 正常系のテストが通る' \
  --label backend \
  --parent 100 \
  --blocked-by 101

上の例の本文は$'...'で囲み、\nを改行として渡しています。二重引用符の"...\n..."だと\nが文字のまま入るので注意してください。本文が長いときは、--body-fileでファイルから読ませる手もあります。

起票後に突き合わせる

起票が終わったら、案と実際のIssueを突き合わせます。Claudeにgh issue listの結果を読ませ、案の番号と実際の番号の対応表を出させます。確かめる点は次の3つです。

• 案の本数と、起票されたIssueの本数が一致しているか
• --blocked-byで指定した依存が、案の依存と同じ向きになっているか
• ラベルとマイルストーンが、案どおりに付いているか

食い違いが出たら、直すのは番号のずれたIssueだけにします。全件を閉じて起票し直すと、通知とリンクが乱れます。

分解のルールをCLAUDE.mdに残す

毎回プロンプトに書くのが重いなら、分解の規約をプロジェクトのCLAUDE.mdに置きます。粒度と完了条件の書き方は、チームで揃えておくと効きます。

## Issue分割のルール
- 1 Issue = 1 PR で閉じる大きさにする
- 本文は「背景 / 作業範囲 / 完了条件」の3見出しで書く
- 完了条件は、実行できるコマンドか、画面で見える結果で書く
- 起票は人が案を承認したあとに限る。承認前に gh issue create を実行しない

最後の1行は、案の段階で勝手に起票されるのを防ぐ歯止めです。ただし文章での指示は強制力を持たないので、確実に止めたいときは、許可ルールの側でgh issue createを許可しない運用と併用します。

つまずきやすい点

--projectが失敗する: Projectへの追加には、projectスコープでの認証が必要です。gh auth refresh -s projectで認証を更新します。

途中で失敗して入力が消える: gh issue createには--recoverオプションがあり、失敗した実行の入力を復元できます。Claudeに再起票させる前に、まず何本が作成済みかをgh issue listで確かめます。同じ案を先頭から流し直すと、重複が出ます。

画像や動画を添えたい: --attachでファイルを添えられます。1コマンドあたり最大50ファイルです。一部のアップロードに失敗してもIssue自体は作成され、コマンドは非ゼロで終了します。成功したか失敗したかは終了コードだけで判断せず、出力されたURLも見ます。

Issueが多すぎる: 本数が増えるほど、人が案を確認しきれなくなります。仕様を2〜3の節に分け、節ごとにplan modeで案を出させ直すと、確認が現実的な量に収まります。

既存Issueとの重複: 起票前に「gh issue listで既存のIssueを読み、重複する案は除いてください」と頼みます。plan modeでの案出しの段階に入れておくと、起票後の整理が減ります。

GitHub MCPサーバーとの使い分け

Issueの起票にはGitHub MCPサーバーも使えます。ただ、今回のように「コマンド1つに許可を絞りたい」場面では、ghが向いています。権限のルールをBash(gh issue create *)の1行で書けて、コマンドが画面にそのまま出るので、何が起きるかを人が読めるからです。

MCPサーバーは、Issueの検索や更新、コメントの取得まで一続きで扱いたいときの選択肢です。設定方法はGitHub MCPサーバーの使い方にまとめています。

分解と起票の後は、Issueごとに実装してPRを作る流れになります。PR側の手順はClaude CodeでPRを作成する手順が扱っています。

まとめ

案出しと起票を別の段階にすると、人の確認が効く場所が2つできます。1つはplan modeの案で、もう1つは起票時の許可ダイアログです。

案の形(粒度、依存、完了条件)を先に指定し、起票は依存のないものから順に、gh issue createに絞った許可で進めます。Issueの本数が少ないうちは許可ルールを足さず、1本ずつ確認する運用でも手間は小さく済みます。plan modeの承認フローや起動方法の全体はPlanモード完全ガイド、コードから見積もりの前提表を作る使い方は見積もり根拠をplan modeで作る手順にあります。