Claude Code 서브 에이전트 실행 시 주의사항

TLDR: 서브 에이전트 쓸 때 조심해라. 생성 개수 제한 걸고, 지들끼리 또 서브 에이전트 못 만들게 막아놔야 함.

오늘 Opus 4.6, 4.7, 4.8 버전에서 깃허브 레포 분석하고 마크다운 리포트랑 HTML 다이어그램 뽑을 때 잘만 쓰던 프롬프트 돌리다가 문제 터짐.

Opus 5 나오면서 앤스로픽이 모델 성능 좋아졌다고 시스템 프롬프트 다이어트 좀 했다고 밝혔는데, 내 생각엔 그 과정에서 서브 에이전트들이 무한 증식하면서 뒷정리도 제대로 안 되는 문제가 생긴 듯함. 예전엔 서브 에이전트들이 좀 보수적으로 움직여서 이런 문제가 없었는데, 아마 예전에 있던 안전장치 몇 개를 없애버린 모양임.

내 5시간짜리 사용 제한을 한 방에 날려버리고 토큰 276만 개를 태워 먹은 원인에 대해 클로드한테 물어봤더니 이렇게 답하더라:

597k 라인짜리 Go 레포에 /analyze-repo + /diagram-repo 프롬프트 한 번 날렸는데, 5시간 제한 다 털림. 왜냐면 내가 헤비급 서브 에이전트 6개를 만들었는데, 얘네가 지들끼리 또 3개를 더 만들었거든. 총 276만 토큰 정도 썼는데, 이게 다 'High' 추론 모드로 돌아가서 턴마다 비싼 생각 토큰을 엄청나게 잡아먹음. 설상가상으로 시스템 결함까지 겹침: 에이전트들이 조사한 리포트가 나한테 전달이 안 됐고(결과물 대신 "Done." / "Standing by."만 뜸), 정작 에이전트 본인들은 파일 쓰기가 막혔는데 하위 에이전트들은 같은 디렉토리에 파일을 쓸 수 있는 상황이었음. 그래서 재시도할 때마다 에이전트 기록 전체가 다시 청구되면서 15만 토큰을 허공에 날림. 내 실수도 컸음. 실패한 에이전트들 멈추려고 TaskStop을 안 불렀거든. 그래서 걔네가 40분 동안 더 돌아갔고, 에이전트 6개가 아직 작업 중인데 결과물을 발행해버리는 바람에, 나중에 나온 리포트들이 내가 쓴 내용이랑 충돌나서 수정만 5번을 반복함. 쓴 돈의 3분의 1에서 절반은 그냥 날린 셈임.

서브 에이전트 쓸 때는 프롬프트에 꼭 이렇게 추가해라: 서브 에이전트 개수 [3]개로 제한하고, 서브 에이전트가 또 다른 서브 에이전트 못 만들게 해라. 그리고 이런 에이전트들 백그라운드에서 돌리지 마라.