github-do-issue

github-do-issue

目的

あらゆるプロジェクトで GitHub の Issue を実装するための、構造化されたワークフローです。各 Issue について、取得し、要件を理解し、進め方を計画して実装し、検証したら、Git 操作を行う前に停止してユーザーのレビューを待ちます。

対象の Issue：キュー

まず、ほかのことをする前に、$ARGUMENTS からキューを決めます。

入力	キュー
42、#42	その Issue
https://github.com/owner/repo/issues/42	その Issue。owner/repo を控えます（ステップ 1 を参照）
複数の番号／URL	指定された順のそれらの Issue
指定なし、または「all」／「the open issues」／「az összes issue」	現在のリポジトリのすべてのオープン Issue — バックログモードを参照

単一の Issue は、1 件だけのキューです。どちらの場合も、以下のルールが適用されます。

1 Issue、1 コミット、1 PR

各 Issue は、最初から最後まで独立した作業単位です。それぞれに独自の実装、レビュー、コミット、ブランチ、プルリクエストがあります。1 つの文で 5 件の Issue が指定された場合も、バックログから 15 件見つかった場合も、それぞれ 5 回（または 15 回）このワークフローを実行します。すべてを 1 回の実行で扱うわけではありません。

プルリクエストは、レビュー、議論、リバートが行われ、Issue に紐付けられる単位です。3 件の Issue をクローズする PR は、個別にレビューしたりリバートしたりできず、そのうち 1 件だけに関心があるレビュアーにも、3 件すべてを読むことを強います。実装を混在させるのはさらに悪い方法です。2 件の Issue の編集が作業ツリーに混ざると、差分を手作業で分解しなければ、クリーンなコミットに分けられなくなります。

そのため、キューに複数の Issue がある場合は、次の手順に従います。

1. コードに触れる前に、キューと順序をユーザーに確認します。

I'll do these one at a time, each with its own commit and PR:
1. #12 — <title>
2. #13 — <title>
3. #14 — <title>

Starting with #12. Order OK?

ある Issue が別の Issue を前提としている場合は、その旨を伝えて順序を提案します。それ以外の場合は、指定された順序を維持します（バックログモードには、以下に独自のデフォルト順があります）。

2. 最初の Issue のみ、ステップ 1〜6 を実行します。
3. 停止して、ユーザーがレビューし、取り込むのを待ちます（github-commit-pr --issue <N> は、その Issue 1 件について、コミット → ブランチ → PR を処理します。--issue により、ステージング対象と Closes #N の範囲がこの Issue だけに限定されます）。
4. その Issue の変更が作業ツリーからなくなってから（コミット済み、またはユーザーが明示的に退避済み）、次の Issue のステップ 1 を開始します。

キューに含めるのは番号とタイトルだけです。それ以上の情報は含めません。すべての Issue の本文を取得してまとめて計画してはいけません。現在の Issue だけに集中することで、差分をクリーンに保ち、レビューしやすくできます。

バックログモード（Issue の指定なし）

Issue が指定されていない場合、ユーザーはリポジトリのオープン Issue に順番に取り組むことを望んでいます。本文ではなく、タイトルとメタデータのみを一覧表示します。

gh issue list --state open --limit 200 \
  --json number,title,labels,assignees,createdAt,blockedBy,closedByPullRequestsReferences

（--limit のデフォルトは 30 で、バックログがそれより多い場合は通知なく切り捨てられます。ちょうど 200 件返ってきた場合は、一覧が不完全な可能性があると伝えてください。）

この一覧からキューを作成します。

• 順序： 番号の昇順（古いものから）とします。ただし、ある Issue の blockedBy に記載されている Issue は、その Issue より先に処理します。また、バグのラベルが付いている Issue や、明示的な優先度ラベルが付いている Issue は前倒しできます。順序を変更する場合は理由を伝えてください。
• 次の Issue は黙って除外せず、保留にして、ユーザーが後から戻せるよう別の一覧に表示します。
  • 紐付けられた PR がすでにある Issue（closedByPullRequestsReferences が空でないもの）— 担当者がすでに作業中です。
  • 現在のユーザー以外に割り当てられている Issue（gh api user --jq .login）。
  • 実装作業ではない Issue — question、discussion、duplicate、wontfix、invalid のようなラベルが付いているもの、またはサブ Issue も一覧に含まれているエピック／トラッキング Issue。
• 残りがなければ、その旨を伝えて停止します。キューが長い（約 10 件を超える）場合は、すべて表示したうえで、各項目にレビューのラウンドが必要になるため、ユーザーに件数を絞るか、対象のラベル／マイルストーンを選ぶことを提案します。

次に、両方の一覧を提示し、Issue が指定された場合と同様に確認を求めます。

14 open issues. Queue (one commit + PR each):
1. #3  — <title>   [bug]
2. #5  — <title>
3. #9  — <title>   (blocks #11)
...
Set aside: #7 (open PR #40), #8 (assigned to @alice), #10 (question)

Starting with #3. Order OK?

以降は通常の 1 件ずつのループです。次の Issue を始める前に、オープン Issue を再度一覧表示します。その間に Issue がクローズされたり、誰かが対応を始めたりしている可能性があります。

前提条件

1. ツールとリポジトリ：

command -v gh && gh auth status && git rev-parse --show-toplevel

gh が見つからない場合は https://cli.github.com を案内してください。認証されていない場合は、ユーザーに gh auth login の実行を依頼してください。Git リポジトリ内にいない場合は、明確なメッセージを表示して中止してください。

2. クリーンな開始状態：

git status --porcelain

未コミットの変更があっても、自動的に問題になるわけではありません。ただし、それが前のイシューの作業である場合、その上に次のイシューの作業を始めると、2 つのイシューが 1 つのコミットに含まれることになります。作業ツリーに変更がある場合は、内容をユーザーに示し、先にコミットする（その作業が属するイシューに対して github-commit-pr --issue <N> を使う）、スタッシュする、または意図的に続行するかを確認してください。

ワークフロー

一度に1 つのイシューについて、以下の手順を実行してください。

ステップ 1：イシューを取得する

キューの先頭にあるイシューを取得します。URL の場合は番号と owner/repo を抽出します。リポジトリが現在のものと異なる場合はユーザーに警告し、続行するか確認してください（実装は現在のリポジトリで行い、イシューのコンテキストは別のリポジトリから取得します）。

gh issue view "$ISSUE_NUMBER" ${ISSUE_REPO:+--repo "$ISSUE_REPO"} --json number,title,body,labels,assignees,milestone,state,comments

ISSUE_REPO は、URL が別のリポジトリを指している場合にのみ owner/repo に設定されます。それ以外の場合、gh は現在のリポジトリをデフォルトとして使用します。コマンドが失敗した場合（見つからない、権限がないなど）は、エラーを報告してください。キュー内のイシューであれば次のイシューにスキップするか確認し、それ以外の場合は停止してください。

イシューがすでにクローズされている場合は、ユーザーに警告し、確認を得た場合にのみ続行してください。

コメントも含めて概要を示してください。コメントには、説明の補足、決定事項、変更された要件が記載されていることがよくあります。

Issue #42: <title>
State: open | Labels: enhancement
---
<issue body, trimmed to key requirements>
<key points from comments, if any>

ステップ 2：要件を把握する

本文とコメントから、以下を抽出します。

• 変更が必要な内容 — 機能、修正、または改善
• 受け入れ条件 — チェックボックスまたは明示された要件
• 対象範囲の境界 — 対象外の内容（記載がある場合）
• 関連するコンテキスト — 関連するイシュー、言及されたファイル、参照されている PR

コメントと本文の内容が矛盾する場合は、最新の合意済みコメントを優先します。イシューが不明瞭、または重要な詳細が不足している場合は、作業を進める前に確認してください。

ステップ 3：進め方を計画する

コードを書く前に、次のことを行ってください。

1. プロジェクトの規約を確認します — README.md、CLAUDE.md、AGENTS.md、CONTRIBUTING.md などのドキュメント、設定ファイル、変更箇所周辺の既存コードを確認してください。
2. 作成または変更が必要なファイルを特定します。
3. 影響を受けるコードを対象とする既存のテストを確認します — 変更によってカバレッジを拡充し、既存のテストを壊さないようにしてください。
4. 簡潔な計画を提示します。

Implementation plan for #42:
1. <specific change>
2. <specific change>
3. <specific change>

計画からイシューの規模が想定より大きいとわかった場合は、その旨を伝えて分割を提案してください。ユーザーが計画を承認または調整するまで待ってください。

ステップ 4：実装する

• ステップ 3 で確認した規約に従ってください。
• 最初の説明だけでなく、最新のコメントスレッドで合意された内容を実装してください。
• イシューで必要とされる変更だけを行ってください。プロジェクトで i18n を使用している場合は、ユーザーに表示される新しい文字列の翻訳キーを追加してください。
• サブタスクが計画より複雑だとわかった場合は、対象範囲を黙って広げず、いったん止めてユーザーに伝えてください。
• キュー内の別のイシューに属する内容には手を触れないでください。修正まであと 1 行で、10 分後には戻ってくるとしても同じです。その行は別のイシューのコミットに含めるべきです。そうすれば、レビュー担当者はその変更と、それを求めたイシューを関連付けられます。メモを残して先に進んでください。

Step 5: 検証する

プロジェクト独自のチェックを実行します。CI で実行されるもの（.github/workflows/、.gitlab-ci.yml、Jenkinsfile、.circleci/）や、package.json のスクリプト、Makefile、プロジェクトのドキュメントに記載されているものを優先してください。PR が通過する必要があるのは、そうしたチェックです。スタックごとの一般的なコマンドは次のとおりです。

• TypeScript/JavaScript: npx tsc --noEmit、npm test、npm run lint
• Rust: cargo check、cargo test
• Python: python -m pytest、mypy .、ruff check .
• Go: go build ./...、go test ./...
• Android (Kotlin/Java): ./gradlew build、./gradlew test、./gradlew lint
• Flutter/Dart: flutter analyze、flutter test
• Swift: swift build、swift test
• Ruby: bundle exec rspec、bundle exec rubocop
• .NET (C#/F#): dotnet build、dotnet test
• Elixir: mix compile --warnings-as-errors、mix test、mix credo

最低限、コンパイラー／型チェッカーと、変更に関係するテストを実行し、報告する前に失敗を修正してください。出力が長い場合は、ログ全体を貼り付けるのではなく、関連する行に絞り込んでください。検証コマンドが存在しない場合は、その旨を伝え、手動での確認方法を提案してください。

Step 6: 報告して停止する

Done — Issue #<number>: <title>

Files modified:
- <path> (new)
- <path> (modified)

Verification:
- Type check: clean
- Tests: passed

Ready for review.

さらに対応待ちの課題がある場合は、残っている内容と、その前に必要な作業を最後に示します。

Remaining: #13, #14.
Next step for #12: review, then commit + PR (github-commit-pr --issue 12).
I'll start #13 once #12 is committed.

ここで停止してください。 コミット、プッシュ、ブランチの作成、PR の作成はしないでください。次に何をするかはユーザーが決めます。ユーザーが変更を公開したい場合は、github-commit-pr --issue <N> が、その課題だけを対象にコミット → ブランチ → PR を実行し、Closes #N を付与します。課題を指定すると、作業ツリーにほかの変更がある場合に、このスキルがステージするパスを判断できます。

Step 7: 次の課題に進む

現在の課題がマージされた後（またはユーザーが明示的に保留した後）、git status --porcelain を再確認します。変更が残っている場合、前の課題は実際には完了していません。その後、キューから次の課題を取り出し、Step 1 に戻ります。バックログモードでは、まず未完了の課題を再度一覧表示し、その間にクローズされたものや、ほかの人が着手したものを除外します。

前の課題がまだ未コミットの状態で、ユーザーが次の課題への着手を求めた場合は、2 つの差分が混在し、手作業でしか分離できなくなることをはっきり伝え、先に現在の作業をコミットすることを提案してください。それでも続行したい場合は、ユーザーの判断に従って進め、生成されるコミットが両方の課題にまたがることを一度だけ警告してください。

エラー処理

シナリオ	検出方法	対応
gh がインストールされていない／ログインしていない	command -v gh／gh auth status が失敗する	https://cli.github.com または gh auth login を案内する
Git リポジトリ内にいない	git rev-parse が失敗する	明確なメッセージを表示して中止する
課題が見つからない／アクセス権がない	gh issue view が 0 以外を返す、403/404	報告する。キュー内の場合はスキップを提案する
課題がすでにクローズされている	state が CLOSED	警告し、確認後にのみ続行する
別のリポジトリの課題	URL が現在のリポジトリと一致しない	警告し、続行するか確認する
複数の課題、または課題の指定なし	キューに 2 件以上ある	キューと順序を確認し、最初の課題だけを実装する
未完了の課題がない	gh issue list が [] を返す	その旨を伝えて停止する
前の課題による作業ツリーの変更	git status --porcelain が空でない	変更を表示し、先にコミット／スタッシュすることを提案する
スコープが想定より大きい	計画／実装中に判明する	一時停止し、ユーザーに伝えて分割を提案する
検証ツールが見つからない	コマンドを利用できない	ユーザーに伝え、手動での検証を提案する

重要な制約

このスキルが担当するのは実装フェーズのみです。Git のワークフローはユーザーが管理します。

• 2 つの issue の変更を同じコミットやプルリクエストに含めないでください。また、現在の issue の変更が作業ツリーからなくなるまで、次にキューに入っている issue に着手しないでください。
• コミット、プッシュ、ブランチの作成、プルリクエストの作成は行わないでください。ユーザーが先にレビューし、独自のブランチ戦略を採用している場合があります。変更をリリースする手順は github-commit-pr が担当します。
• issue のスコープ外のファイルは変更しないでください。スコープの逸脱により、変更のレビューや差し戻しが難しくなります。
• 要件が曖昧な場合は推測せず、質問してください。誤った推測をするより、すぐに質問するほうがコストを抑えられます。