Commit Conventions Guide

複雑なコミットシナリオや判断に迷う場面での詳細ガイダンス。単純なケースはCLAUDE.mdの基本原則で十分。

複雑なケースの判断基準

いつこのスキルが必要か

シナリオ	複雑度	推奨アプローチ
1ファイル、1種類の変更	単純	CLAUDE.md原則で直接コミット
複数ファイル、同一目的	単純	CLAUDE.md原則で直接コミット
複数種類の変更が混在	複雑	このスキル参照 or `/semantic-commit`
大規模リファクタリング	複雑	`/semantic-commit` で自動分割
Breaking changes	複雑	このスキル参照

変更の分離戦略

混在パターンと分離方法

パターン1: 機能追加 + バグ修正

code

✅ 正しい分離:
  1. fix(auth): handle null user in session check
  2. feat(auth): add remember-me functionality

❌ 混在させない:
  feat(auth): add remember-me and fix null check

パターン2: リファクタ + 機能変更

code

✅ 正しい順序:
  1. refactor(api): extract validation to separate module
  2. feat(api): add email format validation

理由: リファクタを先にすることで、機能追加の差分が明確になる

パターン3: テスト + 実装

code

✅ TDDスタイル:
  1. test(auth): add tests for token refresh
  2. feat(auth): implement token refresh logic

✅ 実装後テスト:
  1. feat(auth): implement token refresh logic
  2. test(auth): add tests for token refresh

どちらでも可、プロジェクトの慣習に従う

分離できない場合

密結合した変更は無理に分離しない：

code

✅ 許容される混在:
fix(database): handle connection timeout and add retry logic

理由: リトライロジックはタイムアウト対応の一部として不可分

スコープ決定ガイド

スコープの粒度

code

プロジェクト構造例:
src/
├── auth/          → scope: auth
├── api/
│   ├── users/     → scope: api または users
│   └── products/  → scope: api または products
├── database/      → scope: database, db
└── utils/         → scope: utils (または省略)

スコープ選択フロー

code

1. 影響範囲は単一モジュール？
   → Yes: そのモジュール名をスコープに
   → No: 次へ

2. 影響範囲は関連する複数モジュール？
   → Yes: 親カテゴリまたは機能名をスコープに
   → No: 次へ

3. プロジェクト全体に影響？
   → スコープ省略

プロジェクト履歴からの学習

bash

# 既存スコープの確認
git log --oneline -50 | grep -oP '(?<=\()[^)]+(?=\))' | sort | uniq -c | sort -rn

# 出力例:
#   12 auth
#    8 api
#    5 hooks
#    3 database

既存パターンに従うことで一貫性を保つ。

本文（Body）の書き方

本文が必要なケース

•

WHYが自明でない場合

code

refactor(api): change error response format

The previous format was inconsistent with REST best practices
and caused confusion in client error handling. New format
follows RFC 7807 Problem Details specification.

•

複数の関連変更がある場合

code

feat(auth): implement OAuth2 PKCE flow

Changes include:
- Add code verifier generation
- Implement code challenge creation
- Update token exchange to include verifier
- Add state parameter for CSRF protection

•

Breaking Changesがある場合

code

feat(api)!: require authentication for all endpoints

Previously, read-only endpoints were public. This change
requires all API calls to include a valid JWT token.

Migration:
1. Generate API token in dashboard
2. Add Authorization header to all requests
3. Update client SDK to v2.0+

BREAKING CHANGE: All endpoints now require authentication.

本文のフォーマット

code

<type>(<scope>): <description>
                                    ← 空行必須
<body - 72文字で折り返し>
                                    ← 空行
<footer>

タイプ選択の詳細判断

境界ケース

変更内容	判断	理由
パフォーマンス改善のためのリファクタ	`perf`	目的がパフォーマンス
バグを直しながらリファクタ	`fix`	バグ修正が主目的
新機能のためのリファクタ	`refactor` → `feat`	2コミットに分離
ドキュメント内のコード例更新	`docs`	ドキュメントが主
コメントのみの追加	`docs` または省略	プロジェクト慣習による
依存関係のセキュリティ更新	`chore` または `fix`	脆弱性対応なら`fix`

セマンティックバージョニングへの影響

タイプ	バージョン影響
`feat`	MINOR (0.x.0)
`fix`	PATCH (0.0.x)
`feat!`, `fix!`	MAJOR (x.0.0)
その他	バージョン影響なし

エッジケース対処

Pre-commit hookによる変更

bash

# Hook実行後にファイルが変更された場合
git status  # 変更を確認

# 安全にamendできる条件:
# 1. 直前のコミットが自分のもの
# 2. まだpushしていない

git log -1 --format='%an %ae'  # 作者確認
git status | grep "Your branch is ahead"  # push状態確認

# 条件を満たせばamend
git add -u
git commit --amend --no-edit

空コミット防止

bash

# ステージングエリアの確認
git diff --cached --name-only

# 空の場合はコミットしない
if [ $(git diff --cached --name-only | wc -l) -eq 0 ]; then
  echo "Nothing staged for commit"
fi

部分的なファイルステージング

bash

# ファイル内の特定の変更のみステージ
git add -p <file>

# または git-sequential-stage を使用（/commit コマンド）
git-sequential-stage -patch="changes.patch" -hunk="file.py:1,3"

チェックリスト

コミット前の最終確認:

• タイプは変更の主目的を反映している
• スコープは既存パターンと一致している
• 説明文は現在形・命令形
• 72文字以内に収まっている
• 複数種類の変更が混在していない
• Breaking changesは感嘆符(!)およびBREAKING CHANGE:で明示
• 本文はWHYを説明している（必要な場合）

commit-conventions

Commit Conventions Guide

複雑なケースの判断基準

いつこのスキルが必要か

変更の分離戦略

混在パターンと分離方法

分離できない場合

スコープ決定ガイド

スコープの粒度

スコープ選択フロー

プロジェクト履歴からの学習

本文（Body）の書き方

本文が必要なケース

本文のフォーマット

タイプ選択の詳細判断

境界ケース

セマンティックバージョニングへの影響

エッジケース対処

Pre-commit hookによる変更

空コミット防止

部分的なファイルステージング

チェックリスト

関連ツール