Cmd. /batch
대규모 코드베이스 변경을 독립 단위로 분해해 워크트리에서 병렬 실행하는 bundled skill 명령
핵심 요약
/batch <instruction>은 코드베이스를 먼저 조사한 뒤 작업을 5~30개의 독립 단위로 분해해 병렬로 오케스트레이션하는 번들 스킬입니다.- 계획이 승인되면 각 단위마다 격리된 git 워크트리에서 백그라운드 서브에이전트가 구현·테스트하고 단위별 PR을 엽니다.
- 실행하려면 git 저장소가 필수이며,
<instruction>은 생략할 수 없는 필수 인자입니다. - 단위 간 의존성이 큰 작업에는 맞지 않고, 여러 PR이 한꺼번에 생기니 미리 염두에 두세요.
명령어 원본 선언
/batch <instruction><instruction>은 필수 인자입니다. (<arg>는 필수,[arg]는 선택을 의미)- 별칭(alias)은 없습니다.
공식 설명 요약
/batch는 공식 문서에서 bundled skill(번들 스킬)로 분류되는 명령입니다.
직접 작성한 스킬과 동일하게, Claude에게 전달되는 프롬프트 형태이며 관련 상황에서 Claude가 자동으로 호출할 수도 있습니다.
공식 설명에 따르면 /batch는 코드베이스 전반에 걸친 대규모 변경을 병렬로 오케스트레이션합니다. 흐름은 이렇습니다.
- 코드베이스를 먼저 조사(research)합니다.
- 작업을 **5~30개의 독립적인 단위(independent units)**로 분해하고 계획을 제시합니다.
- 계획이 승인되면, 각 단위마다 **격리된 git 워크트리(worktree)**에서 백그라운드 서브에이전트를 하나씩 띄웁니다.
- 각 서브에이전트는 자신이 맡은 단위를 구현하고, 테스트를 실행한 뒤 풀 리퀘스트(PR)를 엽니다.
이를 실행하려면 git 저장소가 필요합니다.
공식 예시: /batch migrate src/ from Solid to React
최소 지원 버전
- 공식 명령어 문서(
/commands)에는 별도 최소 버전이 명시되어 있지 않습니다. - bundled skill 및 백그라운드 서브에이전트, 워크트리 기능을 모두 활용하는 명령이므로, 이 기능들이 모두 제공되는 최신 버전의 Claude Code에서 사용하는 것을 권장합니다.
사용법
# 공식 예시: 대규모 마이그레이션
/batch migrate src/ from Solid to React# 전반적인 라이브러리 교체/업그레이드를 병렬로 분해
/batch upgrade all API routes from v1 to v2 across the repo지시문에는 "무엇을, 어디까지" 변경할지 범위를 분명히 적으세요. Claude가 그 지시문을 5~30개의 독립 단위로 쪼개기 때문입니다.
좋은 사용 예
- 코드베이스 전반에 걸친 대규모 마이그레이션(프레임워크/라이브러리 교체)
- 여러 모듈에 동일하게 적용해야 하는 대량 리팩터링
- 서로 의존성이 적어 독립적으로 병렬 처리 가능한 다건 변경
비슷한 명령어 추천
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
/batch | 변경을 5~30개 독립 단위로 분해 → 워크트리별 백그라운드 서브에이전트 + PR | 코드베이스 전반의 대규모 병렬 변경 |
/background | 현재 세션 전체를 백그라운드 에이전트로 분리(별칭 /bg) | 단일 작업을 백그라운드로 돌리고 싶을 때 |
/tasks | 현재 세션에서 백그라운드로 도는 작업 목록 확인 | 실행 중인 병렬 작업 상태 점검 |
/agents | 서브에이전트 구성 관리 | 위임할 에이전트 설정/관리 |
활용 사례
- Solid → React처럼 디렉터리 전반에 걸친 프레임워크 마이그레이션을 한 번에 병렬 진행
- 수십 개 파일/모듈에 동일 패턴 변경을 적용한 뒤 단위별 PR로 나눠 검토
- 독립 단위로 분해 가능한 대규모 작업을 워크트리에서 격리 실행해 메인 작업 트리를 보호
주의사항
- git 저장소가 필수입니다. git 저장소가 아니면 실행할 수 없습니다.
- 변경을 5~30개의 독립 단위로 분해하므로, 단위 간 의존성이 큰 작업에는 적합하지 않습니다.
- 계획은 승인 단계를 거친 뒤에야 서브에이전트가 실행됩니다. 분해된 계획을 먼저 검토하세요.
- 각 단위는 별도 워크트리에서 백그라운드로 돌고 단위별 PR이 열립니다. 그만큼 PR이 여러 개 생길 수 있으니 염두에 두세요.
- bundled skill이므로 관련 상황에서 Claude가 자동으로 호출할 수도 있습니다.
출처
- Commands(공식 명령어 레퍼런스): https://code.claude.com/docs/en/commands
- Worktrees: https://code.claude.com/docs/en/worktrees
- Subagents: https://code.claude.com/docs/en/sub-agents