バージョン管理

戻せることが、唯一まともに効くブレーキになる。 変更が速く大量に入る以上、個々の変更の正しさを事前に保証するのは無理になる。 決定を覆せることが、 ここでは実務の手順の話になる。

元の規範

バージョン管理（書籍第16章）、 Git の運用、 継続的インテグレーション。

とくに 壊れたら、まず戻す。

最善の直し方は、メインラインから直近のコミットを revert して、 既知の良いビルドまで戻すこと。

理由は、チームを即座に解放するから。 原因の診断と修正は、別の開発環境でやればよい。

何が崩れるか

1セッションに複数の関心事が混ざる

Git の運用は 「差分の生存期間は数時間以内」を基準にしている。 AI 駆動では、この数時間のあいだに入る変更の量が桁で増える。

そして混ざり方に癖がある。依頼が1つでも、変更は1つにならない。

頼んだこと          機能 A を足す
実際に入るもの      機能 A + 周辺のリファクタ + 型定義の整理
                    + フォーマットの差分 + 「ついでに」直したバグ

小さな変更にするが 「機能変更やバグ修正と、リファクタリングは別の変更にするのが普通はベスト」と言っているのは、 まさにこの混ざり方を防ぐためだった。

混ざると、戻せなくなる。 機能 A に問題が見つかっても、同じコミットにリファクタが入っていると revert できない。 上のブレーキが、ここで効かなくなる。

「動いている状態」の記録が飛ぶ

元の規範は、未完成のものもトランクに置く前提で書かれている。

作業はトランクに対する小さくインクリメンタルな増分として定期的にコミットする。

(出典: 未完成のものをどうトランクに置くか)

AI 駆動で崩れるのは、この「定期的に」の方。 一気に完成まで走るので、途中の動いていた状態がコミットとして残らない。 問題が出たときに戻れる地点が、着手前まで飛ぶ。

コミットメッセージが「何をしたか」で埋まる

ディスクリプションの書き方は 1行目に要約、3行目以降に「どうしてこれが最良の方法なのか」を求めている。

AI は差分から「何をしたか」を正確に書ける。 書けないのは「なぜそうしたか」の方で、 差分を要約しただけのメッセージが量産される。

元の規範が言う目的 —— 「将来の開発者が変更をディスクリプションに基づいて検索しやすいようにしておく」 —— は、差分を見れば分かることを書いても達成されない。

「壊れたら戻す」の判断が遅れる

元の規範の要点は「直し方を考えているあいだ、全員を止めておく必要はない」。

AI 駆動では、逆向きの誘惑が強くなる。 直すのが速いので「戻すより直した方が早い」に見える。 実際に速いこともあるが、外したときの損が大きい。 直したつもりが別の問題を足しているかどうかは、直した直後には分からない。

どう仕掛けるか

コミットの単位を、依頼の単位と切り離す

1依頼 = 1コミットにしない。 1つの関心事が終わったところで刻む。混ざりそうなら、混ぜずに順番にやらせる。

動いた時点を刻ませる

テストが通った状態を通過したら、そこでコミットする。 「全部終わってからまとめて」を避ける。 これは元の規範の「小さくインクリメンタルな増分」そのもので、 AI 相手だと明示しないと守られないだけ。

フォーマットの差分を混ぜない

フォーマッターの差分は、機能の差分を覆い隠す最大の要因。 既存のコードに手を入れる前に、フォーマットだけのコミットを先に分けるか、 そもそも触らせない。

戻せるかどうかを、完了の条件に入れる

この変更だけを revert して、他を壊さずに戻せるか

答えが「いいえ」なら、その変更は大きすぎるか、混ざっている。 行数より確実な基準になる。

そのまま貼る

CLAUDE.md に足す。 コミットメッセージを日本語にするか英語にするかは、リポジトリの既存の履歴に合わせる。

## コミット
 
- **1コミット = 1つの関心事。** 機能変更・バグ修正・リファクタリング・
  フォーマットの整形を同じコミットに混ぜない。混ざりそうなら順番に分けてやる
- **その変更だけを revert して、他を壊さずに戻せる状態を保つ。**
  戻せないなら、大きすぎるか混ざっている
- **テストが通った時点で刻む。** 全部終わってからまとめてコミットしない
- **コミットメッセージは、差分の要約ではなく理由を書く。**
  1行目に何をしたか（50字程度）、空行、それ以降に「なぜこの方法にしたか」
  「他に検討した方法があればそれを採らなかった理由」。
  差分を見れば分かることだけを書かない
- **既存の履歴の書式に合わせる。** `git log` を見てから書く
- **履歴を書き換えない。** rebase・amend・force push は、明示的に頼まれたときだけ
- **フォーマッターを既存ファイル全体にかけない。** 触った箇所だけにする

関連

• バージョン管理 — 単一バージョン原則、トランクベース開発
• Git の運用 — ブランチの運用基準、日々の操作
• 継続的インテグレーション — 壊れたら、まず戻す
• レビュー — 変更の粒度をレビュー側から見る
• 原則 — 取り消せることを担保するという方針の元