GitHub CLI で sub-issue を作成する gh-sub-issue extension を作った

はじめに

最近、Claude で Issue 管理するのにハマってるんですよ。

Claude に「Issue #10 を実装して」とか頼むと、ちゃんと GitHub から Issue を読み込んで実装してくれるじゃないですか。めちゃくちゃ便利！

でも、Issue が多すぎると見づらくなっちゃうんですよね...。かといって1つの Issue に全部詰め込むと、今度は Claude が混乱しちゃう。

「親 Issue と sub-issue で階層化して、Claude に渡すときは sub-issue 単位で細かく指示できたら最高なのに...」

そう思って CLI でサクッと sub-issue を作れるツールを探したんですが、なかった。じゃあ作るか！ということで gh-sub-issue という GitHub CLI extension を作っちゃいました。

https://github.com/yahsan2/gh-sub-issue

背景：GitHub CLI への機能追加提案

もともとは GitHub CLI 本体への機能追加として提案・実装していました。

https://github.com/cli/cli/issues/10298#issuecomment-3162380261

すでにこの issue は存在していて、その中で私は実際に gh issue add-sub コマンドとして実装してみて、以下のような使い方ができるように提案しました：

# issue 番号を指定
gh issue add-sub 123

# URL を指定
gh issue add-sub https://github.com/owner/repo/issues/123

# 別のリポジトリを指定
gh issue add-sub 456 --repo owner/other-repo

しかし、GitHub CLI のメンテナーから「extension として実装してみては？」という提案をいただき、独立した extension として公開することにしました。

gh-sub-issue extension の使い方

インストール

gh extension install yahsan2/gh-sub-issue

基本的な使い方

1. 親 issue に sub-issue を追加

# カレントリポジトリの issue #10 に sub-issue を追加
gh sub-issue create 10

# URL で指定
gh sub-issue create https://github.com/owner/repo/issues/10

# 別のリポジトリを指定
gh sub-issue create 10 --repo owner/other-repo

2. sub-issue のタイトルと本文を指定

# インタラクティブモード（デフォルト）
gh sub-issue create 10

# タイトルを直接指定
gh sub-issue create 10 --title "Implement user authentication"

# タイトルと本文を指定
gh sub-issue create 10 --title "Add tests" --body "Write unit tests for the new feature"

3. 複数の sub-issue を一度に作成

# 複数のタイトルをカンマ区切りで指定
gh sub-issue create 10 --title "Task 1,Task 2,Task 3"

4. ラベルやアサインの設定

# ラベルを追加
gh sub-issue create 10 --title "Bug fix" --label "bug,priority"

# アサインを設定
gh sub-issue create 10 --title "Review PR" --assignee "@me"

# マイルストーンを設定
gh sub-issue create 10 --title "Feature A" --milestone "v1.0"

実装のポイント

GitHub CLI の extension システム

GitHub CLI は extension システムを提供しており、gh extension create コマンドで簡単に作成できます。extension は基本的にシェルスクリプトや任意の実行可能ファイルとして実装でき、gh コマンドのサブコマンドとして動作します。

GraphQL API の活用

sub-issue の作成には GitHub の GraphQL API を使用しています。親 issue の description を更新して sub-issue へのリンクを追加する処理も含まれています：

mutation($input: UpdateIssueInput!) {
  updateIssue(input: $input) {
    issue {
      id
      body
    }
  }
}

既存の gh コマンドとの統合

内部的には gh issue create コマンドを呼び出しているため、既存の GitHub CLI のすべてのオプション（ラベル、アサイン、マイルストーンなど）がそのまま使えます。これにより、ユーザーは慣れ親しんだインターフェースで sub-issue を作成できます。

Claude を活用した高速開発

実は Go を書いたことがなかった私ですが、Claude を使って、わずか2-3時間で実装を完成させることができました。
また README などもそれっぽく用意してくれていい感じです。

開発プロセス

1. 既存コードの理解: GitHub CLI の既存コードを Claude に読み込ませ、コードパターンや慣習を理解してもらいました

2. 実装の支援: 「cli/cli のコードスタイルに従って sub-issue 作成機能を実装して」と依頼すると、既存のコードベースと一貫性のある実装を生成してくれました

3. 動作確認も Claude で: CLI ツールということで、コマンドの動作確認も Claude に依頼できました。実際のコマンド実行結果を Claude に渡して、期待通りの動作をしているか検証してもらいました

# 例えば「Claude にテストして」と伝えると以下のようなコマンドを実行して確認してくれる。
gh issue add-sub 123
gh issue add-sub https://github.com/owner/repo/issues/456
gh issue add-sub 789 --repo different/repo

4. エラーハンドリングの改善: エラーケースも Claude と一緒に網羅的に検討し、適切なエラーメッセージを実装しました

Claude は便利

• 学習曲線の短縮: Go の経験がなくても、既存コードのパターンを Claude が理解して適切な実装を提案
• 品質の担保: GitHub CLI の既存コードスタイルに準拠した実装が可能
• 迅速な検証: CLI ツールの動作確認を Claude に依頼することで、開発サイクルが高速化
• 包括的なテスト: 様々なエッジケースを Claude と検討することで、堅牢な実装を実現

AI 駆動開発における gh-sub-issue の活用

ユースケース：AI を活用した PO 業務の効率化

gh-sub-issue は、AI ツール（GitHub Copilot、Claude Code など）と組み合わせることで、プロダクトオーナー（PO）業務を大幅に効率化できます。

タスク分解のワークフロー

1. 仕様の段階的詳細化

   親 Issue: プロダクト要件
   ├── Sub-issue: スペック定義
   ├── Sub-issue: デザイン設計
   └── Sub-issue: タスク分解
       ├── Sub-issue: API 実装
       ├── Sub-issue: フロントエンド実装
       └── Sub-issue: テスト作成
   

2. AI による自動実装

   • 細かく分解された issue は、GitHub Copilot や Claude Code が理解しやすい
   • 各 sub-issue が明確で小さいタスクなので、AI による実装のズレが最小化される
   • GitHub 上で直接実装を依頼できる

実際の活用例

# 大きな機能要件を作成
gh issue create --title "ユーザー認証機能の実装" --body "OAuth2.0 による認証機能を追加"

# Claude でタスク分解
# "この issue を実装可能な単位に分解して"

# 分解されたタスクを sub-issue として作成
gh sub-issue create 1 --title "認証プロバイダーの設定,JWTトークン生成,ミドルウェア実装,ログイン画面UI,テストケース作成"

# 各 sub-issue に詳細な実装指示を追加
gh sub-issue create 2 --title "データベーススキーマ設計" --body "users テーブルと sessions テーブルを作成"

Claude Code との連携パターン

# Workflow agent を使った自動化
# 1. Issue を読み込んで実装開始
claude code --agent workflow-start --issue 3

# 2. 実装の進捗が GitHub 上でリアルタイムに確認可能
gh issue view 3 --comments

# 3. 完了したら自動で PR 作成
claude code --agent workflow-end --issue 3

メリット

1. 進捗の可視化

• すべてのタスクが GitHub Issues 上で管理される
• sub-issue の完了状況で全体の進捗が一目瞭然
• ステークホルダーへの報告が容易

2. AI 実装の精度向上

• 小さなタスク = 小さなコンテキスト: AI が理解しやすい
• 明確な成功基準: 各 issue に具体的な完了条件を記載
• エラーの局所化: 問題が発生しても影響範囲が限定的

3. 並列開発の実現

• 複数の AI エージェントや開発者が同時に異なる sub-issue に取り組める
• 依存関係を issue のリンクで管理
• コンフリクトのリスクを最小化

4. PO 業務の自動化

# 理想的なワークフロー
1. PO が要件を Issue に起票
2. AI がタスク分解して sub-issue を作成
3. 各 sub-issue を AI が自動実装
4. PR レビューと merge
5. 完了報告の自動生成

実践例：Claude で PO 業務を行う

# Step 1: 要件定義
gh issue create --title "ECサイトのカート機能" \
  --body "商品をカートに追加・削除・数量変更できる機能"

# Step 2: Claude にタスク分解を依頼
# "Issue #10 を開発可能な単位に分解して、各タスクの実装順序と依存関係も明記して"

# Step 3: sub-issue を一括作成
gh sub-issue create 10 --title \
  "カートのデータモデル設計,\
  カートAPI実装（追加）,\
  カートAPI実装（削除）,\
  カートAPI実装（更新）,\
  フロントエンド：カート表示,\
  フロントエンド：商品追加UI,\
  フロントエンド：数量変更UI,\
  カート永続化（セッション）,\
  カート永続化（ログインユーザー）,\
  単体テスト作成,\
  E2Eテスト作成"

# Step 4: 各 issue に AI エージェントを割り当て
for issue in $(gh issue list --label "cart-feature" --json number -q '.[].number'); do
  claude code --agent github-workflow-start --issue $issue
done

このように、gh-sub-issue は単なる issue 管理ツールではなく、AI 時代の開発ワークフローを支える重要な基盤となります。

なぜ extension として作ったのか

1. 迅速なリリース: GitHub CLI 本体への機能追加は慎重な検討が必要ですが、extension なら素早くリリースして改善できます

2. 柔軟な実装: 本体に組み込む場合は厳格な設計指針に従う必要がありますが、extension なら自由度が高く実験的な機能も追加できます

3. コミュニティ主導: ユーザーのニーズに応じて機能を追加・改善できます

4. メンテナンスの独立性: GitHub CLI 本体のリリースサイクルに依存せず、独自にアップデートできます

まとめ

GitHub CLI の extension システムを使うことで、本体への機能追加を待たずに必要な機能を実装できました。gh-sub-issue は、大きなタスクを効率的に管理したい開発者の方々に使っていただければ幸いです。

もし使ってみて改善点や要望があれば、ぜひ GitHub の issue や PR でフィードバックをお願いします！

https://github.com/yahsan2/gh-sub-issue

この記事は claude が書いてます