チーム開発で地味に効くのが「命名の統一」です。
ブランチ名とコミットメッセージが揃うだけで、PRレビュー速度・検索性・自動化（リリースノート生成等）が目に見えて改善します。
この記事では、今日から現場で運用できる最小ルールを「具体例付き」で整理します。
目標（このルールで得られるもの）
- ブランチを見た瞬間に「何の作業か」分かる
- コミット履歴から「何を・なぜ」変えたか追える
- チケット駆動（Jira/GitHub Issuesなど）と自然に紐づく
- Conventional Commits による自動リリースノート生成/分類がしやすい
1. ブランチ名：ベストプラクティス
1-1. 結論：このフォーマットを標準にする
推奨フォーマット（チケットあり）
<type>/<TICKET>-<short-summary>
推奨フォーマット（チケットなし）
<type>/<short-summary>
- 小文字
- ハイフン区切り
- 短く具体的（40文字目安）
- スペース/全角は避ける
1-2. type（prefix）のおすすめセット（迷ったらこれ）
-
feat/: 新機能 -
fix/: バグ修正 -
refactor/: 挙動を変えない内部改善 -
docs/: ドキュメント -
test/: テスト -
chore/: 雑務（依存更新、設定変更など） -
ci/: CI関連 -
build/: ビルド/バンドル関連 -
perf/: パフォーマンス改善 -
hotfix/: 緊急修正（必要なら）
feature/やbugfix/でもOK。大事なのはチームで統一。
1-3. ブランチ名の具体例（良い例 / 悪い例）
✅ 良い例
feat/PROJ-321-add-invoice-downloadfix/api-return-400-on-empty-filterrefactor/web-extract-auth-hookci/speed-up-e2e-cache
❌ 悪い例（よくある）
-
feature（情報不足） -
FixLoginBug（区切り・規則なし） -
wip/update-something（曖昧） -
山田_ログイン修正（ツール/環境で壊れやすい）
1-4. 長命ブランチと短命ブランチを分ける
- 長命：
main（＋運用によってdevelop,release/*） - 短命：
feat/*,fix/*… は PRマージ後に削除
2. コミットメッセージ：ベストプラクティス
2-1. 結論：Conventional Commits を基本形にする
推奨フォーマット
<type>(<scope>): <subject>
-
type：変更の種類 -
scope：影響範囲（任意だがあると超便利） -
subject：何をしたか（短く・具体的に）
2-2. type のおすすめセット（ブランチと揃えると強い）
-
feat,fix,docs,refactor,test,chore,ci,build,perf,revert
2-3. subject（1行目）のルール：ここだけ守れば強くなる
- **命令形（英語）**で書く（例：add / fix / remove）
- 50文字以内目安（長いなら本文へ）
- 句点は不要
- “update”“change” だけで済ませない（曖昧）
✅ 良い例：
fix(payment): prevent double charge on retry
❌ 弱い例：
update payment
2-4. 本文（Body）は「Why/What/Tests」だけで十分
1行目で足りない時だけ書きます。テンプレ：
<type>(<scope>): <subject>
Why:
- なぜ変えたか（背景/原因/仕様）
What:
- 何を変えたか（要点を箇条書き）
Tests:
- どう確認したか（コマンド/観点）
2-5. Breaking Change とチケット紐づけ
破壊的変更
- 1行目に
!：feat(api)!: rename endpoint - または本文に
BREAKING CHANGE:を記載
チケット紐づけ
- 本文に
Refs: PROJ-123（またはCloses #123）で統一すると便利
3. “すぐ現場で回る”運用ルール（最小セット）
3-1. ブランチ命名ルール（コピペ可）
-
type/(TICKET-)?summaryを基本 -
typeはfeat|fix|refactor|docs|test|chore|ci|build|perf|hotfix -
summaryは小文字英数字と-のみ - チケットがある場合は
PROJ-123-を付与 - PRマージ後はブランチ削除
3-2. コミットメッセージルール（コピペ可）
- 形式：
type(scope): subject -
typeはfeat|fix|docs|refactor|test|chore|ci|build|perf|revert - subjectは50文字以内、命令形、句点なし
- 破壊的変更は
!またはBREAKING CHANGE: - チケットがある場合は本文に
Refs: PROJ-123
4. 具体的な開発フロー例（ブランチ→コミット→PR）
ケース：請求書PDFダウンロード機能を追加する（チケットあり）
1) ブランチを切る
git checkout -b feat/PROJ-321-add-invoice-download
2) 実装を進めながらコミット
コミット1：API追加
feat(api): add endpoint for invoice pdf download
Refs: PROJ-321
Tests:
- phpunit --filter InvoiceDownloadTest
コミット2：フロント導線
feat(web): add download button to invoice page
Refs: PROJ-321
コミット3：リファクタ（挙動は変えない）
refactor(web): extract invoice fetch hook
Refs: PROJ-321
コミット4：CI調整
ci: cache playwright browsers
3) PRタイトル（squash運用でも強い）
PRタイトルも Conventional Commits っぽく揃えると、squash時に履歴がきれいです。
feat: add invoice pdf download (PROJ-321)
5. よくある悩みと答え
Q1. scopeって何にすればいい？
迷ったら リポジトリの構造/責務に合わせます。
例：
-
api,web,auth,infra,db,payment,docs,ci
Q2. 日本語コミットはダメ？
ダメではないですが、検索性・多国籍チーム・ツール連携（自動生成）を考えると 英語推奨が安定です。
ただし、チームが日本語で統一しているなら「短く具体的」を守れば運用可能です。
Q3. 1コミットの粒度が難しい
基本は 1コミット=1意図。迷ったら分ける：
- リファクタだけ
- 挙動が変わる変更
- テスト追加
6. 最終まとめ（この2つだけ覚える）
- ブランチ：
feat/PROJ-123-short-summary（小文字・ハイフン・短く） - コミット：
feat(scope): subject（命令形・具体的・必要ならWhy/Tests）