AI에게 "수정해줘"라고 부탁하면 무관한 코드까지 건드리는 문제를 Surgical Changes 규칙으로 억제하기

AI 코딩 에이전트에게 수정을 요청하면, 의뢰 범위를 벗어난 코드까지 "친절하게" 정렬, 리팩토링(Refactor), 정리되어 diff가 불어나는 경우가 있습니다.

이 기사에서는 Andrej Karpathy의 LLM 코딩 관찰 내용을 정리한 OSS(forrestchang/andrej-karpathy-skills)에 나오는 Surgical Changes(외과적 변경) 원칙을 하나의 규칙 파일로 만들어, CLAUDE.md / AGENTS.md에서 먼저 읽게 함으로써 diff가 의뢰 범위 내에 머물도록 한 운영 방법을 정리합니다.

대상은 다음과 같은 분들을 상정하고 있습니다.

• Claude Code나 Codex 등으로 수정 요청을 하면 관계없는 코드까지 건드리는 경험이 있는 분
• AI가 생성하는 diff가 너무 커서 리뷰가 힘든 분
• AI의 리팩토링 의욕을 억제할 명확한 규칙이 필요한 분

AI에게 작은 수정을 요청할 때마다 다음과 같은 일이 일어나고 있었습니다.

• "이곳의 인수를 하나 추가해줘"라고 부탁했더니 옆 함수(Function)의 포맷도 멋대로 정리됨
• "버그만 고쳐줘"라고 부탁했더니 관계없는 dead code를 삭제함 (나중에 필요했던 코드)
• "import를 하나 추가해줘"라고 부탁했더니 사용되지 않는다고 판단된 다른 import까지 삭제됨

diff가 불어나면, 그 diff 중 어디가 의뢰대로이고 어디가 불필요한 친절함인지 리뷰하는 시간이 늘어납니다. 하나하나은 작지만, 하루에 몇 번씩 반복되면 작업 속도 저하로 직결됩니다.

위 OSS를 출처로 하여 karpathy-coding-principles.md라는 파일 하나를 만들고, CLAUDE.md에서 @rules/karpathy-coding-principles.md로 파일 상단 근처에 import 하고 있습니다. 핵심은 「Surgical Changes」 섹션입니다.

## Surgical Changes (외과적 변경)
**건드리는 것은 필요한 부분만. 자신이 만든 쓰레기만 치운다.**
기존 코드를 편집할 때:
...

포인트는 다음 세 가지입니다.

"인접 코드, 주석, 포맷을 개선하지 않는다"라고 적으면, AI의 "하는 김에 고쳐주자"라는 마음을 멈출 수 있습니다. 스타일이 달라서 보기 불편하다고 AI가 판단하더라도, 의뢰가 없다면 건드리지 않는다는 행동 규범이 됩니다.

자신의 변경으로 인해 불필요해진 import나 변수는 삭제해도 좋습니다. 반면, 이전부터 존재하던 dead code는 건드리지 않는다고 명시합니다. 이를 구분하지 않으면, AI가 "사용되지 않으니까 지우자"라고 판단하여 다른 곳에서 호출될 예정이었던 코드까지 삭제하는 사고가 발생합니다.

마지막으로 "변경한 행이 모두 사용자의 요청과 직결되어 있는가?"가 AI에게 있어 자기 리뷰(Self-review)를 위한 질문이 됩니다. 이를 적어두면, diff를 출력하기 직전에 AI 스스로가 "이것은 의뢰와 직결되는가?"라고 검증하는 동작을 끌어내기 쉬워집니다.

이 규칙은 "기존 코드를 건드리는 범위"를 좁힙니다. 신규 추가 시 "하는 김에 이런 기능도 넣어두었습니다"를 방지하려면 별도의 원칙이 필요합니다. 같은 파일 내에 Simplicity First(단순성 우선)도 함께 배치했습니다.

## 불필요한 기능을 작성하지 않는다 (Simplicity First)
- 요청받지 않은 기능을 추가하지 않는다
- 단일 용도의 코드에 추상화를 도입하지 않는다
...

"기존 스타일에 맞춘다"를 강력하게 적었기 때문에, 리팩토링이 정말 필요한 경우에는 그것을 별도의 태스크로 명시적으로 의뢰합니다. Surgical Changes 규칙 하에서 "하는 김에 리팩토링"을 기대하면 효과가 없습니다.

AI에게 코드 리뷰를 시킬 때, 리뷰 측도 "여기도 고쳐야 한다"라며 무관한 지적을 하기 쉽습니다. 리뷰를 의뢰할 때의 프롬프트에도 Surgical Changes 규칙을 충족하고 있는지 관점에서 보도록 지시해 두면, 리뷰 지적 자체도 의뢰 범위 내에 머물게 됩니다.

정량적 측정은 아니지만 체감상 규칙 도입 후 다음과 같이 변했습니다.

• 태스크당 diff 행수가 체감상 절반 이하로 감소

• 관계없는 파일이 Modified로 나타나지 않음

• "이거 의뢰하지 않았는데 건드렸다"를 발견하여 리뷰에서 다시 지적하는 횟수가 감소

• AI 스스로가 "이 변경은 의뢰 범위를 벗어났으므로 삭제했습니다"라고 diff 안에서 자기 정정하는 장면이 늘어남

• AI의 diff (차이점)가 비대해지는 문제는 "건드리지 않을 범위"를 명시하는 규칙으로 억제한다

• 1 파일 1 규칙 (Surgical Changes)으로서 CLAUDE.md 또는 AGENTS.md에서 import 하여 상시 적용한다

• "변경한 행이 모두 의뢰와 직결되어 있는가"를 자기 점검(Self-check) 질문으로 작성한다

• 신규 추가에 따른 "덤으로 기능 추가"를 방지하기 위해서는 Simplicity First를 병용한다

AI에게 맡기는 범위가 늘어날수록, diff 리뷰 비용이 작업 시간을 지배하게 됩니다. 규칙을 한 장 추가하는 것만으로도 diff의 질이 달라지므로, 비용 대비 효과가 높은 설정입니다.

• Andrej Karpathy의 LLM 코딩 원칙을 정리한 OSS 리포지토리: https://github.com/forrestchang/andrej-karpathy-skills