Cmd. /batch
대규모 코드베이스 변경을 독립 단위로 분해해 워크트리에서 병렬 실행하는 bundled skill 명령
핵심 요약
- worktree별 subagent로 대규모 변경 병렬화 (skill)
- 입력 위치·지원 조건을 확인한 뒤 아래 실행 예를 사용합니다.
역할
worktree별 subagent로 대규모 변경 병렬화 (skill)
/batch <instruction>사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 번들 스킬 |
| 상태 | 조건부 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-10-23 · Claude Code 2.1.308 |
| 릴리스 근거 | v2.1.281 |
Git 저장소 또는 worktree를 만드는 WorktreeCreate hook이 필요합니다(git 밖에서는 v2.1.281+). 계획을 승인한 뒤 각 worktree 작업이 시작됩니다.
사용 예
/batch migrate src/utils from JavaScript to TypeScript# 공식 예시: 대규모 마이그레이션
/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 | 서브에이전트 정의 파일 관리 방법 안내 | 위임할 에이전트 설정/관리 |
실행 결과와 유지 범위
승인한 계획의 작업 단위마다 격리된 worktree에서 변경·테스트·PR 생성이 진행됩니다.
/batch는 공식 문서에서 bundled skill(번들 스킬)로 분류되는 명령입니다.
직접 작성한 스킬과 동일하게, Claude에게 전달되는 프롬프트 형태이며 관련 상황에서 Claude가 자동으로 호출할 수도 있습니다.
공식 설명에 따르면 /batch는 코드베이스 전반에 걸친 대규모 변경을 병렬로 오케스트레이션합니다. 흐름은 이렇습니다.
- 코드베이스를 먼저 조사(research)합니다.
- 작업을 **5~30개의 독립적인 단위(independent units)**로 분해하고 계획을 제시합니다.
- 계획이 승인되면, 각 단위마다 **격리된 git 워크트리(worktree)**에서 백그라운드 서브에이전트를 하나씩 띄웁니다.
- 각 서브에이전트는 자신이 맡은 단위를 구현하고, 테스트를 실행한 뒤 변경을 게시(publish)합니다. GitHub 저장소라면 보통 PR이 됩니다.
실행하려면 git 저장소가 있거나, worktree를 만들어 주는 WorktreeCreate hook이 설정돼 있어야 합니다. git 저장소 밖에서 hook으로 실행하려면 Claude Code v2.1.281 이상이 필요합니다.
공식 예시: /batch migrate src/ from Solid to React
주의사항
- git 저장소 또는
WorktreeCreatehook이 필요합니다. 둘 다 없으면 실행할 수 없고, git 저장소 밖에서 hook으로 쓰는 방식은 v2.1.281 이상에서만 동작합니다. - 변경을 5~30개의 독립 단위로 분해하므로, 단위 간 의존성이 큰 작업에는 적합하지 않습니다.
- 계획은 승인 단계를 거친 뒤에야 서브에이전트가 실행됩니다. 분해된 계획을 먼저 검토하세요.
- 각 단위는 별도 워크트리에서 백그라운드로 돌고 단위마다 변경이 따로 게시됩니다(GitHub에서는 보통 PR). 그만큼 PR이 여러 개 생길 수 있으니 염두에 두세요.
- bundled skill이므로 관련 상황에서 Claude가 자동으로 호출할 수도 있습니다.
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록