conventional-git

Conventional Commits とブランチ命名

ブランチ名とコミットメッセージの両方で Conventional Commits v1.0.0 に従ってください。一貫した命名により、ツールでの変更履歴の自動生成、SemVer のバージョン更新の適用、変更内容に応じた履歴の絞り込みが可能になります。

ブランチ命名

形式：<type>/[issue-]<description> — 小文字とハイフンのみを使用し、/ 以外の特殊文字は使いません。

feat/user-authentication
feat/42-user-authentication
fix/login-race-condition
fix/87-login-race-condition
docs/api-reference-update
refactor/payment-module

課題番号がある場合は、先頭に付けてください。GitHub と GitLab で自動的にリンクされ、git log から課題管理ツールをすぐにたどれるようになります。説明部分は 50 文字未満にしてください。多くの Git UI では、この程度の長さでブランチ名が一覧上で省略されるためです。作業内容に合った type を選んでください。これにより、ブランチの目的をひと目で理解できます。

ブランチ名に worktree を含めないでください。Git worktree はローカルのチェックアウト方式であり、ブランチの概念ではありません。名前に含めると実装の詳細がリモートに漏れ、ほかのコントリビューターを混乱させます。

Worktree の命名

Worktree はローカルのチェックアウトディレクトリであり、リモートには表示されません。.claude/worktrees/ の下に配置し、ブランチ名の / を - に置き換えて命名してください。

git worktree add .claude/worktrees/feat-user-authentication feat/user-authentication
git worktree add .claude/worktrees/fix-87-login-race-condition fix/87-login-race-condition

ディレクトリ名をブランチ名に合わせると、git worktree list が読みやすくなり、チェックアウトの内容を調べなくても各 worktree がどのブランチに対応するかすぐに分かります。新しい worktree を作成する前に git worktree list を実行し、同じブランチを対象とするものがすでにあれば再利用してください。

Worktree は単一のブランチに限定してください。他の人の worktree で無関係な作業をすると、変更の所属先が分かりにくくなり、クリーンアップ時に誤りが起きやすくなります。

ブランチがマージされたら worktree を削除してください。ローカルでマージした後、またはリモートでプルリクエスト／マージリクエストがクローズされた後に削除します。古い worktree がたまると、git worktree list が読みにくくなります。

git worktree remove .claude/worktrees/feat-user-authentication   # branch merged locally
git worktree prune                                                # remove refs to already-deleted directories

コミットメッセージの形式

<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

タイプ：

タイプ	SemVer	使用する場面
feat	MINOR	新機能
fix	PATCH	バグ修正
docs	—	ドキュメントのみ
style	—	書式の変更。ロジックの変更なし
refactor	—	機能追加・修正を伴わない再構成
perf	—	パフォーマンスの改善
test	—	テストの追加・修正
build	—	ビルドシステム、依存関係
ci	—	CI 設定
chore	—	その他（src/test 以外）
revert	—	以前のコミットの取り消し

ルール：

• 件名は 72 文字以内にしてください。これを超えると、git log や GitHub／GitLab の UI で件名が通知なく省略されます
• 命令形を使ってください。「added」ではなく「add」とします。履歴の記録ではなく、指示として読めます
• 先頭を大文字にせず、末尾にピリオドを付けないでください。変更履歴ツールによる解析を統一できます
• 本文の前には空行を入れてください。パーサーは最初の空行でヘッダーと本文を分割します
• 破壊的変更には、type／scope の後に ! を付けるか、フッターに BREAKING CHANGE: を追加してください（MAJOR の更新が発生します）。本文だけの説明は変更履歴ツールに認識されません
• revert コミットには、本文に This reverts commit <hash>. を含めることを推奨します。git revert が自動生成するため、削除しないでください
• Claude の署名、AI エージェントのクレジット、または Claude やその他の AI エージェントに対する Co-authored-by トレーラーをコミットに追加しないでください

例：

feat(auth): add JWT token refresh

fix: prevent race condition on concurrent requests

Introduce request ID and reference to latest request.
Dismiss responses from stale requests.

refactor!: drop support for Go 1.18

BREAKING CHANGE: Go 1.18 no longer supported; uses stdlib APIs from 1.21+

コミットメッセージで課題をクローズする

GitHub と GitLab はどちらも、コミットメッセージ内のキーワードを検出し、コミットがデフォルトブランチに取り込まれると、参照された課題を自動的にクローズします。参照はフッターに記載してください（推奨 — 件名行をすっきり保てます）。

キーワード： close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved — 大文字と小文字は区別されません。

GitHub：

fix(auth): prevent token expiry race condition

Closes #42
Closes owner/repo#99

• デフォルトブランチ（通常は main）にマージされたときに動作します
• リポジトリをまたぐ場合：Closes owner/repo#42
• 複数の課題をクローズする場合：Closes #42, closes #43
• PR の説明でも機能します

GitLab：

feat: add dark mode support

Resolves #101
Closes group/project#42

• デフォルトブランチ（プロジェクトごとに設定可能）にマージされたときに動作します
• プロジェクトをまたぐ場合：Closes group/project#42
• 複数の課題をクローズする場合：Closes #101, closes #102
• MR の説明でも機能します

ヒント： コミットの種類と組み合わせます。バグ課題をクローズする場合は fix:、機能リクエストをクローズする場合は feat: とすると、変更履歴に一貫性が生まれます。

よくある間違い

間違い	修正
feat: Added login page	feat: add login page — 命令形にし、大文字を使わない
fix: fix bug.	fix: fix bug — 末尾にピリオドを付けない
件名が72文字を超えている	短くし、詳細は本文に移す
破壊的変更を本文にのみ記載している	! を追加するか、フッターに BREAKING CHANGE: を記載する — ツールは本文だけに記載された内容を検出しません
feat(adding-auth): ...	feat(auth): ... — スコープには動詞ではなく名詞を使う
件名行に Closes #42 を記載している	フッターに移す — 件名をすっきり保ち、解析しやすくする

ベストプラクティス

• ブランチの種類とコミットの種類を一致させます — feat/auth-* ブランチ → feat(auth): コミット
• 1つのブランチにつき1つの関心事に絞ります — 機能ブランチに修正を混在させると、変更履歴がわかりにくくなります
• ブランチ内でスコープを一貫して使います — 全体を通して feat(auth): とし、途中で feat(user): に変えないでください
• スカッシュマージ： PR/MR をスカッシュマージすると、ブランチのコミットは1つにまとめられます — PR/MR のタイトルがコミットメッセージになります。タイトルが Conventional Commits の形式に従っていないと、変更履歴の生成は通知なく失敗します。スカッシュする前に、必ず PR のタイトルを設定してください。