전면 리팩터링에 며칠씩 잡히나요? /batch로 큰 변경을 수십 조각으로 쪼개 동시에 처리하기

라이브러리를 통째로 바꾸거나, 모든 API에 검증 코드를 넣는 것 같은 '전면 공사'. 막상 시작하면 며칠씩 잡히고, 양이 산더미라 엄두조차 안 나죠. 하나씩 손으로 고치다 보면 어디까지 했는지 헷갈리기도 하고요. /batch는 이런 대규모 작업을 위한 명령입니다. 큰 변경을 수십 개 조각으로 쪼개 동시에 처리해, 며칠 걸릴 일을 몇 시간으로 줄여줘요. 고급 기능이라 입문 단계라면 '이런 게 있구나' 정도로 알아두면 됩니다.

정의

/batch는 큰 변경을 5~30개 단위로 쪼개 병렬로 처리하는 명령입니다.

핵심 개념 두 가지를 짚을게요.

• 병렬 처리: 작업을 잘게 나눠 여러 개를 동시에 진행하는 방식이에요. 한 명이 순서대로 하는 대신, 여러 일꾼이 각자 한 조각씩 맡아 동시에 일하는 셈입니다.
• worktree(워크트리): 각 조각이 작업하는 격리된 작업 공간이에요. 조각마다 따로 분리된 방에서 작업하니, 한 조각의 변경이 다른 조각을 망치지 않습니다.

그리고 각 조각은 작업을 마치면 PR(Pull Request, 변경 사항을 합쳐달라고 올리는 요청)까지 만들어줍니다. 즉 "쪼개기 → 동시 작업 → 각각 PR 제출"이 자동으로 흘러가는 거예요.

사용법 (난이도별)

기초 — 대규모 변경 맡기기

대화창에 변경 범위와 내용을 적어 입력합니다.

/batch src/ 폴더를 Solid에서 React로 전환해줘

입력하면 Claude가 이 큰 작업을 여러 조각으로 나눈 뒤, 각 조각을 격리된 공간에서 동시에 진행합니다. 화면에는 조각별 진행 상황이 표시되고, 끝나면 각각의 변경이 PR 형태로 정리돼요.

응용 — 범위 지정해서 분담하기

/batch 모든 API 엔드포인트에 입력값 검증 로직 추가해줘

"코드 전반에 걸친 반복 작업"도 분담시킬 수 있어요. 수십 개 API에 같은 검증을 넣는 일을 조각으로 나눠 동시에 처리하니, 하나씩 손대는 것보다 훨씬 빠릅니다.

흔한 함정 — 결과를 한 번에 합치지 말고 검토부터

/batch의 강점은 속도지만, 그만큼 주의할 점이 있어요. 여러 조각이 만든 PR을 검토 없이 한꺼번에 합치면 위험합니다.

• 각 조각은 격리된 공간에서 따로 작업하기 때문에, 서로 충돌하거나 일관성이 안 맞는 변경이 생길 수 있어요.
• 그래서 batch가 끝난 뒤엔, 각 PR의 변경 내용을 (예: /diff로) 검토하고 하나씩 합치는 게 안전합니다.

빠르게 만들어주는 만큼, 합치기 전 검토는 사람의 몫이라는 점을 기억하세요. 입문 단계에서 큰 코드베이스에 바로 쓰기보다, 작은 범위로 한번 시험해보는 걸 권합니다.

실전 사례

오래된 라이브러리를 새 버전으로 통째로 옮기는 마이그레이션 작업이 있었습니다. 손으로 하면 며칠짜리였어요. /batch로 작업을 30개 단위로 나눠 동시에 진행했습니다.

/batch 프로젝트 전체의 구버전 라이브러리를 새 버전으로 마이그레이션해줘

각 조각이 격리된 공간에서 동시에 돌면서 PR을 만들어냈고, 저는 PR을 하나씩 검토하며 합쳤어요. 순서대로 하면 며칠 걸렸을 대공사가 훨씬 짧은 시간에 끝났습니다.

이렇게 더 씁니다

• 5~30조각 분해: 큰 변경을 독립적인 단위로 쪼개 동시 처리합니다.
• 격리 실행 + PR: 각 조각이 따로 작업한 뒤 PR로 결과를 제출.
• 대규모 마이그레이션: 라이브러리 교체, 프레임워크 전환 같은 대공사에 적합.
• 진행 관리: 여러 조각이 도는 만큼, 진행 상황을 지켜보며 관리하면 좋습니다.

팁: /batch는 강력한 만큼 위험도 큽니다. 처음엔 작은 폴더 하나로 시험해보고, 결과 PR을 꼭 검토하는 습관을 들인 뒤에 큰 범위로 넓히세요.

정리

핵심은 한 문장입니다. 혼자 며칠 걸릴 대공사는 /batch로 쪼개 동시에 처리하라. 큰 변경을 자동으로 분담시킬 수 있으니, 전면 리팩터링이나 마이그레이션도 빠르게 끝낼 수 있어요. 단, 빠른 만큼 합치기 전 검토는 반드시 사람이 챙겨야 합니다.

기준: Claude Code v2.1.154 (2026.05)