git-commit-helper

Git コミットヘルパー

概要

Conventional Commits の基準を適用し、セマンティックバージョニングの判断をガイドし、変更履歴を生成して、コミットメッセージの品質を確保します。このスキルは、バージョン管理におけるコミュニケーションのための体系的なアプローチを提供し、自動化ツールの利用と明確なプロジェクト履歴を可能にします。

フェーズ 1：変更を分析する

ステージされた差分を分析し、何が変更されたかを把握します。

git diff --cached --stat
git diff --cached

1. 影響を受けるファイルとモジュールを特定する
2. 変更の性質（新機能、バグ修正、リファクタリングなど）を判断する
3. 変更によって互換性が損なわれるか確認する（API の変更、機能の削除、契約の変更）

STOP — 変更の全体像を把握するまで、コミットメッセージを書いてはいけません。

フェーズ 2：分類して作成する

コミット種別の判断表

種別	使用する場合	バージョンの更新	例
feat	ユーザー向けの新機能	MINOR	feat(auth): add OAuth2 login flow
fix	ユーザー向けのバグ修正	PATCH	fix(api): handle null response in user endpoint
docs	ドキュメントのみの変更	なし	docs(readme): update installation steps
style	書式設定、セミコロンの不足など	なし	style(lint): fix trailing whitespace
refactor	動作を変更しないコードの変更	なし	refactor(utils): extract date formatting helpers
perf	パフォーマンスの改善	PATCH	perf(query): add index for user lookup
test	テストの追加または修正	なし	test(auth): add login failure scenarios
chore	メンテナンス、依存関係、ツール	なし	chore(deps): update typescript to 5.4
ci	CI/CD 設定の変更	なし	ci(github): add Node 20 to test matrix
build	ビルドシステムまたは外部依存関係	なし	build(webpack): optimize chunk splitting

Conventional Commit の形式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

スコープのガイドライン

スコープには、影響を受けるコードベースの領域を指定します。

スコープの方針	例	使用する場合
モジュール別	auth、billing、dashboard、api	機能ごとに構成されたコードベース
レイヤー別	db、ui、middleware、config	レイヤーごとに構成されたコードベース
パッケージ別	@app/core、@app/shared	モノレポ
一般	deps、ci、lint、types	複数の領域にまたがる変更

ルール：

• 小文字の kebab-case を使用する
• プロジェクト内で一貫性を保つ
• 任意ですが、定期的に 10 ファイル以上を変更するプロジェクトでは推奨されます
• 本当に複数の領域にまたがる変更ではスコープを省略する

説明のルール

• 命令形を使う：「added」や「adds」ではなく「add」
• 先頭の文字は大文字にしない
• 末尾にピリオドを付けない
• 最大 72 文字（種別 + スコープ + 説明の合計）
• どのように変更したかではなく、何を変更したかを記述する

フェーズ 3：コミットメッセージを書く

本文のガイドライン

feat(cart): add quantity update functionality

Users can now change item quantities directly in the cart
without removing and re-adding items. The quantity selector
supports values from 1 to 99 with real-time price updates.

Closes #234

• 72 文字で折り返す
• 変更を行った理由（動機）を説明する
• 変更内容を大まかに説明する
• 説明とフッターは空行で区切る

破壊的変更

feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns a paginated
response object instead of a plain array. Clients must update
to read from the `data` field.

Migration guide:
- Before: const users = await fetch('/api/users').json()
- After:  const { data: users } = await fetch('/api/users').json()

破壊的変更を示す方法は 2 つあります。

1. 種別／スコープの後に ! を付ける：feat(api)!: description
2. BREAKING CHANGE: フッターを付ける（移行の詳細を記述できます）

どちらの方法でも MAJOR バージョンが更新されます。

STOP — コミットする前に、コミットメッセージをユーザーに提示して承認を得てください。

フェーズ 4：バージョンへの影響を評価する

セマンティックバージョニング（SemVer）：MAJOR.MINOR.PATCH

要素	更新する場合	例
MAJOR	破壊的変更（互換性のない API の変更）	1.0.0 -> 2.0.0
MINOR	新機能（後方互換性あり）	1.0.0 -> 1.1.0
PATCH	バグ修正（後方互換性あり）	1.0.0 -> 1.0.1

バージョン更新のルール

Commits since last release:
  fix(auth): handle expired tokens       -> PATCH
  feat(search): add fuzzy matching       -> MINOR (overrides PATCH)
  fix(ui): correct button alignment      -> already MINOR
  feat(api)!: change response format     -> MAJOR (overrides MINOR)

Result: MAJOR bump (highest wins)

プレリリースバージョン

1.0.0-alpha.1    -> Early testing
1.0.0-beta.1     -> Feature complete, testing
1.0.0-rc.1       -> Release candidate
1.0.0            -> Stable release

初期開発（0.x.y）

• 0.1.0：最初の利用可能なバージョン
• 0.x.y：API は安定していません。MINOR に破壊的変更が含まれる場合があります
• 1.0.0：最初の安定版リリース。SemVer のルールがすべて適用されます

フェーズ 5：変更履歴を生成する（該当する場合）

CHANGELOG.md の形式

# Changelog

## [1.2.0] - 2025-03-15

### Added
- Fuzzy search matching for product catalog (#234)
- Bulk export functionality for reports (#245)

### Fixed
- Handle expired authentication tokens gracefully (#230)
- Correct button alignment on mobile viewports (#232)

### Changed
- Update TypeScript to 5.4 (#240)

## [1.1.0] - 2025-02-28
...

コミットタイプと変更履歴セクションの対応

コミットタイプ	変更履歴セクション
feat	追加
fix	修正
perf	パフォーマンス
refactor	変更
docs	ドキュメント
BREAKING CHANGE	破壊的変更（リリースの先頭）
chore、ci、build、style、test	通常は除外

自動化ツール

ツール	使用例
conventional-changelog	Git の履歴から変更履歴を生成
semantic-release	バージョン管理と公開を完全に自動化
changeset	モノレポ用の手動変更セットファイル
release-please	Google のリリース自動化

コミットメッセージの品質チェックリスト

必須項目

• Conventional Commit 形式を使用している（type(scope): description）
• タイプが許可リストに含まれている
• 説明が命令形になっている
• 説明の長さが全体で72文字未満である
• 説明の末尾にピリオドがない
• 破壊的変更が明確に示されている

推奨項目

• スコープが影響を受ける領域を正確に示している
• 本文で「何を」だけでなく「なぜ」を説明している（重要な変更の場合）
• イシュー／チケット番号を参照している（Closes #123、Refs #456）
• コミットごとに論理的な変更が1つである（アトミックなコミット）
• メインブランチの履歴に「WIP」や「temp」のコミットがない

コミット分割ガイド

分割する場合の判断表

条件	対応
異なるモジュール／機能への変更	個別のコミットに分割する
リファクタリングと機能追加の組み合わせ	分割する：最初にリファクタリング、次に機能追加
既存コードへのテスト追加と新機能の追加	分割する：最初にテスト、次に機能追加
設定変更とコード変更	個別のコミットに分割する
複数ファイルにまたがる単一の論理的な変更	1つのコミットにまとめる

分割方法

# Interactive staging for partial commits
git add -p                    # Stage hunks interactively
git add path/to/specific/file # Stage specific files

# Example: split refactor + feature
git add src/utils/date.ts
git commit -m "refactor(utils): extract date formatting helpers"

git add src/components/DatePicker.tsx src/components/DatePicker.test.tsx
git commit -m "feat(ui): add date range picker component"

アンチパターン／よくある間違い

アンチパターン	問題点	代わりにすること
新機能に fix タイプを使う	バージョン更新の自動化を誤らせます	新機能には feat を使います
意味のある履歴をスカッシュする	開発プロセスの背景が失われます	アトミックなコミットを維持し、WIP のみをスカッシュします
フックをスキップするために --no-verify を使う	品質ゲートを回避します	代わりにフックの失敗を修正します
公開済み／プッシュ済みのコミットを修正する	他の開発者の履歴を壊します	代わりに新しいコミットを作成します
空のコミットメッセージや「.」だけのメッセージ	将来読む人に情報をまったく伝えません	内容が分かるメッセージを書きます
フォーマット変更とロジック変更を混在させる	片方だけを元に戻せません	個別のコミットに分けます
差分の内容を重複して「XをYに変更」と書く	差分以上の情報が加わりません	変更した理由を説明します
20個以上のファイルに触れる巨大なコミット	レビューも二分探索もできません	論理的でアトミックなコミットに分割します

統合ポイント

スキル	統合内容
finishing-a-development-branch	スカッシュコミットのメッセージは Conventional Commit 形式に従います
code-review	コミットの品質はレビューのチェックリストに含まれます
deployment	バージョン更新によってリリースパイプラインが起動します
planning	コミットのスコープは計画タスクの粒度に合わせます
verification-before-completion	コミット前にテストがパスすることを確認します

スキルの種類

FLEXIBLE — Conventional Commit 形式を強く推奨しますが、既存のプロジェクト規約に合わせて調整できます。Conventional Commit を使う場合、バージョン更新のルールは決定論的です。変更履歴のセクションはコミットタイプから直接対応付けられます。