はじめに

AI コーディングエージェントに修正を頼むと、依頼範囲外のコードまで「親切に」整形・リファクタ・整理されて diff が膨らむことがあります。

この記事では、Andrej Karpathy の LLM コーディング観察を整理した OSS（forrestchang/andrej-karpathy-skills）に出てくる Surgical Changes（外科的変更）原則を 1 つのルールファイルにして CLAUDE.md / AGENTS.md から先に読ませることで、diff が依頼範囲に収まるようにした運用をまとめます。

対象は次のような人を想定しています。

Claude Code や Codex などで修正依頼すると関係ないコードまで触られる経験がある
AI が生成する diff が大きすぎてレビューが大変
AI のリファクタ意欲を抑える明確なルールが欲しい

詰まったポイント

AI に小さな修正を依頼するたびに、次のことが起きていました。

「ここの引数を 1 つ追加して」と頼んだら隣の関数のフォーマットも勝手に整えられた
「バグだけ直して」と頼んだら関係ない dead code を削除された（後で必要だった）
「import を 1 つ追加して」と頼んだら未使用と判断された別の import まで消された

diff が膨らむと、その diff のどこが依頼通りでどこが余計な親切心かをレビューする時間が増えます。1 件 1 件は小さいですが、1 日に何度も繰り返すと作業の遅さに直結します。

採用したルール（先渡しテキスト）

上記 OSS を出典として karpathy-coding-principles.md という 1 ファイルを作り、CLAUDE.md から @rules/karpathy-coding-principles.md で先頭近くに import しています。中心は「Surgical Changes」セクションです。

## Surgical Changes（外科的変更）

**触るのは必要な箇所だけ。自分が作ったゴミだけ片付ける。**

既存コードを編集するとき：
- 隣接コード・コメント・フォーマットを「改善」しない
- 壊れていないものをリファクタしない
- 既存スタイルに合わせる（自分なら違う書き方をしても）
- 関係ない dead code を見つけたら**削除せず言及する**

自分の変更が orphan を生んだとき：
- 自分の変更で不要になった import / 変数 / 関数は削除する
- 以前から存在する dead code は触らない

**テスト**: 変更した行がすべてユーザーのリクエストに直結しているか？

ポイントは次の 3 つです。

1. 「触らない範囲」を明示する

「隣接コード・コメント・フォーマットを改善しない」と書くと、AI の「ついでに直してあげよう」が止まります。スタイルが違って気持ち悪いと AI が判断しても、依頼が来ていなければ触らないという行動規範になります。

2. orphan と dead code を分ける

自分の変更で不要になった import や変数は削除して構いません。一方で、以前から存在する dead code は触らないと明示します。これを分けないと、AI が「使われていないから消そう」と判断して、別の場所から呼ばれる予定だったコードまで消える事故が起きます。

3. 自己チェックの問いを書く

最後の「変更した行がすべてユーザーのリクエストに直結しているか？」が AI にとっての自己レビュー用の問いになります。これを書いておくと、diff を出力する直前に AI 自身が「これは依頼に直結している？」と検証する動作を引き出しやすくなります。

落とし穴

Surgical Changes だけだと不要機能追加は防げない

このルールは「既存コードを触る範囲」を絞ります。新規追加で「ついでにこんな機能も入れておきました」を防ぐには、別の原則が必要です。同じファイル内に Simplicity First も並べました。

## 不要機能を書かない（Simplicity First）

- 頼まれていない機能を追加しない
- 単一用途のコードに抽象化を持ち込まない
- 「柔軟性」「設定可能性」は明示的に求められるまで不要
- 200行で書けるものを50行で書けないか常に問う

既存スタイルが本当に悪い時は別タスクで依頼する

「既存スタイルに合わせる」を強く書いたので、リファクタが本当に必要な場合はそれを別タスクとして明示的に依頼します。Surgical Changes ルール下で「ついでにリファクタ」を期待すると効きません。

AI レビュー時にも同じルールを適用する

AI にコードレビューさせる時、レビュー側も「ここも直すべき」と無関係指摘をしがちです。レビューを依頼する時のプロンプトにも、Surgical Changes ルールを満たしているかという観点で見るように指示しておくと、レビュー指摘自体が依頼範囲に収まります。

実運用での変化

定量計測ではなく体感ベースですが、ルール導入後に次が変わりました。

1 タスクあたりの diff 行数が体感で半分以下
関係ないファイルが Modified に出てこない
「これ依頼してないけど触られた」を発見してレビューで指摘し直す回数が減った
AI 自身が「この変更は依頼の範囲外なので削除しました」と diff の中で自己訂正する場面が増えた

まとめ

AI の diff が膨らむ問題は「触らない範囲」を明示するルールで抑える
1 ファイル 1 ルール（Surgical Changes）として CLAUDE.md や AGENTS.md から import して常時適用する
「変更した行がすべて依頼に直結しているか」を自己チェックの問いとして書く
新規追加に対する「ついで機能」防止には Simplicity First を併用する

AI に任せる範囲が増えるほど、diff レビューのコストが作業時間を支配します。ルールを 1 枚追加するだけで diff の質が変わるので、効果対コストが高い設定です。

参考

Andrej Karpathy の LLM コーディング原則を整理した OSS リポジトリ: https://github.com/forrestchang/andrej-karpathy-skills