서브에이전트로 작업 분산 시도기: 콘텐츠 만들다 발견한 반전
도입
서브에이전트를 5개 만들었습니다. code-improver, ui-improver, logcat-analyzer, notion-project-manager, plan-analyst. Claude Code한테 물어보면서 병렬로 처리하면 좋을 만한 작업을 하나씩 서브에이전트로 뽑았고, 만들고 난 후에는 실제 워크플로에 붙여서 써보면서 하나씩 조정해왔습니다. 그 과정에서 코드 리뷰 서브에이전트를 쓰다가 다시 되돌린 적이 있는데, 되돌아갔어야 할 지점과 실제로 도착한 지점이 달랐다는 걸 이 글을 쓰면서 알게 됐습니다.
무엇을 만들었나
현재 쓰고 있는 서브에이전트 5개입니다.
- code-improver: 최근 작성·수정한 코드의 성능·보일러플레이트·코드 품질을 분석해서 High/Medium/Low 우선순위로 개선안을 제안
- ui-improver: UI/애니메이션 코드를 시각적 일관성, 애니메이션 품질, 접근성 기준으로 리뷰
- logcat-analyzer: 크래시/ANR/프리즈 보고가 들어오면 logcat을 분석해 원인을 추적하고 수정안까지 제안 (로그가 없으면 ADB로 직접 캡처)
- notion-project-manager: 노션 티켓 조회·생성·업데이트를 담당. 네 개 프로젝트(DWS, ALTERAI, PXL, APL) DB 스키마를 알고 있음
- plan-analyst: .plan/ 폴더의 플랜 md 파일을 읽고 작업 브리핑·우선순위·의존성을 정리
모두 Claude Code에게 "이런 작업은 어떻게 분리하면 좋을까"를 물어보면서 함께 설계한 결과입니다. 코드 리뷰도 이 흐름 안에서 서브에이전트로 만들었던 작업 중 하나였습니다.
작업 관리방식: 노션 대시보드 + .plan 폴더
프로젝트 관리는 노션의 DashBoard DB로 하고 있습니다. 네 개 프로젝트의 티켓을 각각 다른 DB로 관리하고, notion-project-manager 서브에이전트가 티켓 ID로 조회·생성·업데이트를 대신 처리합니다.
실제 작업은 프로젝트 안 .plan/ 폴더에 플랜 md 파일을 만들어 진행합니다. 세션이 끊기거나 나중에 다시 이어가야 할 때 이 파일을 기준으로 컨텍스트를 복원하고, plan-analyst 서브에이전트가 이 파일들을 읽고 작업 브리핑을 생성해줍니다.
문제: PR 생성에서 코드 리뷰 서브에이전트가 느렸다
PR 생성 커맨드 안에서 코드 리뷰 단계를 전용 서브에이전트로 놓아 본 적이 있습니다. 결과부터 말하면, 체감상 상당히 오래 걸렸습니다.
왜 느렸는지: 서브에이전트의 컨텍스트 격리 구조
Claude Code 공식 문서에 따르면, 서브에이전트는 각자 독립된 컨텍스트 윈도우에서 실행되고, 본 세션의 대화 기록을 자동으로 이어받지 않습니다. 반환되는 건 최종 결과뿐이고, 중간에 무슨 파일을 읽었는지 어떤 추론을 거쳤는지는 본래 대화에 남지 않습니다. 공식 문서에도 "서브에이전트는 처음부터 시작하므로 컨텍스트를 모으는 데 시간이 걸릴 수 있다"고 명시되어 있습니다.
PR 생성 플로우에 대입해보면 이게 문제가 됩니다. 메인 세션은 이미 브랜치 정보, diff, 변경된 파일 목록을 다 파악한 상태입니다. 하지만 리뷰를 서브에이전트로 넘기는 순간, 그 서브에이전트는 이 모든 것을 모르는 상태에서 출발합니다. diff를 다시 가져오고, 관련 파일을 다시 읽고, 필요하면 CLAUDE.md도 다시 확인해야 합니다. 메인 세션이 이미 끝낸 일을, 서브에이전트가 처음부터 다시 반복하는 셈입니다.
여기에 더해, PR 생성과 코드 리뷰는 원래 결합도가 높은 작업입니다. 리뷰 결과에 따라 PR 본문 내용이나 라벨이 달라지기도 하고, 제가 "수정할지 그대로 올릴지"를 바로 결정해야 하는데, 이 정보가 서브에이전트 경계를 넘나들면서 끊기고 다시 병합되는 과정이 추가되었습니다.
되돌아갔어야 할 지점과 실제로 도착한 지점
서브에이전트가 느려서 되돌리기로 했을 때, 원래 계획은 "서브에이전트를 접고 코드 리뷰를 다시 스킬(커맨드)로 되돌린다"였습니다. 서브에이전트를 쓰기로 마음먹고 여러 개를 만든 것과 별개로, 코드 리뷰 하나만큼은 PR 플로우와 결합도가 높으니 독립된 커맨드 형태로 남겨두려던 것입니다.
그런데 실제로는 스킬이 아니라 완전한 인라인으로 가버렸습니다. 지금 pr.md에는 "/code-review 스킬을 호출하지 않는다"고 명시되어 있고, 코드 리뷰 로직 자체가 PR 커맨드 안에 통째로 들어가 있습니다. 되돌아갔어야 할 지점은 스킬이었는데, 어느 순간 그 단계를 건너뛰고 더 멀리 가버린 셈입니다. 이 차이를 이번에 이 글을 쓰면서 pr.md를 다시 들여다보다가 알게 됐습니다.
그래서 다음 작업으로 코드 리뷰를 다시 별도 스킬로 분리할 계획입니다.
서브에이전트 5개는 여전히 잘 쓰고 있다
이 경험이 "서브에이전트가 느리다"로 일반화되지는 않습니다. 다섯 서브에이전트 중 네 개(code-improver, ui-improver, logcat-analyzer, notion-project-manager, plan-analyst)는 여전히 독립적으로 호출합니다. 이 작업들은 메인 세션이 방금 몰두해 있던 컨텍스트를 그대로 이어받을 필요가 없기 때문입니다. 코드 개선을 물어보거나, 크래시 로그를 놓거나, 노션 티켓을 조회할 때는 새 컨텍스트에서 시작해도 전혀 손해가 아닙니다. 오히려 메인 세션이 그 컨텍스트로 오염되지 않아서 깨끗합니다.
판단 기준
지금까지의 경험으로 세운 기준은 이렇습니다.
- 메인 세션과 컨텍스트를 공유할 필요가 없고, 독립적으로 끝나는 작업 → 서브에이전트
- 이미 메인 세션이 확보해둔 컨텍스트(diff, 파일, 브랜치 정보)를 그대로 써야 하고, 결과가 바로 다음 결정에 영향을 주는 작업 → 스킬 또는 인라인
다만 코드 리뷰는 이 기준대로라면 "스킬"에 자리 잡았어야 하는데, 실제로는 완전 인라인에 멈춰 있었습니다. 스킬은 인라인처럼 메인 세션 컨텍스트를 그대로 쓰면서도, PR 생성과 분리해서 필요할 때만 불러 쓸 수 있다는 점에서 지금의 완전 인라인과는 다릅니다.
마무리
서브에이전트는 만들어두면 다 좋은 줄 알았는데, 실제로는 작업이 기존 컨텍스트와 얼마나 결합되어 있는지가 더 중요한 판단 기준이었습니다. 그리고 그 기준을 세워뒀다고 해서 항상 계획대로 정착하는 것도 아니었습니다. 코드 리뷰는 스킬로 되돌아갔어야 했는데 인라인으로 가버렸다는 걸, 정작 이번에 콘텐츠를 만들면서야 알아차렸습니다. 다음 작업은 이걸 다시 스킬로 분리하는 것입니다.
[핵심요약] 서브에이전트 여러 개를 만들어 쓰다가, 코드 리뷰만은 스킬로 되돌아갔어야 했는데 실제로는 완전 인라인이 되어버린 걸 콘텐츠를 만들다 알게 된 이야기. 다음 계획은 코드 리뷰를 다시 스킬로 분리하는 것