클로드 코드 서브에이전트로 안드 멀티모듈 리팩터링 반나절 컷 낸 후기

 

멀티에이전트의 핵심은 '병렬 처리'가 아니었습니다. 정작 시간을 줄여준 건 '컨텍스트 격리'였거든요. 빌드는 어차피 직렬로 쌓이니까요.

 

지난달에 회사 안드로이드 프로젝트의 Convention Plugin 마이그레이션을 하루 안에 끝내야 하는 상황이 생겼어요. 모듈이 30개 정도 있는데 compileSdk, Hilt(힐트), Detekt(디텍트) 설정이 모듈마다 따로 박혀 있어서, build-logic 으로 한 번에 묶어야 했습니다. 평소라면 사흘은 잡았을 작업인데, 이번엔 클로드 코드(Claude Code) 서브에이전트를 처음으로 본격 투입해봤네요.

 

단일 클로드 코드 세션으로 30개 모듈 굴리면 한계가 옵니다

이전까지는 그냥 단일 클로드 코드 세션으로 모듈을 하나씩 돌려가며 작업했어요. 근데 6년차로 굴려보니까 단일 세션은 모듈 7~8개를 넘기면 슬슬 이상해집니다.

 

가장 자주 마주친 패턴이 libs.versions.toml 중복 추가였어요. 분명히 30분 전에 androidx-hilt 버전을 정의해놨는데, 다른 모듈을 손보다가 다시 같은 키를 추가하고 있더라고요. 토큰이 80K 를 넘기면서 앞쪽 작업 내용을 잊어버리는 셈이었습니다. 체감상 80K 가 안드로이드 멀티모듈 프로젝트에선 의외로 금방 차거든요.

 

거기에 모듈 하나 손볼 때마다 :app:assembleDebug 가 4~7분씩 걸리니까, 직렬로 쌓이면 진짜 답이 없었어요. 사람이 에이전트의 단기 기억을 보조하는 역할까지 떠맡게 되더라고요.

 

 

클로드 코드 서브에이전트의 진짜 효과는 컨텍스트 격리

서브에이전트(Subagents)는 메인 에이전트가 만들어내는 자식 에이전트입니다. 각자 독립된 컨텍스트, 시스템 프롬프트, 도구 권한을 따로 가져요. 작업이 끝나면 결과 요약본만 메인으로 돌아옵니다.

 

이게 왜 중요하냐면, 메인 에이전트의 토큰 부하가 확 줄어들기 때문이에요. 제가 이번에 굴려보니 메인 세션 토큰이 80K 까지 차오르던 게 12K 수준에서 멈추더라고요. 서브에이전트가 자기 모듈의 30개 파일을 다 뒤져도 메인한테는 "이 4개 파일을 이렇게 고쳤습니다" 한 줄만 올라옵니다.

 

병렬 처리 효과는 사실 생각보다 크지 않습니다. 코드는 같이 고쳐도 그래들(Gradle) Sync 와 KSP(Kotlin Symbol Processing) 빌드는 어차피 직렬로 돌아가니까요. 그래도 모듈별 책임만 명확하게 잘라주면 환각률이 눈에 띄게 줄어드는 게 진짜 가치였어요.

 

:core·:feature·:build-logic 서브에이전트 모델 라우팅 실전

이번에 제가 짠 분배는 이랬습니다.

 

1. 에이전트 A (Opus): :core:designsystem 의 젯팩 컴포즈(Jetpack Compose) 테마와 디자인 토큰 리팩터링. 색상·타이포·간격 토큰을 새 구조로 옮기는 작업.
2. 에이전트 B (Sonnet): :feature:* 모듈의 ViewModel 을 Hilt 와 KMP 호환 구조로 변환. 패턴이 반복되는 작업이라 Sonnet 으로 충분했어요.
3. 에이전트 C (Opus): build-logic 에 Convention Plugin 스크립트 작성과 libs.versions.toml 정리.
4. 에이전트 D (Haiku): 패키지명 일괄 변경, import 정리 같은 단순 파일 수정.

 

핵심은 모델 라우팅이었습니다. 4개 서브에이전트를 다 Opus 로 굴리면 토큰 비용이 4배가 되니까요. 단순 작업은 Haiku, 패턴 반복은 Sonnet, 의존성 추론처럼 머리 써야 하는 작업만 Opus 로 묶었습니다. 이렇게 분리하니까 최종 비용이 단일 세션 대비 2.3배 선에서 정리됐어요.

 

그리고 가장 효과가 컸던 규칙 하나. 서브에이전트를 생성하기 전에 수정할 파일 목록을 먼저 출력해서 제가 승인하도록 만들었습니다. 처음엔 귀찮았는데, 이 한 단계가 재작업을 절반 가까이 줄여줬어요. 메인 에이전트가 작업을 잘못 분배하면 서브에이전트는 그저 잘못된 일을 빠르게 해낼 뿐이니까요.

 

 

깃 워크트리와 CLAUDE.md로 서브에이전트 충돌 막기

서브에이전트끼리는 직접 통신이 불가능합니다. 그래서 동시에 같은 파일을 건드리면 그냥 덮어써져요. 안드로이드 멀티모듈은 한 모듈 변경이 다른 모듈에 영향을 줄 일이 많아서, 이 부분을 사람이 미리 잘라줘야 합니다.

 

1. isolation: "worktree" 옵션으로 서브에이전트별 작업 공간을 분리합니다. 깃 워크트리(Git Worktree) 를 활용해서 각자 자기 브랜치에서 일하게 하는 방식이에요.
2. 루트 CLAUDE.md 에 모듈 경계 규칙을 박아둡니다. 예를 들면 ":feature 는 :data 를 직접 import 금지, :core:domain 을 통해서만 접근" 같은 문장이요(이건 Hedvig 실제 규칙이 아니라 제가 쓰는 가상 예시입니다). Hedvig Insurance 라는 회사는 80여 개 모듈을 CLAUDE.md 한 장으로 관리한다고 합니다.
3. public API 변경 시 메인 에이전트에게 반드시 보고하도록 시스템 프롬프트에 명시합니다. 다른 에이전트 작업과의 충돌을 잡는 마지막 안전망입니다.

 

개인적으로는 CLAUDE.md 규칙을 짤 때 "do not touch" 항목을 가장 먼저 적어두는 걸 추천드리고 싶네요. 허용 규칙보다 금지 규칙이 환각을 더 잘 잡아주는 경우가 많더라고요.

 

 

통합 빌드와 instrumented 테스트는 결국 사람이 직접

서브에이전트별로 PR 이 4개 만들어지니까, 리뷰 부담은 오히려 늘었습니다. 그리고 :app:assembleDebug 통합 빌드는 첫 시도에 그냥 깨지는 일이 잦았어요. 4개의 작업이 각자 깔끔해도, 합쳐놓으면 의존성 그래프가 어긋나는 경우가 생기더라고요.

 

특히 instrumented 테스트와 baseline profile 검증은 절대 에이전트한테 맡기면 안 됐습니다. 한 번은 서브에이전트가 깨진 테스트를 @Ignore 로 막아두고 "통과"라고 보고한 적이 있어요. 이게 잡혀서 다행이지, 그대로 머지됐으면 큰일 날 뻔했습니다.

 

그래서 저는 단위 테스트만 에이전트한테 맡기고, 통합 빌드와 instrumented 테스트는 직접 돌립니다. 모듈 3개 이상을 동시에 손보는 큰 리팩터링이 아니면 멀티에이전트를 켜지 않아요. 30초짜리 단순 수정에 서브에이전트를 띄우면 계획·분할·병합 오버헤드 때문에 오히려 더 오래 걸리니까요.

 

결국 사람이 모듈 경계를 자르는 도구

이번에 굴려보고 가장 크게 느낀 건, 클로드 코드 서브에이전트가 'AI 자동화 도구' 가 아니라 '사람이 컨텍스트를 설계하고 격리하는 도구' 라는 점이었습니다. 모듈 경계를 어디서 자를지, 워크트리를 어떻게 분리할지, 어떤 작업을 Opus 에 보내고 어떤 작업을 Haiku 로 돌릴지는 결국 사람이 정해야 했어요.

 

멀티에이전트를 처음 도입하신다면, 도구 사용법보다 본인 프로젝트의 모듈 경계 정리가 먼저라고 봅니다. 경계가 흐릿한 상태에서 에이전트만 4개로 늘리면 환각도 4배가 되니까요.

 

메인 세션 토큰이 80K 에서 12K 로. 결국 이번에 돈을 번 자리는 거기 한 곳이었습니다.