【連載①】Claude Code向けGitHub Issueの書き方｜アイデアを言語化する最初の一歩
> 📚 連載：Claude Code × GitHub 運用フロー（全8回）
【今ここ】
↓
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ①アイデア / Issue ← 今ここ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
↓
②clone & branch
↓
③Claude Codeで実装
↓
④動作確認 / テスト
↓
⑤commit & push
↓
⑥Pull Request作成
↓
⑦レビュー / 修正
↓
⑧merge & deploy
> 次回：cloneとbranch、最初に詰まる2語（2026-05-14 公開予定）
Claude Code向けGitHub Issueの書き方を、非エンジニア視点で整理した記事です。
「やりたいことはあるけど、どこから手をつければいいかわからない」
Claude Codeを使い始めて、いざ自分のプロジェクトを動かそうとしたとき、私が最初にぶつかったのがこれでした。
GitHubの画面を開いて、「Issues」というタブはあるけれど、何を書けばいいのか、本当に書いていいのかすら判断できない。そんな状態が続いていました。
この記事では、Claude Codeにそのまま渡せるGitHub Issueの書き方を、非エンジニア向けに整理します。連載全体では、Claude CodeとGitHubを組み合わせた運用フローを8回に分けて解説していきます。初回は「アイデアをIssueに言語化する」工程です。
—
Issueは「やりたいこと・困っていること」を1件ずつ残すメモ
一言で言えば、Issueは「やりたいこと・困っていること」を1件ずつ書き留める付箋です。
ToDoリストのアプリを使ったことがあれば、それを思い浮かべてください。「明日までに買い物に行く」「来週までに資料を作る」と書く、あの感覚です。
GitHubのIssueも、それと同じです。大きな違いは、コメント・担当者（Assignees）・ラベル（Labels）などを使って後から追いやすいこと。一人で使う場合でも、自分への作業メモとして十分機能します。
私が最初に勘違いしていたのは、「Issueはバグ報告専用」だと思い込んでいたことでした。実際は、リポジトリのルールに沿っていれば、機能の追加・改善のアイデア・調べたいこと・気になっていることなど、幅広く使えます。
—
なぜ「Issueから始める」のが大事なのか
最初は「Issueなんて書かずに、いきなりClaude Codeに頼めばいいのでは？」と思っていました。
でも、実際にやってみるとわかります。頭の中の「やりたいこと」をそのまま口頭でClaude Codeに伝えると、何かしらズレた成果物が返ってくるんです。
Issueに書き出してから依頼するようになって、ズレが減りました。
理由はシンプルで、書く過程で「自分が本当は何をしたいのか」が整理されるからです。「Webサイトを作りたい」だけだったアイデアが、書いているうちに「お問い合わせフォーム付きの1ページのLP」「色はベージュ系」「スマホで見たときに崩れないこと」と具体化していきます。
書くこと自体が思考の整理になる、という体験でした。
—
Claude Codeに渡しやすいGitHub Issueの書き方
「Issueに書く内容を整理するのが面倒」という人にこそ、Claude Codeを使ってほしいです。
頭の中のもやもやを話すだけで、Issue形式に整えてくれます。
私が使っているプロンプトはこれです：
これからやりたいことを話すので、GitHubのIssue形式にまとめてください。
【やりたいこと】
（ここに思いついたことを箇条書きでも文章でも書く）
出力ルール：
- この段階では実装はしないでください（Issue文章の作成のみ）
- GitHubにそのまま貼れるMarkdown形式で出力してください
- タイトルと本文を分けて出力してください
- 不足している情報があれば、まず私に質問してください
出力フォーマット（本文側）：
- 背景：なぜやりたいか（2〜3行）
- やること：具体的な作業を箇条書き
- 完了条件：何が出来ていれば終わりか（3つ以内）
- 補足：迷っている点・あとで決める点
最初から完璧に書こうとしないのがコツです。「お問い合わせフォーム付けたい、たぶんGoogleフォームでもいけそう、でも見た目変えたい」みたいに、ぐちゃぐちゃに伝えても整えてくれます。
—
最低限おさえたいIssueの3要素：タイトル・完了条件・補足
何度か書いて気づいたのは、書きやすい・読み返しやすいIssueには共通点があるということです。背景や具体的な作業内容は余裕があれば足すとして、まずはこの3つだけ意識すれば十分でした。
1. タイトルは動詞で終わらせる
「ログイン画面を作る」「日付フォーマットの不具合を直す」のように、何をするのかが一目でわかる動詞で締めると、後から見返したときに迷いません。
2. 「完了条件」を3つ以内で書く
ここがいちばん大事です。「これができていれば完了」と言える条件を3つ以内で書きます。多すぎると終わらないし、なさすぎると終わったかどうか判断できません。
私は最近、こんなふうに書いています：
- 完了条件1: トップページにフォームが表示される
- 完了条件2: フォーム送信時、指定したメールアドレスにテスト通知が届く
- 完了条件3: iPhone Safariで開いてもレイアウトが崩れない
3. 補足に「迷っている点」を残す
「色をベージュにするか白にするか迷っている」「ライブラリは後で選ぶ」など、まだ決められていないことをそのまま書きます。
正直に書いておくと、後でClaude Codeに「この迷っている点、どう判断する？」と聞くときの材料になります。
—
やってみて正直に感じたこと
よかった点：
- 頭の中の「やりたい」が、目に見える形に変わる
- Issue本文はClaude Codeへの依頼文の土台として使える（実装時は対象ファイル・制約・確認方法を足すとズレにくい）
- 「あれ何やろうとしてたっけ？」が消えた
まだよくわからない点：
- 1つのIssueにどこまで詰め込んでいいのか。大きいタスクを1個にまとめるか、3個に分けるか、毎回迷っています
- ラベル（Labels）機能はまだ使いこなせていない。とりあえず色分けしている程度
失敗した体験：
最初の頃、Issueに「全部やる」と書いてしまったことがあります。サイトのデザイン・機能・公開作業まで1つに詰め込んだ結果、何から手をつければいいか自分でわからなくなりました。
その経験から、私はまず「1つのIssueは1日以内で終わる粒度」を目安にしています。それ以上大きそうなら、Issueを分割するか、親Issueと子Issueに分けるようにしています。
—
連載の進め方（ロードマップ）
この連載では、Claude Codeを使った開発の流れを8ステップに分けて、1記事ずつ解説していきます。
【全体フロー】
①アイデア / Issue ← 今ここ ⭐
↓
②clone & branch 作業ブランチを切る
↓
③Claude Codeで実装 対話しながらコード生成
↓
④動作確認 / テスト ローカルで挙動を検証
↓
⑤commit & push GitHubに変更を送る
↓
⑥Pull Request作成 CI実行 / レビュー依頼
↓
⑦レビュー / 修正 セルフ or Claudeに依頼
↓ ↑ 指摘対応で⑤へ戻る
⑧merge & deploy 本番反映
毎回、非エンジニアの私が実際にやってみた記録を、プロンプト付きで残していきます。
—
まとめ
- IssueはGitHubの「やりたいこと付箋」。バグ報告以外でも使っていい
- 書き出す過程で「本当は何をしたいか」が整理される
- Claude CodeにIssue形式の整形を任せると、書く心理的ハードルが消える
- タイトルは動詞・完了条件は3つ以内・補足に迷っている点を残す
- 1つのIssueは「1日以内で終わる粒度」を目安にする
- 慣れてきたら、ラベル（Labels）・担当者（Assignees）・Projects・GitHub CLIの `gh issue create` なども使えるが、最初はタイトルと完了条件だけで十分
連載第1回は、すべての作業のスタート地点である「Issue」の話でした。
「Issueなんて書いたことがない」という方も、まずは今日の作業1つ分でいいので、Claude Codeに整理させてみてください。書き出してみると、思っていたよりやることが明確になるはずです。
次回は、Issueを書いた後の最初の作業「clone & branch」について書きます。リポジトリを手元に持ってきて、作業ブランチを切るまでの流れを、私がつまずいた所も含めて正直に記録します。