멀티 에이전트

왜 한 대화가 아니라 여러 에이전트인가

Claude Code에 그냥 다 시킬 수도 있다. 기획도 구현도 리뷰도 커밋도 한 대화에서. 처음엔 그렇게 했다. 그런데 대화가 길어질수록 앞에서 정한 규칙이 뒤로 갈수록 흐려지고, 리뷰하느라 파일을 잔뜩 열어보면 그 덤프가 다음 작업의 맥락을 밀어내고, 무엇보다 모든 일이 한 줄로만 흘렀다. 검증하는 동안 다른 건 멈춰 있었다.

그래서 일을 역할별 에이전트로 쪼갰다. 이건 AI 하네스플레이북AI 하네스Claude Code를 무인으로 부리려고 짠 협업 하네스.의 세 계층 중 "자율 위임" 계층을 오케스트레이션 관점에서만 파고드는 문서다. 규칙 자동주입(Skills)·자동화·MCP는 하네스 쪽에서 다룬다. 여기선 에이전트를 어떻게 나누고, 언제 병렬로 띄우고, 언제 안 띄우는가만 본다.

역할로 나눈 일곱 전문가

.claude/agents/에 에이전트 정의 일곱 개를 파일로 뒀다. 각 파일은 그 에이전트의 시스템 프롬프트다. 페르소나·체크리스트·출력 형식·모델이 프론트매터와 본문에 박혀 있다. "너는 시니어 아키텍트고 SOLID를 지키고 함수는 20줄 이하로"를 매번 설명하는 대신, 그 정의를 가진 에이전트를 부르면 끝이다. 역할 분리란 곧 전문가를 새로 부르는 것이다.

정의는 페르소나 한 줄이 아니라 그 역할이 실제로 밟을 절차다.

에이전트	무엇을 박아뒀나
requirement-planner	모호한 요청을 Phase로 분해, 확인 필요 질문 우선, 자기검증 체크리스트
senior-clean-architect	Clean Architecture 4레이어 + SOLID, contract-first, 함수당 20줄
code-reviewer	심각도 S/A/B/C 분류 + 항목별 100점 채점, 배포 전 리뷰 체크리스트
test-runner	tsc·eslint·build·pytest를 순서대로, 고치지 않고 보고만
commit-manager	diff로 커밋 타입 자동판단, 커밋 분리 기준, 공개 미러 subtree 발행
librarian	모노레포 전 프로젝트를 가로질러 위치·요약·회고
blogger	초안 → 적대적 AI-티 검출 → 타깃 재작성 3단계 파이프라인

각 정의가 독립돼 있으니 하나를 고쳐도 다른 여섯은 안 흔들린다. 리뷰 기준을 바꾸고 싶으면 code-reviewer.md만 손대면 되고, 그 변경은 커밋 에이전트나 플래너에 새지 않는다.

컨텍스트 격리, 덤프는 두고 결론만 받는다

서브에이전트는 자기만의 컨텍스트 창에서 돈다. 이게 역할 분리만큼 중요하다.

code-reviewer가 파일을 통째로 읽고 라인별로 훑으면 수백 줄이 그 에이전트의 컨텍스트에 쌓인다. 하지만 메인 대화로 돌아오는 건 그 덤프가 아니라 최종 보고서 한 장이다. test-runner도 마찬가지다. 빌드 로그·타입 에러 전문을 다 읽되, 오케스트레이터에겐 "타입 3건, 여기 이렇게 고쳐라"만 넘긴다. 탐색의 부산물은 서브에이전트와 함께 버려지고, 판단만 남는다.

한 대화에서 다 했다면 그 로그가 전부 같은 창에 쌓여, 다음 작업을 할 즈음엔 정작 필요한 맥락이 밀려나 있었을 것이다. 격리가 그걸 막는다.

모델 티어링, 비싼 추론과 값싼 기계

일곱 중 다섯은 opus, 둘은 sonnet이다. 아무렇게나 정한 게 아니라 그 일에 판단이 필요한가로 갈랐다.

opus는 판단·추론이 드는 일에 붙인다. 모호한 요구를 구체화하고(requirement-planner), 아키텍처를 결정하고(senior-clean-architect), 코드의 위험을 가늠하고(code-reviewer), 프로젝트를 가로질러 방향을 회고하고(librarian), 사람 냄새 나는 글을 빚는(blogger) 일이다. 답이 하나로 딱 떨어지지 않고, 여러 선택지의 무게를 재야 하는 일들.

sonnet은 결정론적이고 기계적인 일에 붙인다. 빌드를 돌려 통과 여부를 보고하고(test-runner), diff를 읽어 커밋 타입을 판정해 메시지를 짓는(commit-manager) 일이다. 절차가 명확하고 채점표가 있어서, 비싼 추론을 태울 이유가 없다.

핵심은 값비싼 추론을 모든 일에 뿌리지 않는다는 것이다. 티어링은 각 정의의 model 필드 한 줄로 박아뒀고, 라우터(CLAUDE.md)의 에이전트 표에도 그대로 드러난다.

순차 파이프라인과 병렬 팬아웃

기본 개발 사이클은 순차로 이어 붙는다. 요청 하나가 알맞은 에이전트를 타고 흐른다.

여기서 검증 단계가 핵심이다. test-runner(빌드가 되나)와 code-reviewer(코드가 괜찮나)는 서로의 결과를 안 기다린다. 그래서 한 번에 둘 다 띄운다. 순차로 하면 검증에 두 번 걸릴 시간이 한 번으로 줄고, 둘 다 격리돼 있으니 서로의 로그로 오염되지도 않는다.

팬아웃이 진짜 위력을 내는 건 조사형 작업이다. 이 위키들을 채우려고 여러 프로젝트의 코드를 한꺼번에 전수조사할 때, 서브에이전트 15개+를 병렬로 띄웠다. 각자 다른 프로젝트를 격리된 컨텍스트에서 파고, 오케스트레이터는 열다섯 갈래의 덤프가 아니라 열다섯 장의 요약만 받아 엮었다. 한 대화로 순차 조사를 했다면 시간도 시간이지만, 컨텍스트가 진작 넘쳐 뒤쪽 프로젝트는 앞쪽을 잊은 채 봤을 것이다.

지금 읽는 이 문서 자체가 같은 패턴의 산물이다. 이 기술 노트 네 편(멀티에이전트·MCP·LLM 판정·실시간 렌더링)은 서로 독립이라, 각각을 맡은 에이전트가 동시에 자기 근거를 조사해 자기 문서를 쓰고 있다. 오케스트레이션을 설명하는 문서가 오케스트레이션으로 쓰이는 셈이다.

언제 위임하고 언제 인라인인가

위임이 공짜는 아니다. 에이전트를 스폰하고, 지시를 넘기고, 결과를 받아 엮는 왕복 비용이 든다. 그래서 경계가 있다.

위임한다: 여러 파일·프로젝트를 가로지르는 넓은 조사, 서로 독립이라 동시에 굴릴 수 있는 일, 과정의 덤프는 필요 없고 결론만 있으면 되는 일. 검증·리뷰·전수조사가 여기 든다.

인라인으로 한다: 이미 위치를 아는 파일 한 곳의 단일 조회. 어느 심볼이 어디 있는지 아는데 굳이 조사 에이전트를 띄우는 건, 왕복 비용이 이득보다 크다. 이미 위임받아 도는 에이전트가 자기 임무를 통째로 또 다른 에이전트에 재위임하는 것도 금물이다. 받은 일은 직접 끝낸다.

에이전트 수에도 같은 경계가 있다. 너무 적으면 범용화로 전문성이 흐려지고, 너무 많으면 선택 비용과 유지보수가 는다. 그래서 3~7개 선에서, "혹시 필요할까봐" 미리 만들지 않고 반복 패턴이 보일 때만 추가한다(그 판단 근거는 AI 하네스플레이북AI 하네스Claude Code를 무인으로 부리려고 짠 협업 하네스.에 정리했다). 지금 일곱 개는 그 상한이다.

Decision Log

배운 것

한 대화에 다 시키는 건 편하지만, 규칙 희석·컨텍스트 오염·순차 병목이라는 세 가지 세금을 낸다. 그걸 구조로 푸는 게 멀티 에이전트다. 역할로 나누면 매번 설명할 필요가 없고, 컨텍스트를 격리하면 탐색의 부산물이 판단을 밀어내지 않고, 병렬로 띄우면 독립인 일이 한 번에 끝난다.

다만 위임은 공짜가 아니라서, 무엇을 나누고 무엇을 그냥 인라인으로 할지가 실력이 된다. 이 위키를 채운 열다섯 갈래 조사도, 지금 이 문서도 그 판단 위에서 굴렀다. 나눌 값어치가 있는 일을 나누는 것 — 거기까지가 오케스트레이션이다.