GitHub Issue・PR の正しいワークフロー

概要

GitHubでは、Issue → ブランチ → PR → マージという流れが標準的なワークフローです。PRのdescriptionに Closes #3 と記載することで、PRマージ時にIssueが自動クローズされます。

標準ワークフロー

1. Issueを確認

# Issue一覧を確認
gh issue list

# Issue #3の詳細を確認
gh issue view 3

2. 作業用ブランチを作成

# masterブランチから最新を取得
git checkout master
git pull origin master

# Issue番号を含むブランチ名で作成（推奨）
git checkout -b feature/3-add-search-functionality
# または
git checkout -b fix/3-search-bug

ブランチ名の例：

• feature/3-add-search - 新機能
• fix/3-bug-name - バグ修正
• docs/3-update-readme - ドキュメント更新

3. 実装・コミット

# 変更を実装
# ...

# 変更をステージング
git add .

# コミット（詳細なメッセージ）
git commit -m "feat: FlexSearchによる全文検索機能を実装

- FlexSearchライブラリを追加
- 検索ページ（/search）を新規作成
- MDC AST形式に対応したテキスト抽出を実装

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>"

4. ブランチをプッシュ

# 初回プッシュ時は -u オプションでトラッキング設定
git push -u origin feature/3-add-search-functionality

5. PRを作成

gh pr create --title "検索機能の実装" --body "$(cat <<'EOF'
## 概要
FlexSearchを使用した全文検索機能を実装しました。

## 変更内容
- ✅ FlexSearchライブラリの追加
- ✅ `/search` ページの新規作成
- ✅ MDC AST形式のテキスト抽出対応
- ✅ 日本語・英語の全文検索対応
- ✅ キーワードハイライト機能
- ✅ デバウンス処理（300ms）

## テスト
- [x] 英語検索（例: "SEO", "Excel"）
- [x] 日本語検索（例: "赤字", "繰越欠損金"）
- [x] 短い単語の検索
- [x] スニペット生成とハイライト

## 関連Issue
Closes #3

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

重要ポイント:

• Closes #3 で Issue #3 とリンク
• PR本文に変更内容を詳しく記載
• チェックリストで実施内容を明示

6. PRマージ

PRがレビュー・承認されたら、以下のいずれかの方法でマージ：

方法A: GitHub Web UI

1. PR画面で「Merge pull request」をクリック
2. マージメッセージを確認
3. 「Confirm merge」をクリック
4. Issue #3 が自動的にクローズされる ✨

方法B: GitHub CLI

# PRをマージ
gh pr merge 4 --squash --delete-branch

# または、マージ方法を選択
gh pr merge 4
# → Merge方法を選択: Squash / Merge commit / Rebase

7. ローカルブランチの削除

# masterに戻る
git checkout master

# リモートの最新を取得
git pull origin master

# 作業ブランチを削除
git branch -d feature/3-add-search-functionality

PR Description のベストプラクティス

基本構成

## 概要
何を実装/修正したかを1-2行で説明

## 変更内容
- 主要な変更点をリスト化
- ファイル単位または機能単位で記載

## テスト
実施したテストケース

## スクリーンショット（必要に応じて）
視覚的な変更がある場合

## 関連Issue
Closes #3

Issueを自動クローズするキーワード

PRのdescriptionまたはコミットメッセージに以下を記載：

参考: GitHub公式ドキュメント

今回の反省点

実際に行ったこと（誤り）

# masterブランチで直接作業
git checkout master
# 変更を実装...
git commit -m "..."
git push origin master  # ← masterに直接プッシュ

問題点:

• ✗ PRを経由していないためレビュー不可
• ✗ Issueが自動クローズされない
• ✗ 変更履歴がフラットで追跡困難

正しい流れ（修正版）

# 1. 作業ブランチを作成
git checkout -b feature/3-add-search-functionality

# 2. 変更を実装・コミット
git add .
git commit -m "..."

# 3. ブランチをプッシュ
git push -u origin feature/3-add-search-functionality

# 4. PRを作成（Closes #3 を記載）
gh pr create --title "..." --body "...Closes #3..."

# 5. PRをマージ → Issue #3 自動クローズ ✨
gh pr merge

既にmasterにプッシュしてしまった場合のリカバリ

方法1: ブランチを作り直す

# 1. 現在のHEADからブランチを作成
git checkout -b feature/3-add-search-functionality

# 2. masterを元に戻す（プッシュ前の状態）
git checkout master
git reset --hard origin/master

# または、特定のコミットまで戻す
git reset --hard <commit-hash>

# 3. masterを強制プッシュ（注意！）
git push origin master --force

# 4. feature ブランチをプッシュ
git checkout feature/3-add-search-functionality
git push -u origin feature/3-add-search-functionality

# 5. 通常通りPRを作成
gh pr create --title "..." --body "...Closes #3..."

注意: --force プッシュはチーム開発では危険です。個人リポジトリでのみ使用してください。

方法2: 今回は諦めて次回から正しく実施

今回は手動でIssueをクローズし、次回から正しいワークフローを実践する方が安全です：

# Issueにコメントを追加
gh issue comment 3 --body "検索機能を実装しました。

実装内容:
- FlexSearchによる全文検索
- MDC AST対応
- 日本語・英語検索対応

関連コミット: d7e6594, e7a3da1, cbc5aeb, 9cd9b7e"

# Issueを手動でクローズ
gh issue close 3

チーム開発での追加ルール

ブランチ保護

masterブランチを保護して、直接プッシュを防止：

1. GitHub リポジトリ → Settings → Branches
2. "Add rule" をクリック
3. Branch name pattern: master
4. 以下をチェック:
   • ✅ Require pull request before merging
   • ✅ Require approvals (1人以上)
   • ✅ Dismiss stale approvals

レビュープロセス

# PR作成時にレビュアーを指定
gh pr create --reviewer username1,username2

# レビューコメントに返信
gh pr comment 4 --body "ご指摘ありがとうございます。修正しました。"

# 修正をプッシュ（同じブランチに追加コミット）
git add .
git commit -m "fix: レビュー指摘事項を修正"
git push

まとめ

✅ 正しいワークフロー:

Issue作成 → ブランチ作成 → 実装 → PR作成（Closes #N） → レビュー → マージ → Issue自動クローズ

✅ ベストプラクティス:

• Issue番号をブランチ名に含める
• PRのdescriptionに Closes #N を記載
• PRで変更内容を詳しく説明
• masterに直接プッシュしない

✅ 次回の実践:

1. git checkout -b feature/issue番号-機能名
2. 実装・コミット
3. git push -u origin ブランチ名
4. gh pr create で Closes #N を含むPRを作成
5. PRマージでIssue自動クローズ

このワークフローを実践することで、変更履歴が整理され、レビューがしやすく、Issueとの紐付けも自動化されます。