Claude Code 서브에이전트로 코드리뷰·테스트·문서화 역할 나누기
화요일 밤, PR 리뷰 큐에 커밋 열두 개짜리 변경사항이 올라와 있었어요. Claude Code 창 하나에 리뷰와 테스트, 문서화까지 한꺼번에 맡겼더니 대화 맥락이 자꾸 뒤섞였다. 이 글을 따라 하면 서브에이전트 세 개로 역할을 쪼개서, 맥락이 섞이지 않는 상태로 작업을 굴리는 방법을 손에 쥐게 된다. 직접 지시했을 때와 위임했을 때 결과물이 어떻게 달라지는지도 실제로 돌려본 사례로 비교해볼게요.
서브에이전트는 왜 나눠야 할까요?
서브에이전트는 특정 작업을 전담하는 독립된 AI 도우미다. 각자 자기만의 컨텍스트 창과 시스템 프롬프트, 별도의 도구 권한을 가지고 돌아간다. 메인 창 하나로 탐색과 구현, 리뷰를 다 처리하면 검색 결과와 로그가 쌓여 컨텍스트를 잠식해요.
코드리뷰 서브에이전트에는 파일 수정 권한을 아예 빼고 읽기 전용 도구만 남겼어요. 실수로 코드를 고쳐버리는 사고가 원천 차단됐다. 테스트 서브에이전트에는 실행 권한만 열어주고 문서 편집은 막았다. 도구 접근을 역할마다 다르게 설정한 것 자체가 안전장치로 작동했더라고요.
모델 지정도 도움이 됐다. 문서화는 상대적으로 단순해서 가벼운 모델로 지정했고, 코드리뷰는 로직 결함을 잡아야 해서 메인 대화와 같은 모델을 그대로 뒀다. 서브에이전트 단위로 모델을 따로 고를 수 있어서, Claude Code를 역할별 전담 팀처럼 쓰는 셈이 됐어요.
코드리뷰 전담 서브에이전트는 어떻게 만드나요?
서브에이전트는 YAML 프론트매터가 붙은 마크다운 파일 하나예요. 프로젝트 안에서만 쓰려면 .claude/agents 폴더에, 내 컴퓨터 전체에서 쓰려면 홈 디렉터리 쪽에 파일을 두면 된다. 나는 review-agent.md를 만들고 description에 호출 조건을 최대한 구체적으로 적었어요.
description을 애매하게 적었을 때는 일반 대화에서 잘 안 불려 나왔다. '로직 결함과 네이밍 일관성을 짚어달라는 요청이면 쓴다'라고 구체적으로 바꾸자, 같은 세션에서 열 번 중 아홉 번은 정확히 이 서브에이전트로 위임됐어요.
review-agent.md 안에는 Write와 Edit를 빼고 읽기 도구만 남겼다. 시스템 프롬프트에는 우리 팀이 자주 놓치는 패턴을 예외 처리 누락과 매직 넘버 위주로 나열해뒀다. 체크리스트를 박아두니 이 서브에이전트의 리뷰 코멘트 품질이 눈에 띄게 균질해지더라고요.
테스트와 문서화도 역할별로 나눠보니
코드리뷰 서브에이전트를 만든 다음 주, test-agent.md와 doc-agent.md를 추가했다. test-agent에는 실행 권한을 열어줬고, description에는 '빠진 테스트 케이스를 작성하고 보고한다'라고 적었다. doc-agent에는 실행 권한을 빼고 문서 파일 편집 권한만 남겼어요.
세 서브에이전트를 동시에 돌려본 첫날은 8월 셋째 주 목요일이었다. 커밋 열두 개짜리 작업을 위임 문장 세 줄로 던지고 기다렸다. 직접 지시했다면 47분쯤 걸렸을 일이 19분 만에 끝났어요. 매번 이 정도로 줄어든다고 장담하진 않는다.
문서화 서브에이전트가 특히 인상적이었어요. 코드 변경사항만 보고 README에서 바뀌어야 할 부분을 스스로 찾아 목록으로 뽑아줬다. 예전에 직접 지시했을 때는 절반쯤 놓치고 지나갔는데, 전담 역할이 생기니 누락률이 확 줄었다.
직접 지시했을 때와 위임했을 때, 뭐가 달랐나
지난 화요일 밤, 같은 PR을 두 가지 방식으로 다뤄봤어요. 하나는 메인 세션에 리뷰·테스트·문서화를 한 번에 지시하는 방식이고, 다른 하나는 서브에이전트 세 개에 각각 위임하는 방식이었다. 직접 지시했을 때는 세 작업이 뒤섞이면서 앞서 지적한 내용을 다시 설명해야 했다.
위임 방식에서는 이런 되풀이가 없었어요. 서브에이전트가 각자 컨텍스트 안에서 작업을 끝내고 요약만 돌려주니, 메인 대화에는 정리된 결과만 남았다.
결과물 형식도 갈렸어요. 직접 지시했을 때는 리뷰·테스트·문서 코멘트가 한 응답에 뒤섞여 정리하는 수고가 따로 들었는데, 서브에이전트로 나누니 결과물이 분리된 채로 도착했어요. 매번 확실히 더 낫다고 말하긴 조심스럽지만, 이번 규모의 작업에서는 위임 쪽이 관리하기 쉬웠다.
흔한 실수와 해결법
처음 서브에이전트 세 개를 한꺼번에 만들 때 description을 대충 적었다. 그랬더니 test-agent를 불러야 할 상황에 review-agent가 불려 나오는 일이 반복됐어요. 조건을 구체적으로 적고 나서야 호출 정확도가 올라갔다.
컨텍스트가 완전히 나뉘는 게 실수로 이어진 적도 있어요. 서브에이전트는 이전 대화를 기억 못 해서, 지난주 지적한 매직 넘버를 이번 PR에서 또 지적했다. 리뷰 이력을 시스템 프롬프트에 요약해두고서야 같은 지적이 안 반복됐다.
버전 문제도 겪었다. v2.1.198부터 Explore 서브에이전트가 메인 모델을 그대로 물려받게 바뀌었는데, 예전 습관대로 뒀다가 비싼 모델로 탐색이 도는 걸 뒤늦게 발견했어요. 커스텀 서브에이전트에 모델을 직접 명시해두면 이런 변경에 영향받지 않는다.
세 서브에이전트를 다 만들고 나니 다음 실험거리가 떠올랐다. PR 규모가 커지면 배포 전 체크리스트 전담 서브에이전트를 하나 더 추가해볼까 싶어요. 오늘 review-agent.md 하나부터 만들어보는 것이 빠른 시작점이다.
자주 묻는 질문
Q. 서브에이전트는 몇 개까지 만들 수 있나요? A. 개수 제한은 따로 없다. description이 겹치면 호출이 헷갈리니, 나는 역할이 뚜렷이 구분되는 선에서 세 개로 시작했어요.
Q. 서브에이전트 도구 권한은 어디서 정하나요? A. 프론트매터 tools 필드에서 지정한다. 비워두면 메인 세션 권한을 물려받으므로, 역할을 좁히려면 명시적으로 적어야 한다.
Q. 프로젝트 범위와 개인 범위는 뭐가 다른가요? A. .claude/agents 폴더에 두면 그 프로젝트에서만, 홈 디렉터리에 두면 컴퓨터 전체에서 쓸 수 있어요.