여러 파일에 걸친 리팩터링을 시키면 Claude Code가 파일 하나를 고치자마자 바로 다음 파일로 넘어가는 경우가 있습니다. 중간에 접근 방식이 잘못됐다는 걸 알아차려도 이미 절반 넘게 진행된 뒤라서, 되돌리고 다시 시키는 비용이 꽤 컸습니다. 플랜 모드로 실행 전에 방향부터 확인받은 뒤 작업을 맡긴 경험을 정리합니다.
어떤 작업이었나
여러 화면에서 공통으로 쓰는 네트워크 응답 처리 코드를 손보는 작업이었습니다. 기존에는 API 호출이 실패하면 예외를 던지고 각 화면에서 try/catch로 잡아 에러 메시지를 표시하는 방식이었는데, 화면마다 잡는 예외 종류와 메시지 처리 방식이 조금씩 달라서 실패 케이스 하나가 빠지면 앱이 그대로 죽는 경우가 종종 있었습니다. 성공/실패를 값으로 표현하는 Result 타입으로 바꾸려는 게 목표였는데, 호출부가 열 곳이 넘어서 한 번에 맡기기엔 범위가 컸습니다.
AI를 어떻게 활용했나
Shift+Tab을 눌러 권한 모드를 플랜 모드로 바꾼 뒤 작업을 설명했습니다. 플랜 모드에서는 파일을 바로 고치지 않고 코드를 읽기만 하면서 진행 계획을 세웁니다.
네트워크 응답 처리를 예외 던지는 방식에서 Result<T, ApiError> 반환 방식으로 바꾸고 싶어.
호출부를 전부 찾아서 어떤 순서로 바꿔야 할지 계획을 세워줘.
Claude Code가 호출부를 전부 훑은 뒤 아래와 같은 계획을 제시했습니다.
1. ApiError sealed 클래스 정의 (Network, Unauthorized, Unknown)
2. ApiClient의 각 메서드가 예외 대신 Result<T, ApiError>를 반환하도록 수정
3. 호출부 11곳을 하나씩 Result 처리 방식(when 분기)으로 교체
4. 기존 예외 처리에 의존하던 테스트 코드 수정
3번 항목만 보고는 어떤 화면부터 바꿀지 우선순위가 안 보여서, 승인하기 전에 계획을 조정해달라고 요청했습니다.
3번을 더 구체적으로 나눠줘. 로그인 관련 화면부터 먼저 바꾸고,
결제 관련 화면은 별도 커밋으로 분리해서 마지막에 처리해줘.
다시 나온 계획에는 호출부 11곳이 로그인 3곳 → 목록/상세 5곳 → 결제 3곳 순서로 나뉘어 있었고, 결제 쪽은 "별도 커밋" 표시가 붙어 있었습니다. 이 상태로 승인하자 Claude Code가 계획 순서대로 파일을 고치기 시작했고, 결제 관련 파일 세 개를 고친 뒤에는 스스로 멈춰서 커밋 메시지를 확인해달라고 물었습니다.
결과와 얻은 팁
- 계획 단계에서는 파일을 읽기만 하므로, 방향이 잘못됐다고 판단되면 코드가 하나도 바뀌지 않은 상태에서 되돌릴 필요 없이 바로 계획만 다시 요청할 수 있었습니다. 실행 모드로 넘어간 뒤 되돌리는 것보다 비용이 훨씬 적었습니다.
- 처음 나온 계획은 "호출부 11곳을 순서대로 교체"처럼 뭉뚱그려져 있었는데, 이 상태로 바로 승인했다면 로그인과 결제 화면 수정이 커밋 하나에 섞여서 리뷰하기 어려웠을 겁니다. 계획 단계에서 커밋 단위를 미리 지정해두니 실행 결과도 그 단위로 나뉘어 나왔습니다.
- 플랜 모드는 읽기 전용이라 계획을 몇 번 다시 요청해도 코드에 영향이 없다는 점이 편했습니다. 반대로 계획이 마음에 들어도 승인 전까지는 아무것도 실행되지 않으므로, 급하게 한 줄만 고치고 싶을 때는 플랜 모드보다 일반 모드가 더 빠릅니다. 범위가 작은 작업까지 매번 플랜 모드를 거칠 필요는 없었습니다.
- 계획에 없던 파일을 실행 중에 건드리려고 하면 Claude Code가 별도로 알려왔습니다. 계획에서 빠뜨린 호출부가 실행 단계에서 뒤늦게 발견된 셈인데, 이 경우는 계획을 다시 세우게 하기보다 그 자리에서 바로 포함시켜도 되는지 확인만 받고 진행하는 편이 더 실용적이었습니다.