git-commit-granularity

name: git-commit-granularity description: Gitコミットの粒度（サイズ・単位）ベストプラクティスに従い、アトミックで単一概念のコミットへ分割・整形するガイドを提供する。git add -pによるハンクステージング、セマンティックギャップの回避、クリーンな履歴の構築手順をカバーする。コミット作成時、既存コミットのリファクタリング前、コードレビューでのコミット単位の見直し時に使う。コンフリクト解消、PRマージ、リポジトリの初期セットアップには使わない。

Git コミット粒度ガイド

手順

Step 1: 現在の差分を把握する

1. 作業ツリーの変更全体を確認する:

   git status
   git diff --stat
   

2. ステージ済みの変更を確認する:

   git diff --cached --stat
   

3. 変更が複数の目的・概念を含む場合は Step 2 へ進む。単一概念であれば Step 4 へスキップする。

Step 2: 差分を論理グループへ分類する

1. 差分を論理グループ（バグ修正・機能追加・リファクタリング・タイポ修正など）へ分類する。
2. セマンティックギャップ（コードが壊れた中間状態）が生じないかを確認する。判断基準はスキル同梱の references/granularity-rules.md を読む。
3. 各グループが「関数の移動」を伴う場合は、削除と追加を必ず同一コミットに含める（セマンティックギャップ防止）。

Step 3: ハンク単位でステージングする（git add -p）

1. インタラクティブなハンクステージングを起動する:

   git add -p
   

2. 各ハンクに対してキーを入力する:
   • y — 現在のグループに属するハンクを採択
   • n — 次のコミットに回す
   • s — ハンクをさらに分割（より細かい粒度が必要な場合）
   • e — ハンクを手動編集（行単位の選択が必要な場合）
   • q — ステージング終了
3. ステージ内容を確認する:

   git diff --cached
   

4. 意図した変更のみが含まれていることを確認する。含まれていない場合は git restore --staged <file> でアンステージし直す。

Step 4: コンパイル／テストの通過確認

1. ステージ済みの差分のみで、コードが動作する状態を維持しているか確認する。
2. テストスイートまたはビルドを実行する:

   # プロジェクトに合わせて選択
   npm test / yarn test / pnpm test
   go test ./...
   pytest
   make build
   

3. ビルドまたはテストが失敗した場合は Step 2 へ戻り、セマンティックギャップが生じていないか再確認する。

Step 5: コミットメッセージを作成する

1. コミットメッセージの書式を確認する: スキル同梱の references/granularity-rules.md
2. Conventional Commits 形式で書く:

   <type>(<scope>): <概要>（50文字以内）
   
   [本文: 変更した理由、背景（任意）]
   
   [フッター: BREAKING CHANGE / 関連 issue 番号（任意）]
   

3. type の選択例:
   • fix — バグ修正
   • feat — 機能追加
   • refactor — 振る舞いを変えないリファクタリング
   • chore — ビルド・設定変更
   • docs — ドキュメントのみの変更
   • style — フォーマット・タイポ修正

Step 6: コミットを実行する

1. コミットを実行する:

   git commit
   

2. 複数のグループが残っている場合は Step 3 へ戻り、次のグループをステージして繰り返す。
3. すべてのグループをコミットし終えたら、履歴を確認する:

   git log --oneline -n 10
   

Step 7: 既存コミットの整理（Push 前のみ）

1. リモートへの Push 前で、かつローカル履歴が冗長な場合はインタラクティブリベースで整理する:

   git rebase -i HEAD~<対象コミット数>
   

2. pick を squash（s）または fixup（f）へ変更して論理的にまとめる。
3. reword（r）でコミットメッセージを修正する。
4. 注意: すでに Push 済みのコミットには rebase -i を使わない。

エラーハンドリング

• git add -p でハンク分割後にビルドが壊れる場合は、セマンティックギャップが発生している。削除と追加が分離されていないかスキル同梱の references/granularity-rules.md を再確認する。
• コミット単位の判断が難しい場合はスキル同梱の scripts/check_granularity.py を実行して差分の概要を得る。
• git rebase -i で競合が発生した場合は git rebase --abort で中断し、安全な状態へ戻す。
• Conventional Commits の type 選択が迷う場合はスキル同梱の references/granularity-rules.md の判定フローを参照する。