github-issues

github-issues

目的

あらゆるプロジェクトで、GitHub の issue の作成と管理を標準化します。すべての issue が明確な構成を持ち、適切なラベルが付けられ、実行可能な内容になるようにします。適切な形式の issue の作成と、GitHub のデフォルトのラベル分類体系の一貫した適用をユーザーに案内します。

前提条件

操作を行う前に、環境を確認してください。

1. gh がインストールされ、認証済みであることを確認します — gh auth status。認証されていない場合は処理を中止し、ユーザーに gh auth login を案内してください。後続の手順はどれも失敗するためです。

2. リポジトリのコンテキストを検出します：

gh repo view --json nameWithOwner --jq .nameWithOwner

結果を REPO="owner/repo" として保存します。gh がリモートを自動で解決します（SSH または HTTPS、フォークでは設定済みのベースリポジトリ）。解決に失敗した場合（Git リポジトリではない、または GitHub リモートがない場合）は、ユーザーに owner/repo を尋ねてください。

これらは、gh issue または gh label コマンドを実行する前に行い、常に正しいリポジトリを対象にするため、各コマンドに -R "$REPO" を渡してください。これにより、現在のディレクトリに左右されません。

使用する場面

• 重複を事前に確認したうえでの新しい GitHub issue の作成（すでに要望を網羅する issue がある場合は、既存の issue を更新します）
• 監査またはレビューのレポートファイルからの issue の一括登録
• issue の詳細の表示
• 説明を添えた issue のクローズ
• 既存の issue へのコメント
• 既存の issue のトリアージまたはラベル付け
• ラベル付きのオープンな issue の一覧表示

詳細なリファレンス

必要に応じて読み込んでください。最初からすべてを読む必要はありません。

• references/issue-templates.md — タイトルのルール、機能改善およびバグ報告の本文テンプレート、本文セクションのルール、タイトルやコンテキストに基づく種類の判定について説明します。issue の本文を作成または書き直す前に読んでください。
• references/labels.md — 種類・ステータスのラベル分類体系、適用前にラベルの存在を確認する方法、--add-label と --label の使い分けについて説明します。ラベルを適用または変更する前に読んでください。
• references/audit-import.md — 監査／レビューのレポートを issue に変換する方法について説明します。指摘事項の解析、カテゴリからラベルへのマッピング、指摘事項ごとの重複確認、一括レビュー用の表、レポートを削除するか確認する最後の質問が含まれます。from-audit を使う場合に読んでください。

操作

$ARGUMENTS に基づき、次の操作のうち1つを実行してください。レポートファイルから issue を登録する依頼（「監査の指摘事項の issue を作成して」、「csinálj issue-kat az audit alapján」、またはコードアナライザーの監査後にオプション2を選択する場合）は、ユーザーが「作成」と言った場合でも from-audit を使用してください。

create <title>

1. タイトルとコンテキストから課題の種類を判断します。references/issue-templates.md の種類判定の指標を参照してください。
2. 何かを作成する前に、同じ内容を扱う既存の課題がないか確認します。 すでに課題がある問題について二つ目の課題を登録すると、議論が分散し、トリアージの労力も無駄になるため、必ず最初に検索してください。タイトルから特徴的なキーワードを抜き出し（「add」／「fix」などの一般的な動詞やストップワードは除外）、オープンとクローズの両方の課題を検索します。

gh issue list -R "$REPO" --search "<keywords>" --state all --json number,title,state,url,updatedAt --limit 20

候補を確認し、単にキーワードが重複しているだけではなく、同じ根本的な要望またはバグを説明しているものがあるか判断します。同じファイルに関係していても、求めていることが異なる二つの課題は重複ではありません。一方、表現が異なっていても、同じ変更で解決する二つの課題は重複です。判断に迷う場合は、推測するのではなく、最も近い候補を一致する可能性のある課題として扱い、ユーザーに判断してもらいます。

• 一致するものがない場合： ステップ3に進み、新しい課題を作成します。
• 一致するオープン課題がある場合： 重複する課題は作成しません。既存の課題を開き（gh issue view <number> -R "$REPO"）、本文と新しい詳細情報を比較します。新しい情報が実質的に追加される場合（再現手順の追加、課題に記載されていない影響ファイル、より明確な解決策の提案、新しいコンテキストなど）は、既存の課題を更新します。ステップ6bを参照してください。既存の課題で内容がすべて網羅されている場合は、すでに登録済みであることをリンクとともにユーザーに伝え、何も変更せずに終了します。
• 一致するクローズ済みの課題がある場合： リンクとステータスをユーザーに提示します。問題が再発した場合は再オープンするか、新しいコンテキストをコメントとして追加するか、新しい課題を登録するか（例：以前の課題とは根本原因が異なる場合）を尋ねます。黙って再オープンしないでください。

3. 対象リポジトリで利用可能なラベルを確認し、種類のラベルがない場合は対応します。references/labels.md に従ってください。
4. references/issue-templates.md から該当する本文テンプレート（機能拡張またはバグ）を選び、コンテキストに基づいて「Summary」セクションを事前に記入します。ユーザーから十分な詳細が提供されている場合は、該当するすべてのセクションを記入します。それ以外の場合は、不足している必須セクションを尋ねます。特に、具体的なファイルパスと実装方法を含む「Proposed Solution」が必要です。
5. 種類の判断とステップ3で確認した利用可能なラベルに基づき、適切なラベルを提案します。
6. 作成前に、課題全体（タイトル、本文、ラベル）をユーザーに提示して確認してもらいます。 確認または修正を待ちます。
7. 課題を作成します。

gh issue create -R "$REPO" --title "<title>" --label "<label1>,<label2>" --body "$(cat <<'EOF'
<body content>
EOF
)"

8. 課題の URL を出力します。

ステップ6b：作成せずに既存の課題を更新する

ステップ2で一致するオープン課題が見つかり、新しい依頼によって得られる情報が不足している場合にのみ実行します。目的は、すでにある内容を損なわずに既存の課題を充実させることです。本文には、編集内容、議論への参照、ユーザーが手動で追加した詳細が含まれている可能性があります。

1. 実際に変更が必要な内容を判断します。再現手順の追加、リンク、新たに特定された原因など、小規模な追加であれば、コメントが最も破壊的でなく、変更履歴も残せます。

gh issue comment <number> -R "$REPO" --body "$(cat <<'EOF'
<the new information, e.g. additional repro steps or an affected file>
EOF
)"

2. 課題の構造化された本文に実質的な不足があり（「Proposed Solution」がない、「Summary」が不適切または空など）、書き直すことで課題がわかりやすくなる場合は、本文を編集します。ただし、まずユーザーに変更後の本文案を提示し、既存の内容を丸ごと置き換えるのではなく、既存の内容と統合してください。

gh issue edit <number> -R "$REPO" --body "$(cat <<'EOF'
<merged body — existing content plus the new details>
EOF
)"

3. 新しいコンテキストによって分類が変わる場合（例：機能拡張ではなくバグだと判明した場合）は、--add-label で適切なラベルを追加します。既存のラベルをすべて消去してしまう --label は決して使用しないでください。
4. 課題の URL と、変更内容を一行で簡潔に説明したメモを出力します。

from-audit [<file>] [<ids or severities>]

監査またはレビュー報告書の指摘事項から、イシューを一括作成します。手順全体については、references/audit-import.md に従ってください。概要は次のとおりです。

1. 報告書を特定します（指定されたパス、またはリポジトリのルートにある最新の CODE_AUDIT_*.md。複数ある場合は、どれを使うか確認します）。すべての指摘事項を解析します。
2. 対象範囲を確定します。ユーザーが指定した ID または重大度を使い、指定がなければ Critical + High を提案して確認します。
3. 指摘事項ごとに create のステップ 2 の重複チェックを実行し、利用可能なラベルを一度だけ確認します。
4. テンプレートからすべてのイシューの下書きを作成し、各本文を単独で内容が完結するようにします（報告書は後で削除される可能性があります）。
5. バッチ全体について、指摘事項 ID、提案するタイトル、ラベル、アクション（create / update #N / skip）を記載したレビュー表を1つ提示し、確認を待ちます。
6. 確認済みのイシューを作成または更新し、指摘事項 → イシュー URL の表を提示します。
7. **監査ファイルを削除するかどうかを尋ねます。**自分の判断で削除してはいけません。ユーザーの回答前に伝える内容については、リファレンスを参照してください。

view <number>

1. イシューの詳細を表示します。

gh issue view <number> -R "$REPO"

2. ユーザーがディスカッションの表示を希望する場合は、コメントを表示します。

gh issue view <number> -R "$REPO" --comments

close <number> [reason]

1. イシューを取得して状態を確認します。

gh issue view <number> -R "$REPO" --json title,labels,state

2. イシューがすでにクローズされている場合は、ユーザーに伝えて終了します。
3. 重複としてクローズする場合は、ユーザーに元のイシュー番号を指定してもらいます。元のイシューが存在することを確認してから、GitHub 標準の重複理由を使ってクローズします。これにより、イシューのタイムラインにリンクが記録されます。

gh issue view <original> -R "$REPO" --json number,title,state
gh issue close <number> -R "$REPO" --duplicate-of <original> --comment "Closing as duplicate of #<original>."

リポジトリに duplicate ラベルがある場合は、それも追加します（gh issue edit <number> -R "$REPO" --add-label "duplicate"）。ラベルがない場合はスキップします。クローズ理由にすでに意味が含まれているためです。--duplicate-of に対応していない古い gh（"unknown flag" で失敗する場合）では、--reason "not planned" とコメントを使います。

4. それ以外のクローズの場合は、理由を説明するコメントを添えてクローズし、理由を選びます。完了・修正済みの場合は completed、修正しない・無効・古くなった場合は not planned を使います。

gh issue close <number> -R "$REPO" --reason "<completed|not planned>" --comment "<reason>"

5. 引数にユーザーが理由を指定している場合は、それを使います。指定がない場合は、クローズ前に理由を尋ねます。理由を確認せずにクローズしてはいけません。

comment <number> <text>

1. イシューが存在することを確認します。

gh issue view <number> -R "$REPO" --json number,title,state

2. コメントを追加します。

gh issue comment <number> -R "$REPO" --body "<text>"

3. リンクを添えて、コメントが投稿されたことを確認します。

assign <number> <user> [--remove]

1. イシューが存在することを確認します。

gh issue view <number> -R "$REPO" --json number,title,state,assignees

2. --remove が指定されていない場合は、ユーザーを割り当てます。

gh issue edit <number> -R "$REPO" --add-assignee "<user>"

--remove が指定されている場合は、割り当てを解除します。

gh issue edit <number> -R "$REPO" --remove-assignee "<user>"

3. <user> が @me または me の場合は、認証済みユーザーに置き換えます。

gh api user --jq '.login'

4. 割り当ての変更を確認します。

label <number> <label> [--remove]

1. 利用可能なラベルを取得し、指定されたラベルが存在することを確認します。

gh label list -R "$REPO" --json name --jq '.[].name'

2. --add-label / --remove-label を使ってラベルを追加または削除します。正確なコマンドと、gh issue edit で --label を決して使ってはいけない理由については、references/labels.md を参照してください。
3. ラベルが存在しない場合はユーザーに警告し、利用可能なラベルを一覧表示します。可能であれば、最も近い候補を提案します。

triage

1. すべてのオープンイシューをラベルとともに一覧表示します。

gh issue list -R "$REPO" --state open --json number,title,body,labels,createdAt --limit 100

2. labels が空のイシューに絞り込みます。
3. ラベルなしのイシューが見つからない場合は、「オープンイシューにはすべてラベルが付いています」とユーザーに伝えて終了します。
4. ラベルなしの各イシューのタイトルと本文を分析し、references/issue-templates.md の種類判定の指標と、references/labels.md の分類体系を使ってラベルを提案します。
5. 提案するラベルをまとめた表を提示します。

#   Title                                    Suggested Label
37  Add database corruption recovery         enhancement
33  Fix error state on successful ops        bug
30  Update API documentation                 documentation

6. 提案を適用する前に、それぞれについて確認、変更、またはスキップするかをユーザーに尋ねます。
7. 確認済みのラベルを適用します。

gh issue edit <number> -R "$REPO" --add-label "<label>"

list（引数が指定されていない場合のデフォルト）

1. オープンなイシューを一覧表示します。

gh issue list -R "$REPO" --state open --json number,title,labels,assignees --limit 50

引数に --label <label> が指定されている場合は、絞り込みのために --label "<label>" を追加します。

2. 読みやすい表形式で表示します。

#   Title                                    Labels              Assignee
12  Add dark mode toggle                     enhancement         @user
11  App crashes on startup with empty DB     bug, good first     —
10  Update README with build instructions    documentation       @user

3. 合計件数とラベルの内訳を要約して表示します。
4. 表示上限を超える数のイシューがある場合は、その旨をユーザーに伝え、--label で絞り込むか、上限を増やすよう提案します。

エラー処理

状況	検出方法	対応
gh がインストールされていない	command -v gh が失敗する	https://cli.github.com を案内します
gh が認証されていない	gh auth status が失敗する	gh auth login を実行するようユーザーに依頼します
Git リポジトリ内にいない	git rev-parse --show-toplevel が失敗する	owner/repo を手動で指定するようユーザーに依頼します
リモートが設定されていない	git remote get-url origin が失敗する	owner/repo を手動で指定するようユーザーに依頼します
イシューが見つからない	gh issue view がゼロ以外の終了コードを返す	イシュー番号とリポジトリを確認します
ラベルが見つからない	gh label list の出力にラベルがない	利用可能なラベルを表示し、最も近いものを提案します
アクセスが拒否された	gh が 403/404 を返す	リポジトリへのアクセス権と認証スコープを確認します
レート制限	gh が 429 を返す、または「secondary rate limit」に言及する 403 を返す（短時間に多数のイシューを連続して作成する場合によく発生します）	一時停止してから一度だけ再試行します。一括処理の場合は、まだ作成されていない項目を報告します

制約

次のルールに従うことで、イシューの品質を高め、既存のラベルやイシューへの誤った変更を防ぎます。

• 新しいイシューを作成する前に既存のイシューを検索し、重複して登録するのではなく、そのイシューを更新します。重複したイシューは議論を分散させ、トリアージの負担を倍増させます。
• すべてのイシューに少なくとも 1 つのタイプラベルが必要です。ラベルは主要な分類手段であり、絞り込みとトリアージを可能にします。
• 作成前に、イシュー全体（タイトル、本文、ラベル）をユーザーに提示して確認してもらいます。最終的な内容を決めるのはユーザーです。
• イシューをクローズする前に、その理由を説明するコメントを追加します。後から読む人が判断の背景を理解できるようにする必要があります。
• イシューを重複としてクローズする前に、元のイシューへのリンクを追加します。これにより、GitHub の UI で関連性が保持されます。
• イシューの編集時には --label ではなく --add-label を使用します。--label は既存のラベルをすべて置き換えるため、重要な分類が気付かないうちに削除される可能性があります。
• ユーザーの確認なしに新しいラベルを作成しないでください。ラベルはリポジトリ全体で共有され、全員のワークフローに影響します。
• 状況が把握できる場合は、イシューの本文に具体的なファイルパスとコードへの参照を含めます。具体的な手掛かりのある、対応可能なイシューはより早く解決されます。
• ユーザーから明示的に許可されない限り、ソースレポート（監査ファイル）を削除してはいけません。未登録の調査結果が含まれている可能性があります。