前回は、プルリクエストで修正案を出し、確かめてから取り込む流れを体験しました。最後に「次回はIssue」と予告していたので、今回はそのIssue（イシュー）を使います。
仕事にたとえると、Issueは依頼票です。課題管理表の1行と言ってもかまいません。「ここを直してほしい」「こういうものを作りたい」という依頼を、1件ずつ番号を付けて記録しておく場所です。
依頼は、記録しておかないとすぐに散らばります。第1回の佐藤さんの場面を思い出してください。修正の依頼はチャットに、補足はメールに、確認結果は佐藤さんの記憶の中にありました。今回は、その「依頼」の部分をGitHubの中に置いてみます。
Issueに書くもの
Issueには、仕事として片付けたいことを何でも書けます1。直したいところ、追加したいもの、思いついたアイデア、誰かに相談したいこと。どれも1件のIssueになります。
Issueを立てると、「#1」「#2」のような番号が自動で付きます。この番号が、あとで依頼と修正をつなぐ鍵になります。
書くときのコツは、1つのIssueに1つの依頼だけを書くことです。「READMEを直す」のように大きくまとめると、どこまでやれば済んだのかが分からなくなります。「READMEに問い合わせ先を書く」のように、終わりが見える単位に分けておくと、片付いたかどうかがはっきりします。
Issueには、Open（対応中）とClosed（対応済み）の2つの状態があります。対応が済んだIssueは閉じますが、消えるわけではありません。どんな依頼があり、どう片付いたのかは、あとからいつでもたどれます。
Issueを立てる
第3回から使っている work-notes リポジトリで試します。READMEに「問い合わせ先」を書き足してほしい、という依頼を記録してみましょう。
リポジトリの上に並ぶタブから「Issues（イシュー）」を開き、緑の「New issue（新しいイシュー）」を押します2。タイトルと本文を書く画面が出ます。
タイトルは、何をしたいのかが一目で分かる短い文にします。
READMEに問い合わせ先を書く
本文には、なぜそれが必要なのかと、やることを書きます。
READMEを見た人が、誰に聞けばよいか分からない。
問い合わせ先を書いておけば、迷わずに済む。
- [ ] 担当部署を書く
- [ ] 連絡方法を書く
- [ ] で始まる行は、Issueの画面ではチェックボックスになります3。終わった項目にチェックを入れていけば、どこまで進んだのかが一目で分かります。ここでも、空行を1つ入れてから箇条書きを始めておくのが確実です。
書けたら、右下の緑の「Create（作成）」ボタンを押します2。
画像① タイトルには「何を」、本文には「なぜ」と、やることを書く
作成すると、タイトルの横に「#1」のような番号が付きます。本文のチェックボックスも、押せる形で表示されているはずです。
番号は、1から順に付くとは限りません。Issueとプルリクエストは、同じリポジトリの中で1つの通し番号を分け合っているからです。第4回の練習で work-notes にプルリクエストを1つ作っていれば、それが「#1」なので、今回のIssueは多くの場合「#2」になります。この先の手順では、表示された番号をそのまま使ってください。この記事の画像は、第4回の撮影でプルリクエストを2つ作ったリポジトリで撮っているため、番号が「#3」になっています。
画面の右側には、Assignees（担当者）やLabels（ラベル）といった欄が並んでいます。担当者を決めたり、「急ぎ」「質問」のような札を付けて分類したりするためのものです1。一人で使ううちは空欄のままで困りません。
画像② 番号が付き、やることがチェックボックスになっている
コメントで相談する
Issueの下には、コメント欄があります。依頼について相談したいことは、ここに書きます。
たとえば、問い合わせ先を個人の名前にするか、部署の名前にするか。担当者が替わるたびに書き直すのは手間なので、部署名にしよう、という結論になったとします。そのやり取りを、コメントとして残しておきます。
担当者が替わっても書き直さずに済むよう、個人名ではなく部署名にします。
書けたら、コメント欄の下にある「Comment（コメントする）」を押して投稿します。
画像③ 相談した内容と結論を、依頼と同じ場所に残す
メールやチャットで相談すると、依頼とは別の場所に結論が散らばります。Issueのコメントなら、依頼と相談と結論が、1つの画面に並んだままです。
同僚に意見を聞きたいときは、コメントに「@」に続けてその人のアカウント名を書きます。名前を呼ばれた人には、通知が届く仕組みです1。関係する別のIssueがあれば、「#」に続けて番号を書くだけで、そのIssueへのリンクになります。今回は一人で練習しているので、どちらも使わなくて構いません。リポジトリを複数人で使うようになったときに、思い出してください。
Issueとプルリクエストをつなぐ
依頼が固まったら、修正に取りかかります。やり方は第4回と同じです。READMEを編集し、2つ目の選択肢（新しいブランチを作って、プルリクエストを始める）で記録します。
READMEの最後に、空行を入れてから次の2行を書き足します。2行の間にも、空行を1つ入れてください。入れないと、Previewで1行につながって表示されることがあります。
問い合わせ先：営業企画部
連絡方法：社内チャットの営業企画部チャンネル
Issueのチェックリストに書いた「担当部署」と「連絡方法」が、これで両方そろいます。
違うのは、プルリクエストの説明欄の書き方です。何を変えたか、なぜ変えたかに加えて、次の1行を書きます。
Closes #1
#1 の部分は、さっき立てたIssueに付いた番号に置き換えてください。第4回の練習をしていれば、多くの場合は Closes #2 になります。「Closes」に続けてIssueの番号を書くと、このプルリクエストとIssueがつながります4。「このプルリクエストは、あの依頼を片付けるためのものです」という印です。
画像④ 説明欄に「Closes #番号」と書くと、プルリクエストとIssueがつながる
プルリクエストを作ってからIssueの画面に戻ると、つながったプルリクエストが3か所に表示されています。タイトルの下の「Open」の横、右側の「Development（開発）」欄、そしてコメントの流れの中の「linked a pull request that will close this issue（このIssueを閉じるプルリクエストがつながりました）」という記録です。依頼の側からも、どの修正案で対応しているのかが分かるわけです。
画像⑤ Issueの側からも、対応しているプルリクエストが見える
マージすると、Issueが自動で閉じる
修正案を確かめたら、マージする前に、Issueの本文のチェックボックスにもチェックを入れておきましょう。担当部署と連絡方法、どちらも書き足したはずです。依頼の側から見ても、やることが全部済んだと分かる状態になります。
それから、第4回と同じ手順でマージします。
マージが済んでからIssueを開いてみてください。状態が「Closed（対応済み）」に変わっています4。Issueを自分で閉じる操作はしていません。プルリクエストのマージに合わせて、GitHubが自動で閉じてくれました。コメントの流れの最後には「closed this as completed in #4」のように、どのプルリクエストで片付いたのかも記録されています。
画像⑥ マージに合わせて、Issueが自動で「Closed」になる
これで、依頼から取り込みまでが一本の記録でつながりました。
- Issue：何を頼み、なぜ必要で、どう相談したか
- プルリクエスト：どう直し、誰が確かめたか
- 履歴：いつ、本体に取り込まれたか
どこから見始めても、ほかの2つにたどり着けます。
Issueとプルリクエストの使い分け
IssueとプルリクエストはGitHubの画面上でよく似ていて、どちらにもタイトルと本文とコメント欄があります。迷ったら、次のように考えると整理しやすくなります。
- Issue：「何をしたいか」を書く場所。まだ直し方が決まっていなくても立てられる
- プルリクエスト：「こう直しました」を出す場所。中身は、具体的な変更（差分）
依頼が先、修正案が後、という順番です。小さな修正なら、Issueを立てずにいきなりプルリクエストを出しても問題はありません。ただ、「なぜ直すのか」を後から確かめたくなりそうな修正は、先にIssueを立てておくと、理由と相談の経緯が残ります。
つまずきやすいところ
「Closes #1」は、プルリクエストの説明欄に書いてください。キーワードがIssueを閉じるのは、プルリクエストがリポジトリの本体（main）に向けて出されているときだけです4。第4回の手順どおりに作ったプルリクエストなら、本体に向いているので心配はいりません。
「#」と数字は、半角で書いてください。全角の「＃１」では、Issueとつながりません。
「Closes」のほかに、「Fixes」や「Resolves」でも同じようにつながります4。どれを使っても構わないので、迷ったら「Closes」で統一するのがおすすめです。
コメントを入力している間は、「Comment」の隣のボタンが「Close with comment（コメントして閉じる）」に変わります。押すとコメントと同時にIssueが閉じてしまうので、相談を書き込むときは「Comment」のほうを押してください。間違えて閉じても、Issueの画面の「Reopen issue」で開き直せます。
閉じたIssueが見当たらなくなっても、慌てなくて大丈夫です。Issuesタブの一覧は、最初は対応中（Open）のものだけを表示しています。一覧の上にある「Closed」（件数付きで「Closed (1)」のように表示されます）を押せば、閉じたIssueも出てきます。
対応が済んだのに、プルリクエストとつながっていないIssueは、Issueの画面の下にある「Close issue」で手動で閉じられます5。
佐藤さんの依頼を、Issueにしてみると
第1回の佐藤さんは、AIに「部門別の内訳も出して」と頼みました。総額まで変わったのを見て、頼んだ範囲を超えていることには、すぐに気づいています。「部門別にして、と頼んだだけなのに」という一言が、それを物語っています。問題は、気づけなかったことではありません。何を頼み、何は変えてほしくなかったのか。その依頼が、AIにも同僚にも伝わる形でどこにも残っていなかったことです。
もし最初に、こんなIssueを立てていたらどうでしょう。
集計ツールに、部門別の内訳を追加する。
- [ ] 部門ごとの売上を表示する
- [ ] 売上総額の計算方法は変えない
「総額の計算方法は変えない」と書いてあれば、第1回の後半で描き、第4回で種明かしをした場面が、もっと楽になります。修正案の差分に集計条件の書き換えが混ざっていたら、Issueと見比べるだけで「頼んだ範囲を超えている」と言えるからです。コメントで「集計条件は昨日の版のままにしてください」と返すときも、根拠を示せます。
同僚の田中さんが進めていた日付の修正も、別のIssueとして立てておけます。佐藤さんの依頼が「#3」、田中さんの依頼が「#4」というように、番号で分けておく。それぞれのプルリクエストに「Closes #3」「Closes #4」と書けば、どの修正がどの依頼に対応しているのかが、取り違えようのない形で残ります。第1回の共有フォルダで起きていた「誰の、どの修正が入っているのか分からない」という状態には、なりにくくなるはずです。
依頼を文章にしておくことには、もう1つ利点があります。この連載の後半で扱うのは、AIのCodex（OpenAIが提供する、開発作業を任せられるAI）に作業を任せる方法です。Issueに書いた依頼は、そのままAIへの指示の下書きにもなります。何を頼み、何は変えてほしくないのか。人に頼むときもAIに頼むときも、最初に書くべきことは同じです。
まとめと次回予告
今回分かったことは3つです。
- Issueは、依頼に番号を付けて記録する場所
- 依頼についての相談と結論も、同じIssueに残せる
- プルリクエストに「Closes #番号」と書けば、マージで依頼まで片付く
第3回から、ここまではすべてブラウザの中で操作してきました。次回は、自分のパソコンとGitHubをつなぎます。GitHubのリポジトリをパソコンに写し、手元で変えた内容をGitHubに送る。AIのCodexに手元で作業してもらうための、土台づくりです。
実はこの記事も、今回の手順どおりにIssueから作っています。その舞台裏は、次回以降でお見せします。