Codex에 리팩토링을 맡기기 전에 수정 범위를 명시했다

AI에게 "이 부분을 리팩토링해줘"라고 부탁하면, 목적한 변경뿐만 아니라 주변의 명명 정리(Naming), 포맷(Format), 오래된 주석 삭제까지 한꺼번에 포함될 때가 있습니다.

리뷰하는 입장에서는 기능 차분(Diff)과 정리 차분이 섞여서 무엇을 확인해야 할지 알기 어려워집니다. 그래서 Codex에게 넓은 범위의 수정을 맡기기 전에 "수정해도 좋은 범위"와 "수정하면 안 되는 범위"를 먼저 선언하는 운영 방식을 도입했습니다.

이 기사에서는 구현 전에 스코프(Scope) 선언을 두기 위한 최소한의 템플릿을 정리합니다.

완성 조건의 사전 선언 자체는 별도의 기사에서 다루고 있습니다. 이 기사에서는 특히 리팩토링 시 발생하기 쉬운 "수정 범위가 넓어져서 diff가 방대해지는" 문제에 집중합니다.

의뢰문 서두에 다음과 같은 스코프 선언을 둡니다.

작업 스코프:
- 수정 가능: src/features/schedules/ 하위, 관련 테스트
- 수정 금지: 인증, DB schema, package 업데이트, 화면 전체 디자인
...

포인트는 "할 일"뿐만 아니라 "하지 않을 일"을 동일한 입도(Granularity)로 작성하는 것입니다.

AI에게 리팩토링을 부탁하면 다음과 같은 차분이 섞이기 쉬웠습니다.

• 대상 파일 옆에 있는 무관한 함수까지 정렬됨
• 기존 주석이 "불필요"하다고 판단되어 삭제됨
• 사용하지 않는 것처럼 보이는 import가 삭제됨
• 덤으로 새로운 helper나 공통화 코드가 추가됨
• 기존의 커밋되지 않은 변경 사항을 자신의 변경 사항인 것처럼 덮어씀

어느 것이든 단독으로는 큰 사고처럼 보이지 않습니다. 하지만 리뷰 시에는 "이것이 의뢰한 변경인가", "기존 사양이 바뀌지 않았는가"를 전부 재검토해야 합니다.

원인은 리팩토링 의뢰를 목적만으로 전달했기 때문이었습니다.

"이 처리를 정리해줘"라고 말하면, AI는 정리 대상을 넓게 해석합니다. 인간이라면 암묵적으로 "이 PR의 범위만", "기존의 미커밋 차분은 건드리지 마"라고 판단하는 상황에서도, AI에게는 명시하지 않으면 전달되지 않습니다.

그래서 의뢰문에 다음 4가지를 반드시 넣도록 했습니다.

- 수정 가능한 범위
- 수정 금지 범위
- 기존 변경 사항의 취급
...

"관련 파일"이 아니라, 가능한 한 경로(Path)로 작성합니다.

수정 가능:
- src/renderer/components/SettingsModal.jsx
- src/renderer/hooks/useSchedule.js
...

AI에게 "관련된"이라는 표현은 너무 넓습니다. 경로로 경계를 작성하면 diff 리뷰도 쉬워집니다.

멀티 에이전트나 로컬 편집이 섞이는 환경에서는 작업 전의 git status가 중요합니다.

작업 전에 git status를 확인한다.
내가 건드리지 않은 변경 사항은 되돌리지 않는다.
같은 파일에 타인의 변경 사항이 있는 경우, 읽어본 후 최소한의 차분으로 맞춘다.

이 한 문장으로 AI가 git checkout --를 실행하거나 전체를 새로 쓰는 리스크를 낮출 수 있습니다.

리팩토링에서는 동작 확인만으로는 불충분합니다. diff가 스코프 내에 들어와 있는지도 완성 조건에 포함합니다.

완성 조건:
- 대상 테스트가 통과할 것
- 기존 UI의 문구와 동선이 바뀌지 않을 것
...

스코프 선언은 AI의 판단을 멈추기 위한 것이 아닙니다. 판단의 경계를 맞추기 위한 것입니다.

"수정 금지"라고 적은 범위에 정말로 버그 원인이 있는 경우에는 AI에게 억지로 수정하게 하지 않고, 일단 보고하게 합니다. 스코프 외의 영역을 멋대로 고치는 것보다 다음 의뢰로 나누는 것이 리뷰하기 쉽습니다.

또한, 스코프를 너무 좁게 설정하면 필요한 테스트나 타입 정의(Type Definition)까지 건드릴 수 없게 됩니다. 경계를 작성할 때는 "관련 테스트", "타입 정의", "문서 업데이트" 등 필요해지기 쉬운 주변 영역은 명시해 둡니다.

Codex에게 리팩토링을 맡기기 전에 수정 범위를 먼저 작성하면 리뷰가 가벼워졌습니다.

• 경로로 "수정 가능한 범위"를 작성한다
• "수정 금지 범위"와 기존 변경 사항의 취급도 작성한다
• 완성 조건에 diff의 수렴 여부를 포함한다

AI에게 맡기는 범위를 좁히는 것이라기보다, 리뷰 가능한 단위로 자르기 위한 운영 방식입니다.

• harness17/zenn-articles - 본 기사에서 다룬 기사 리포지토리
• AI에게 "수정해줘"라고 부탁하면 무관한 코드까지 건드리는 문제를 Surgical Changes 규칙으로 억제하기 - 작은 수정을 위한 관련 운영
• AI에게 구현을 맡기기 전에 완성 조건을 선언하는 Sprint Contract 운영 - 완성 조건을 먼저 두는 관련 운영