【GitHub基礎】コードを書く前にIssueを立てる理由――作業の迷子を防ぐ課題管理

READMEに原稿の保存場所が書かれていない。記事のリンクが開かない。新しい説明を追加したいけれど、どこまで対応するかを相談したい。

こうした気づきを、作業につながる形で記録するのがGitHubのIssueです。チャットで話して終わりにせず、課題の内容、判断、対応状況を1か所で追いかけられます。

この記事では、課題を書くときの考え方、担当や分類、Pull Requestとの関連付け、完了の確認までを説明します。READMEの修正とIssue番号は説明用の例です。GitHub公式資料に基づく入門記事として整理しました。

1. Issueは、課題や作業を記録して話し合う場所

Issueは、バグ報告だけでなく、機能の提案、改善、作業の計画などを記録できます。タイトルと本文で内容を示し、コメントで相談や確認を進めます。GitHub公式：Issueについて

たとえば、記事原稿を管理するリポジトリなら、次のように使えます。

これらは、この記事で考えた使い方の例です。最初から解決方法が決まっていなくても、確認できたことと、まだ決まっていないことを分けて記録できます。

Issueを作成すること自体は、ファイルの変更ではありません。課題を記録した後、必要な修正をブランチで進めます。

2. IssueとPull Requestの違い

前回の記事で扱ったPull Requestと、役割を分けて考えましょう。

この記事の例では、Issueで「何を解決するか」を整理し、PRで「どの変更で解決するか」を確認します。PRには差分があり、Issueには課題や相談の経緯があります。

すべてのPRに、必ず別のIssueが必要なわけではありません。小さな修正ならPRの説明で十分な場合もあります。チームで、Issueを作る範囲と記録の粒度を合わせておくと整理しやすくなります。

幅広い質問や情報交換にはGitHub Discussionsが向く場合もあります。IssueとDiscussionsの使い分けも、プロジェクトの運用に合わせます。GitHub公式：IssueとDiscussions

3. 相手が判断できる内容を書く

「READMEを直す」だけでは、どの説明が足りず、どこまで対応すればよいかが伝わりません。

この記事のREADME修正なら、次の項目を分けると相談しやすくなります。

次は、説明用のIssue本文です。実際に使う場合は、調べた事実に合わせて書き換えてください。

タイトル：READMEに記事原稿の保存場所を追加する

## 現在の状態
READMEには、記事原稿を置くフォルダーの説明がありません。

## 困っていること
初めて作業する人が、原稿をどこへ保存するか判断できません。

## 期待する状態
READMEを読めば、記事原稿の保存場所がわかるようにします。

## 完了の条件
- 記事原稿はarticlesフォルダーへ保存することが書かれている。
- フォルダー名が実際の構成と一致している。
- 前後の説明に矛盾がない。

## 相談したいこと
画像の保存場所も、同じ箇所で説明するかを相談したいです。

不具合の報告なら、再現手順、使った環境、期待した結果、実際の結果も添えると確認しやすくなります。推測した原因は、確認済みの事実と分けて書きます。

4. GitHubでIssueを作る

まず、同じ課題がすでに登録されていないかを確認します。既存のIssueで話し合える内容なら、調べた結果や補足をそこへ追加する方法もあります。

新しく作る場合は、目的のリポジトリを開き、「Issues」から「New issue」を選びます。テンプレートや入力フォームが用意されている場合は、その案内に沿ってタイトルと本文を入力します。GitHub公式：Issueの作成

入力したら、次を見直して作成します。

1. 記録先のリポジトリが合っているか。
2. タイトルだけでも課題の対象がわかるか。
3. 事実、希望、未確認のことが区別されているか。
4. 完了を判断する条件があるか。

Issueが無効になっているリポジトリでは、作成できません。また、担当や分類を設定できる範囲は権限によって異なります。

公開リポジトリへ書く本文や画像は、外部の人にも読まれる前提で確認します。業務の課題を記録する場合は、公開範囲に合った内容にしましょう。

5. 担当・ラベル・マイルストーンで整理する

Issueを増やすだけでは、誰が何を進めるかが見えにくくなります。必要に応じて、次の情報を付けます。

担当の設定は、誰が対応しているかを伝えるために使えます。設定できる相手や操作権限には条件があります。GitHub公式：担当者の設定

ラベルは、IssueやPRを分類するための名前です。たとえばbugやdocumentationなどを使えますが、名称と意味はリポジトリのルールを確認します。GitHub公式：ラベルの管理

マイルストーンは、関連するIssueやPRの進捗をまとめて追跡するために使います。説明や期限を設定することもできます。GitHub公式：マイルストーンについて

担当が付いたことや、分類されたことだけで、作業が完了したわけではありません。コメントには、確認した結果、決まった方針、残っている点を記録します。

6. IssueとPRを関連付ける

課題を整理したら、修正用ブランチで作業し、コミット・push・PRの作成へ進みます。IssueとPRを関連付けると、課題に対してどの変更が提案されているかを追いかけられます。

説明用のIssue番号を#12とすると、同じリポジトリのPR本文に、次のような記載ができます。

関連する課題：#12

番号を参照することで、読み手が課題の説明へたどれます。ただし、単に番号を記載したことと、自動でIssueを閉じる指定は別です。

今回のPRで課題全体が解決するなら、PR本文に次のような終了用キーワードを使えます。

Closes #12

このキーワードによる関連付けと自動終了は、PRがリポジトリのデフォルトブランチを対象にしていることが条件です。対象のPRがそこへマージされると、関連するIssueが自動で閉じられます。PRを作っただけでは閉じられません。GitHub公式：PRとIssueの関連付け

一部だけを対応するPRなら、残る課題があるのに自動終了する指定を付けないようにしましょう。「この変更で何が終わり、何が残るか」を本文で伝えます。

7. 完了の条件を確認して、Issueを閉じる

READMEの変更が取り込まれたら、Issueに書いた条件を見直します。この例なら、保存場所の説明、実際のフォルダー名との一致、前後の文章を確認します。

手動で閉じる場合は、確認結果や判断理由をコメントに残すと、あとから経緯を追いやすくなります。

GitHubでは、対応が完了した場合に加え、対応しないと判断した場合にもIssueを閉じられます。Closedは、すべて「修正済み」という意味ではありません。終了理由とコメントを合わせて読みます。GitHub公式：Issueを閉じる

また、Issueを閉じることは、記録を削除することではありません。課題の説明や、相談した経緯を参照できるように残します。

作業が大きくなった場合は、完了条件を整理し、別の課題へ分けることも考えます。相談しただけで終わらず、対応すること、見送ること、まだ判断が必要なことを区別しましょう。

8. まとめと理解度確認

Issueは、課題を記録して、相談と対応を追跡するための仕組みです。何に困っているか、どの状態を目指すか、何を確認したら終えられるかを、相手が判断できる形で書きます。

修正が必要ならPRと結び付け、レビューと取り込みへ進みます。最後に完了の条件を確認し、結果や判断を残して閉じる、という流れで使いましょう。

自分の言葉で説明してみる

1. Issueは、バグ報告だけに使うものですか？
2. IssueとPRは、主な役割がどう違いますか？
3. 課題に完了の条件を書くと、どんな判断がしやすくなりますか？
4. PR本文にCloses #12と書けば、PRの作成直後にIssueが閉じますか？
5. ClosedになっているIssueは、必ず修正済みですか？

解答例

1. バグだけではありません。改善、提案、作業の計画などにも使えます。
2. Issueは課題と対応の追跡、PRは具体的な変更の提案とレビューに使います。
3. 何を確認すれば対応を終えられるかがわかり、作業範囲と完了を判断しやすくなります。
4. 閉じません。このキーワードを使ったPRがデフォルトブランチを対象とし、そこへマージされることが条件です。
5. 必ずではありません。対応しない判断で閉じる場合もあるため、理由やコメントを確認します。

参考資料

• GitHub公式：Issueについて
• GitHub公式：Issueの作成
• GitHub公式：担当者の設定
• GitHub公式：ラベルの管理
• GitHub公式：マイルストーンについて
• GitHub公式：PRとIssueの関連付け
• GitHub公式：Issueを閉じる

資料確認日：2026年10月11日