클로드 코드 큰 리팩터링을 파일마다 하이쿠 세션으로 나눠 돌리는 법

파일 수백 개를 세션 하나로 고치다 보면 대화가 길어져 앞에서 정한 내용을 놓치기 쉽다. 고칠 파일 목록부터 만들고, 파일마다 claude -p로 새 세션을 띄워 나눠 돌린다. 클로드 코드(Claude Code) 공식 모범 사례 문서에 '파일마다 나눠 돌리기(fan out across files)'로 나오는 방법인데, X에서는 "오퍼스가 계획하고 하이쿠가 갈아 넣는다"는 글로 퍼졌다.

1. 대화형 세션에서 고칠 파일 목록과 규칙을 파일로 적게 한다.

이번 변경이 필요한 파일을 한 줄에 하나씩 files.txt에 적고, 적용할 규칙은 RULE.md에 적어 줘

1. 파일 몇 개로 먼저 돌려 보고, 결과가 이상하면 프롬프트를 고친다.

head -3 files.txt | while read f; do
  claude -p "RULE.md 규칙을 $f에 적용해. 끝나면 OK, 못 하면 FAIL만 답해" \
    --model haiku --max-turns 8 \
    --allowedTools "Edit" --permission-mode dontAsk \
    --output-format json
done

1. 문제가 없으면 8개씩 동시에 돌린다.

mkdir -p out
xargs -P 8 -I{} sh -c 'claude -p "RULE.md 규칙을 {}에 적용해. 끝나면 OK, 못 하면 FAIL만 답해" --model haiku --max-turns 8 --allowedTools "Edit" --permission-mode dontAsk --output-format json > "out/$(echo {} | tr / _).json"' < files.txt

1. 결과와 비용을 한꺼번에 본다. --output-format json으로 받은 결과에 답(result)과 실행별 비용 추정치(total_cost_usd)가 들어 있다.

jq -r '[input_filename, .result, .total_cost_usd] | @tsv' out/*.json

FAIL이 나온 파일만 --model sonnet으로 다시 돌린다.

--allowedTools에 넣은 도구는 묻지 않고 쓰고, --permission-mode dontAsk는 그 밖에 승인이 필요한 동작을 전부 거절해서 자리를 비워도 승인 창에서 멈추지 않는다. --max-turns는 -p 모드에서만 먹는다. 한도에 닿으면 오류로 끝난다.

X 글처럼 Bash(git commit:*)까지 허락해 커밋을 맡겨도 된다(:*는 *와 같은 뜻). 여러 세션이 동시에 커밋하면 git 잠금이 겹칠 수 있으니 병렬로 돌릴 때는 다 끝난 뒤 한 번에 커밋한다.

스크립트 짜기가 번거로우면 /batch <지시>를 쓴다. 클로드가 변경을 서브에이전트 5~30개에 나눠 맡기고, 서브에이전트는 저마다 자기 worktree에서 작업한다.