Issue ベースの開発フローを回す

この章で学ぶこと：GitHub Issue を使った開発フロー、ブランチ戦略、PR テンプレート、そして AI エージェント（Claude Code）との組み合わせ方を身につける。
なぜ学ぶのか：一人開発でも issue を切る習慣があると「何を作るか」が明文化され、途中離脱しても再開できる。実務では必須のスキル。
Web 開発のどの領域か：開発プロセス・チーム開発・AI エージェント活用。

前提: b02-git-basics b03-github-workflow b21-claude-md b22-task-decomposition を読み終えていること。

所要時間: 60 分（読解 25 分＋自分の sns_clone に issue を 5 件切って PR を 1 件作る 35 分）

到達目標: sns_clone リポジトリに issue ベースの開発フローが回り始め、PR が 1 件マージされている状態。

なぜ Issue を切るのか

やることを明文化する: 頭の中にだけあるタスクは消える。issue にすると永続化される。
進捗の可視化: 未着手・実装中・レビュー中・完了が GitHub Project で一目で分かる。
AI への入力になる: Claude Code に「issue #12 を実装して」と依頼できる。issue の本文がそのまま仕様書になる。
あとから自分が振り返れる: 3 か月後にコミット履歴を見ても意図が分からないことがある。issue のリンクがあれば戻って読める。

Issue の書き方テンプレート

## 目的

このタスクで達成したいこと（ユーザーが何をできるようになるか）。

## 完了条件

- [ ] 条件 1（動作 or 見た目の確認可能な形で）
- [ ] 条件 2
- [ ] テストが書かれている
- [ ] README / 仕様書が更新されている

## 実装メモ

関連するファイル・想定される変更箇所・参考リンク。

## 関連

- 関連 issue: #5
- 関連ドキュメント: docs/screen-transition.md

ブランチ戦略（単独開発向け）

main: 常にデプロイ可能な状態
feat/<短い説明>: 新機能（例：feat/like-button）
fix/<短い説明>: バグ修正
chore/<短い説明>: 依存更新など雑事

issue との対応は feat/issue-12-like-button のような命名にする流派と、branch 名に issue 番号を入れない流派がある。好みの問題なので決めて守る。

1 サイクルの流れ

1. issue を切る（何を・なぜ・完了条件）
2. main から branch を切る
3. 実装 + ローカルでテスト
4. push → PR を作る（PR 本文で `Closes #12` と書く）
5. CI を待つ
6. セルフレビュー（時間を空けてから自分で読み直す）
7. マージ → main が自動デプロイされる
8. issue が Closes で自動クローズ

Closes #12 / Fixes #12 / Resolves #12 のいずれかを PR 本文に書くと、マージ時に該当 issue が自動で閉じられる。

PR テンプレート

.github/PULL_REQUEST_TEMPLATE.md を置くと、PR 作成時に自動でこのテンプレが挿入される。

## 概要

Closes #<issue 番号>

このPRで何を変更したか（1〜2 行）。

## 変更内容

- 変更点 1
- 変更点 2

## 動作確認

- [ ] ローカルで起動して正常動作を確認した
- [ ] 該当のテストが通る
- [ ] 関係する画面でリグレッションがない

## スクリーンショット

Before / After の画像を貼る（UI 変更の場合）。

Claude Code との組み合わせ

issue を整備すると AI の出力が劇的に改善する。

プロンプト例:
「issue #15 を読んで、完了条件を満たす最小限の実装をしてください。
変更対象は web/src/components/ と api/src/routes/ に限定。
テストは vitest で書いてください。」

このとき、CLAUDE.md にプロジェクトルール（命名規則・コミット message 形式・テストの書き方）が書かれていると、AI は文脈に沿った出力をする。b21-claude-md を参照。

よくある詰まりポイント

issue が大きすぎる: 「MVP 実装」のような粒度は issue にならない。「タイムラインに投稿一覧を表示する」くらいに分割する。
完了条件が曖昧: 「いい感じに動く」は完了条件にならない。「ログインユーザーが自分の投稿 10 件を新着順で見られる」のように確認可能な形で書く。
PR を大きくしすぎる: 500 行超の PR はレビューが難しい。機能単位で分割する。

sns_clone 参考実装

docs/curriculum.md — 受講者向けのカリキュラム全体像（issue 化の元ネタ）
docs/weekly-template.md — 週次 issue テンプレ

確認クイズ

Q1. PR 本文に Closes #12 と書く目的は何か。

正解: PR がマージされたときに、GitHub が自動で issue #12 を閉じる連携を有効にするため。手動でクローズする手間が省け、閉じ忘れも防げる。

解説: Closes / Fixes / Resolves のいずれも同じ動作をする。チームや個人の習慣で統一する。

Q2. issue の「完了条件」を曖昧に書くとどんな問題が起きるか。

正解: 実装中に自分（または AI）がどこで止めればいいか判断できず、過剰実装や実装漏れが起きる。

解説: 「いい感じ」「きれいに」のような主観的な条件は判定不能。「〜ができる」「〜の値を返す」のように観測可能な条件にすることで、実装の完了判断が機械的に行える。

生きているコード

本ドキュメントで扱ったパターンの完全な動作コードは、メンター側リポジトリの参照ブランチで確認できます。

対応 Week: W1 / W2 / W3 / W4
参照ブランチ:
W1: reference/week-1
W2: reference/week-2
W3: reference/week-3
W4: reference/week-4
対応 checklist 項目: N8

ブランチの作り方・見方は b00-curriculum-map を参照してください。