GitHub Issuesを書く技術
〜開発チームの生産性を高める「伝わるIssue」の書き方ガイド〜
1. はじめに
GitHub Issuesは、ソフトウェア開発においてタスク管理・バグ報告・議論の場として広く利用されています。しかし、曖昧で伝わらないIssueは、手戻りや開発スピードの低下を招きがちです。
この記事では、「読みやすく、行動しやすく、議論しやすい」Issueの書き方を解説します。
Issueは単なる備忘録ではなく、チームとの対話と行動を促すインターフェースです。
2. なぜ良いIssueが重要なのか？
✅ 1. 開発のスピードが上がる
→ 必要な情報が揃っていれば、即着手できる
✅ 2. バグや仕様のすれ違いを防げる
→ 曖昧な要望は、誤解の原因に
✅ 3. チームメンバーとの信頼が生まれる
→ 「分かりやすいIssue」は読み手へのリスペクト
3. 良いGitHub Issueの基本構成
以下の構成を意識することで、どんなIssueでも「伝わる」形になります：
タイトル（1行で内容を要約） 本文： 1. 概要（何を伝えたいのか） 2. 再現手順や背景（なぜこのIssueが必要か） 3. 期待する結果（どうなってほしいか） 4. スクリーンショットやエラー出力（必要に応じて） 5. 備考・関連IssueやPRへのリンク
4. 書き方テンプレート（サンプル付き）
🎯 機能追加の例
タイトル
Add export button to dashboard table
本文
## 概要 ダッシュボード画面の表に「CSVエクスポート」ボタンを追加したいです。 ## 背景 ユーザーから「月次で集計したデータをCSVで出力したい」と要望がありました。 ## 期待する結果 - テーブル上部に「エクスポート」ボタンが表示される - クリックでCSVファイルをダウンロードできる ## 備考 - UIデザインはFigmaにあります（https://figma.com/project/xxx） - backend/api/csv-export エンドポイントは既にあります
🐛 バグ報告の例
タイトル
[Bug] ログイン後にリダイレクトされない問題
本文
## 概要 正しい認証情報でログインしても、ダッシュボードにリダイレクトされません。 ## 再現手順 1. /login にアクセス 2. 正しいメール・パスワードを入力 3. ログイン後 `/` に留まる（`/dashboard` へ遷移しない） ## 期待する動作 ログイン後は `/dashboard` に遷移する ## エラー出力
Uncaught (in promise) TypeError: Cannot read property 'push' of undefined
## 備考 - 影響範囲：`useAuth.ts` の `login()` 関数？ - 関連PR: #102
5. 書く時の5つのコツ
✅ 1. タイトルは「名詞＋動詞」で簡潔に
例：
✗ 「表に関して」
◎ 「表にソート機能を追加」
✅ 2. 読み手にとっての「WHY」を必ず書く
単なる仕様説明でなく、背景や目的を書くことで、理解が早くなります。
✅ 3. 再現手順・前提条件はできるだけ具体的に
とくにバグ報告では、「再現できる」ことが非常に重要です。
✅ 4. スクリーンショットやGIFで可視化
「百聞は一見にしかず」。
デザイン・UI系のIssueでは特に有効です。
✅ 5. ラベル・Assignee・Milestoneを活用
bug,enhancement,question,help wantedなどのラベルは分類に便利- 担当者（Assignee）とマイルストーンも忘れずに設定
6. Issueを書くときによくあるアンチパターン
| 悪い例 | 問題点 |
|---|---|
| 「バグっぽい」 | 内容が不明瞭、再現できない |
| 「やってほしいです」 | 要望が曖昧、背景不明 |
| 「○○ができない」 | 状況が不足、誰も対応できない |
7. まとめ：Issueは「一人のメモ」ではない
良いIssueは、チーム全員が理解し、議論し、行動できる「情報のインターフェース」です。
読み手の立場に立って、背景・目的・期待を明確に書くことで、開発はもっとスムーズに、信頼あるものになります。
あなたの次のIssueが、チームの未来を変えるかもしれません。
