batch

Claude Code /batch 명령어는 대규모 리팩토링이나 마이그레이션을 자동으로 처리해주는 오케스트레이터입니다. 상위 수준 지시문 하나를 던지면 여러 개의 독립적인 작업 단위로 쪼개서 코드베이스 전체에 병렬로 실행합니다.

이 명령어는 다음 조건에 해당하는 작업에 적합합니다.

• 여러 파일이나 모듈에 걸친 변경(wide)
• 저장소 전체에서 비슷한 패턴이 반복되는 작업(repeatable)
• 여러 청크로 안전하게 나눌 수 있는 작업(decomposable)

프레임워크 마이그레이션이나 대규모 rename, API 변경 같은 시스템적인 코드베이스 업그레이드가 대표적인 예입니다.

사용법은 /batch <instruction> 형태입니다. <instruction>은 실제 문법이 아니라 원하는 변경을 자연어로 채워 넣는 자리입니다.

/batch migrate src/ from Solid to React

좋은 instruction은 범위가 구체적이고(어느 폴더인지), 완료 기준이 명확하며 필요하면 제약조건(API 호환성 유지 등)까지 포함합니다.

먼저 코드베이스를 조사하고 나서 5~30개의 독립적인 unit으로 분해합니다. 그 다음 계획을 제시하고 승인을 기다립니다. 사용자가 unit 구성과 접근 방식을 검토하기 전까지는 아무것도 진행되지 않습니다. 승인 후에는 unit당 백그라운드 에이전트 하나를 생성해 병렬로 실행합니다. 각 에이전트는 격리된 git worktree에서 작업하며 구현부터 테스트, PR 오픈까지 개별적으로 처리합니다.

이 명령어는 하나의 거대한 작업을 동시 실행 가능한 여러 작은 작업으로 바꾸는 게 가장 큰 특징입니다. git worktree로 격리하기 때문에 에이전트끼리 작업 디렉토리를 침범하지 않고 unit별로 변경 내역도 깔끔하게 유지됩니다. 계획 검토 단계를 두는 이유는 불필요한 연산과 시간 낭비를 막고 범위와 리스크가 의도와 일치하는지 확인하기 위해서입니다. 결과물도 unit당 PR로 나오기 때문에 리뷰가 관리하기 쉽고 단계적으로 머지하거나 일부만 롤백하는 것도 가능합니다.

단 git 저장소가 필요하고 5~30개의 의미 있는 청크로 나눌 수 있는 작업에 가장 적합합니다. 작업 항목들이 서로 지나치게 의존적이면 병합 충돌이나 중간 상태가 깨질 수 있어서 계획과 순서를 잘 잡는 게 중요합니다.