レガシー移行で効いた「1ファイル 1 目的コミット」戦略

なぜ書いたか

AIに実装させると、放っておけば1コミットに20ファイル500行みたいな変更が入ってきます。レビューする側は地獄ですし、何か問題があっても「どこを戻せばいいか」が分かりません。今回は、コミット粒度を 1目的単位 に切り刻んでから運用が安定した話です。

やったこと

ルールはひとつだけです。

1コミットは「1つの変更目的」に対応する。それ以上は混ぜない。

具体的には、たとえばあるスライスでは：

• コミットA: DTOに新しいフィールドを追加
• コミットB: APIでそのフィールドを返すマッピングを追加
• コミットC: Blazor側のモデル / サービスでマッピングを受ける
• コミットD: 画面にフィールドを表示するUI

を別々のコミットとして積みます。各コミットでビルドが通る状態にしておくのがポイントです。

何が変わったか

コミット粒度を変えただけで、3つのコストが下がりました。

• レビューコスト: 差分が小さいので、Reviewer Sub Agentが追える。1コミット数十行までなら指摘の精度も上がる
• ロールバックコスト: 「UIだけ戻したい」「DTO追加だけ残したい」が即できる
• 再着手コスト: 履歴を読むだけで「何を、どの順で、なぜそうしたか」が分かる

特にレビューコストはAIベースのフローでは効きます。差分が大きすぎるとSub Agentも粒度の粗い指摘しかできなくなります。

わかったこと

• AIは放っておくと変更を巨大化させがちなので、コミット粒度は 明示的に縛らないと崩れます
• 「1ファイル1目的」は字面どおりではなく「1目的のために必要な最小ファイル群」と読むのが実用的。DTO追加にはAPIのマッピングまで含む、など
• 各コミットでビルドが通る状態を維持するのは最初は面倒ですが、これがないとbisectも難しくなります

次にやること / 未解決の問題

• コミットメッセージのフォーマットがまだ統一されていない。feat(scope): 系のプレフィクスをルール化したい
• 「DTOだけ追加してマッピングは次のコミット」のような中間状態のコミットは、buildが通らない瞬間ができることもある。どこまで厳密に通すかは継続調整中