既存コードを壊さないための「差分最小主義」

なぜ書いたか

AIに「この画面に列を1つ追加して」と頼むと、関係のないリファクタや書式整形まで一気にやってくることがあります。変更範囲が広いPRは、たとえ意図が良くてもデグレが入りやすい。今回は、明示的に「最小差分」を縛るルールにした話です。

やったこと

3つだけ守るようにしました。

1. 変更計画を最小差分で立てる: 「DTO追加 → APIマッピング → UI表示」のように、影響線を1本に絞る
2. 段階反映: 各ステップでbuild / 動作確認を挟む。複数ステップを1回でやらない
3. 副作用は別PR: リファクタ・書式整形は混ぜない

具体例

たとえば「画面に1列追加する」スライスは、こう刻みます。

• ステップA: DTO（共有契約）にフィールドを追加。build確認
• ステップB: APIのマッピングでフィールドを返す。build + 単体テスト
• ステップC: Blazorのモデル / サービスでフィールドを受ける
• ステップD: 画面に列を出す。手動確認

各ステップで触るファイルは限定的で、ロールバックも段階的にできます。AIに最初に「この順で、各ステップでbuildを通してから次に進む」と指示しておくと、勝手に全部やろうとして失敗するパターンを防げます。

わかったこと

• 「最小差分」は字面どおりではなく、1つの目的を達成する最小ファイル群 という意味
• AIは最初に投げた指示の範囲を超えて触ろうとする傾向がある（特に書式・フォーマット・周辺リファクタ）。「最小差分以外は触らない」を明示しないと崩れます
• レビュー観点に「このPRで必要な変更だけが含まれているか」を入れると、不要なdiffが削れます

トレードオフ

最小差分主義はトレードオフを抱えています。

• コミット数が増える: 履歴が長くなる
• 中間状態がbuildを通らないことがある: 厳密にすると進みが遅い
• 関連リファクタの機会を失う: ついでに直したい衝動を抑える必要がある

このうち最初の2つは妥協できますが、3つ目だけは「別PRを切る」という運用で吸収します。リファクタ衝動を捨てると技術負債が溜まりますが、混ぜると確実にデグレします。

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

• 「ついでに直したい」を逃さないため、別PRを起こすコストをもう少し下げたい（テンプレ化、ブランチ命名規則）
• 中間状態でbuildが通らないコミットを許容するかどうか、まだチームでも迷っている