organize-commits

コミットを整理する

ブランチの作業を、レビュアーが一度に1つずつコミットを読める順序に組み直します。すべてのコミットが単独でビルドでき、テストに合格することが条件です。

整理されたコミットログは、理解が長く残る場所の1つです。各コミットメッセージには、差分だけでは表現できない「理由」が記され、コミットの順序そのものが、変更に至った考え方をレビュアーに伝えます。このスキルでは、その成果物を作成します。

原則

すべてのコミットは、次の条件をすべて満たす必要があります。

1. 論理的な変更は1つだけにする。 リファクタリングと動作変更を決して混在させないでください。フォーマットや名前変更などの機械的な変更は、独立したコミットにします。
2. その時点の履歴でビルドでき、テストに合格する。 「次のコミットで修正する」という負債を残してはいけません。それがあってこそ、git bisect が意味を持ちます。
3. メッセージで理由を説明する。 何を変更したかは差分で確認できます。制約、却下した代替案、見えにくい不変条件を記録してください。
4. 順序にも意味を持たせる。 一般的には、準備のための整理・リファクタリング → インフラストラクチャや追加機能 → 新しい動作 → 呼び出し元の移行 → 不要なコードの削除 → テスト・ドキュメントの順です。後のコミットで、それ以前の変更を部分的に取り消してはいけません。
5. 小さく保つ。 一度に読める大きさにします。大きすぎると感じたら、ほとんどの場合、さらに分割できます。

手順

1. 現状を評価する

次のコマンドを並行して実行します。

git status
git log --oneline @{upstream}..HEAD   # no upstream → use main/master
git diff --stat <base>...HEAD
git diff <base>...HEAD                # skim the full diff once

<base> は通常 origin/main または main です。不明な場合はユーザーに確認してください。

2. 変更を論理的な単位にまとめる

差分全体を読み、「レビュアーにどう説明するか」という視点でグループ分けします。たとえば、次のようになります。

• 準備のためのリファクタリング（動作変更なし）
• 新しいモジュール／型／ヘルパー（まだ呼び出されない）
• 新しい動作
• 呼び出し元の移行（旧 → 新）
• 不要なコードの削除
• テスト／ドキュメント

グループ分けの概要を簡潔に示し、合意を得てください。（コミットが3つを超える場合は、先に提示するのがほぼ常に適切です。）

3. 安全策を講じる

書き換えを始める前に、バックアップブランチを作成します。

git branch backup/<current>-$(date +%s)

作業ツリーに未追跡または未コミットの変更がある場合は、先にスタッシュするかコミットし、その旨をユーザーに伝えてください。

4. 組み直し方法を選ぶ

状況に合った方法を提案します。

• 単一コミット、または作業ツリーのみの場合：git reset を実行し、ハンクごとに再コミットします。

  git reset <base>            # or reset --soft HEAD~N
  git add -p                  # pick hunks per group
  git commit -m "..."
  

• 複数のコミットを並べ替える／まとめる場合：git rebase -i <base> を使います。ただし、-i は対話型で、この環境では直接実行できません。 ユーザー自身が実行するコマンドを案内するか、git rebase --onto と cherry-pick を組み合わせて非対話的に処理してください。
• ファイル単位できれいに分割できる変更の場合：git add <file> とコミットを繰り返します。
• 1つのファイル内で分割する変更の場合：git add -p を使います（ハンクの分割には s、行単位の編集には e）。

5. 各コミットを検証する

これが「bisect 可能」にするための要です。各コミットを作成したら、次を実行します。

<build command>    # project-specific; at minimum type check / lint
<test command>     # at minimum the fast unit tests

失敗した場合は、そのコミットを修正します（git commit --amend、または fixup と autosquash を使います）。「次のコミットで修正される」と考えて先に進んではいけません。

コミットの並び全体ができたら、もう一度検証します。

git rebase <base> --exec '<build>; <test>'

これに合格すれば、各コミットが個別に合格することを確認できます。

6. コミットメッセージ

件名行（約50文字）＋空行＋本文（72文字で折り返し）とします。本文では、次の内容を説明します。

• この変更が必要な理由
• 検討して却下した代替案（ある場合）
• レビュアーが見落とす可能性のある制約／不変条件
• このコミットが一連の変更のどこに位置するか（例：「呼び出し元の移行は後続のコミットで行います」）

まずリポジトリの既存のスタイルを確認し（git log）、conventional commits を使っている場合はそれに従ってください。

7. プッシュ

すでにプッシュ済みのブランチには、強制プッシュが必要です。必ず先にユーザーから明示的な承認を得て、--force-with-lease を使ってください。 main/master には強制プッシュしないでください。

git push --force-with-lease -u origin <branch>

安全ルール

• バックアップブランチを作らずに、履歴を書き換えてはいけません。
• rebase -i は対話型です。この環境で直接実行せず、ユーザーに案内するか、非対話型の代替手段を使ってください。
• ユーザーから明示的に依頼された場合を除き、--no-verify や、リース指定なしの git push -f は使わないでください。
• ビルド／テストコマンドが不明な場合は、CLAUDE.md、package.json、Makefile、README を確認してください。それでも不明な場合は、ユーザーに確認してください。
• 1つのコミットが大きくなりすぎた場合は、作業を止めて、さらに分割するかユーザーと相談してください。

アンチパターン

• 最終履歴に「WIP」「fix」「address review」のような意味のないメッセージを残す
• 2つ目のコミットで1つ目の変更を部分的に取り消す形で、同じファイルを2回変更する
• リファクタリングと動作の変更を1つのコミットに混在させる
• 実装より前にテストのみのコミットを置く（そのコミットではテストが失敗し、二分探索が機能しなくなります）
• 最後に一度だけ npm test を実行して「パスしました」と報告する。二分探索を有効にするには、各コミットでテストがパスする必要があります