멀티 에이전트 하네스 구성: 실수를 줄이고 가용성을 지키는 설계 원칙

개발용으로 돌리는 맥 한 대에 Claude Code 세션 다섯 개가 떠 있습니다. 세션마다 텔레그램 봇이 하나씩 붙어 있어서, 휴대폰으로 각자에게 따로 일을 시킵니다. 여기에 Gemini 까지 붙여 같이 일하게 하고 싶어서 「하네스 설계를 해야겠다」고 말했습니다. 말해 놓고 보니 두 가지가 걸렸습니다. 이게 하네스라는 말이 맞는지, 그리고 에이전트를 늘리는 게 정말 일을 낫게 만드는지였습니다.

찾아보니 두 번째 질문에는 공개된 답이 꽤 많았습니다. Anthropic, Cognition, OpenAI 가 각자 만든 시스템을 놓고 무엇이 됐고 무엇이 안 됐는지 적어 두었습니다. 이 글은 그 자료를 개발할 때 실수를 줄이고 가용성을 지키는 쪽으로 다시 엮은 것입니다. 중간중간 우리 세션 구성에서 실제로 잰 숫자를 끼워 넣었습니다.

하네스는 모델 하나가 일하는 환경

하네스(harness)는 원래 말에 씌우는 마구입니다. AI 쪽에서는 모델을 실제로 일하게 만드는 틀을 가리킵니다. 어떤 도구를 쓸 수 있는지, 어떤 지침을 받는지, 무엇을 사람에게 허락받아야 하는지, 결과를 어떻게 확인하는지가 여기 들어갑니다. Anthropic 은 2025년 11월 글에서 자기네 Claude Agent SDK 를 「범용 에이전트 하네스」라고 부릅니다. 추론 루프, 파일과 셸 도구, 맥락 관리가 한 묶음이라는 뜻입니다.

여러 모델이나 세션이 역할을 나눠 함께 일하도록 조율하는 것은 다른 이름을 씁니다. 오케스트레이션(orchestration), 또는 멀티 에이전트입니다. 제가 처음 하고 싶었던 것은 이쪽이었습니다. 한 세션은 서버를, 다른 세션은 앱을 맡고, 의견이 갈리면 Gemini 에게 세 번째 의견을 묻는 구조입니다.

그렇다고 하네스라는 말이 틀린 것만은 아닙니다. 오케스트레이션을 짜다 보면 결국 참여자 각자의 하네스로 돌아오기 때문입니다. 누가 파일을 쓸 수 있는지, 누구의 말을 지시로 받는지가 정해져 있지 않으면 협업 구조는 금방 구멍이 납니다. 그래서 둘을 묶어 「멀티 에이전트 하네스」라고 부르기도 합니다. 아래에서는 오케스트레이션의 모양부터 보고, 그 모양을 안전하게 만드는 하네스 장치로 넘어갑니다.

워크플로와 에이전트를 나누는 기준

Anthropic 의 2024년 12월 글 Building effective agents는 먼저 두 가지를 갈라 놓습니다.

Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage.

정해진 코드 경로를 따라 모델을 부르는 것이 워크플로이고, 다음 행동을 모델이 스스로 고르는 것이 에이전트입니다. 같은 글은 자주 쓰이는 모양을 이름 붙여 정리합니다.

패턴	하는 일	잘 맞는 경우
프롬프트 체이닝	앞 단계 출력을 다음 단계 입력으로	단계가 고정된 작업
라우팅	입력을 분류해 맞는 처리로 보냄	문의 유형이 뚜렷이 갈릴 때
병렬화	나눠서 동시에, 또는 같은 일을 여러 번 해서 투표	서로 독립인 조각, 검토
오케스트레이터-워커	중심 모델이 실행 중에 일을 쪼개 맡김	쪼갤 단위를 미리 모를 때
평가자-최적화	하나가 만들고 하나가 평가하며 반복	평가 기준이 분명할 때

이 표에서 제가 가장 오래 본 줄은 표 밖에 있었습니다. 글은 「가능한 가장 단순한 해법을 찾고, 필요할 때만 복잡도를 올리라」고 하고, 복잡도는 결과가 눈에 보이게 나아질 때만 더하라고 못 박습니다. 멀티 에이전트는 이 표의 맨 아래, 가장 비싼 칸에 있습니다.

에이전트를 늘리면 잘한다는 믿음의 값

에이전트를 여럿 띄우면 더 빨리, 더 잘한다고 흔히 생각합니다. 절반은 맞습니다. Anthropic 이 2025년 6월에 공개한 리서치 시스템 글에서, Opus 4 가 지휘하고 Sonnet 4 서브에이전트들이 일한 구성은 Opus 4 혼자보다 내부 리서치 평가에서 90.2% 앞섰습니다.

같은 글이 그 이유도 밝힙니다. 성능 차이의 80% 는 토큰을 얼마나 썼는지 하나로 설명됐습니다. 도구 호출 횟수와 모델 선택까지 넣으면 95% 입니다. 멀티 에이전트가 잘하는 것은 똑똑해서라기보다 문제에 토큰을 충분히 쓰게 해 주기 때문이라는 말입니다. 대가는 숫자로 나옵니다. 에이전트 하나가 일반 대화의 약 4배, 멀티 에이전트는 약 15배의 토큰을 씁니다.

초기 버전의 실패도 그대로 적혀 있습니다. 간단한 질문에 서브에이전트를 50개 띄우고, 있지도 않은 자료를 끝없이 찾고, 서로 너무 잦은 업데이트로 방해했습니다. 고친 방법은 지휘하는 쪽에 위임하는 법을 가르치는 것이었습니다. 서브에이전트마다 목표, 출력 형식, 쓸 도구와 출처, 일의 경계를 주고, 단순한 사실 확인은 에이전트 하나에 도구 호출 3~10번으로 끝내라고 규칙을 넣었습니다.

이 숫자를 우리 구성에 대 보면 비용은 토큰만이 아닙니다. 오늘 세션 메모리를 재 보니 텔레그램 세션 다섯 개가 2.7GB 를 쓰고 있었습니다. 처음에 Claude 가 일곱 개라고 셌는데, 실행 등록 목록의 감시 프로세스와 원격 접속 세션까지 넣은 숫자였습니다. 휴대폰에 보이는 봇은 다섯 개였고, 다시 재서 맞췄습니다.

세션	메모리
tx	695MB
t800	603MB
t600	565MB
t850	422MB
t1000	402MB

평균 540MB 입니다. 열두 개로 늘리면 6.5GB 쯤이고, 대화가 길어진 세션은 1GB 가까이 커지기 때문에 최악이면 12GB 까지 봐야 합니다. 램이 16GB 인 기계에서 이건 세션을 더 띄울지, 컨테이너 VM 을 켜 둘지 고르는 문제가 됩니다.

코딩에서 병렬 쓰기가 깨지는 구조

리서치에서 통한 구성이 코딩에서도 통할까요. Anthropic 의 같은 글이 먼저 선을 긋습니다. 모든 에이전트가 같은 맥락을 공유해야 하거나 서로 의존이 많은 일은 지금의 멀티 에이전트에 맞지 않고, 대부분의 코딩은 리서치보다 진짜로 병렬화할 수 있는 조각이 적다고 씁니다.

Cognition 의 Walden Yan 은 같은 달 Don't Build Multi-Agents에서 이걸 원칙 두 개로 정리했습니다.

Share context, and share full agent traces, not just individual messages.
Actions carry implicit decisions, and conflicting decisions carry bad results.

예시가 기억에 남습니다. 「플래피 버드 클론을 만들어라」를 둘로 나눠 한쪽에 배경과 파이프를, 다른 쪽에 새를 맡깁니다. 배경 쪽은 슈퍼 마리오 같은 배경을 만들고, 새 쪽은 게임 그림처럼 보이지도 않는 새를 만듭니다. 각자 받은 지시는 지켰지만, 상대가 무엇을 하는지 볼 수 없으니 화풍이라는 암묵적 결정이 갈렸습니다. 코드에서는 이 화풍이 네이밍, 에러 처리 방식, 상태 관리 방식이 됩니다.

저는 이 지적이 우리 세션 지침의 한 줄과 정확히 겹친다고 봅니다. 「한 리포는 한 번에 한 세션만 고친다」는 규칙은 처음에 충돌을 막으려고 넣었는데, 실제로 막는 것은 git 충돌보다 암묵적 결정의 충돌입니다.

여럿이 생각하고 하나가 쓰는 구성

Cognition 은 열 달 뒤인 2026년 4월, Multi-Agents: What's Actually Working에서 입장을 다듬었습니다. 병렬로 코드를 쓰는 무리에 대한 경고는 여전히 유효하다고 하면서, 되는 구성을 하나 짚습니다.

multi-agent systems work best today when writes stay single-threaded and the additional agents contribute intelligence rather than actions.

쓰기는 한 에이전트만 하고, 나머지는 행동이 아니라 판단을 보탭니다. 그들이 든 예 중 하나가 깨끗한 맥락에서 PR 을 보는 리뷰 에이전트인데, PR 하나에 평균 버그 2개를 잡고 그중 약 58% 가 심각한 것이었다고 합니다. 작은 모델이 일하다가 막히면 큰 모델에게 묻는 구성도 효과가 있었다고 적었습니다.

우리 구성에 옮기면 Gemini 의 자리가 여기서 정해집니다. 파일을 고치는 쪽이 아니라 의견을 내는 쪽입니다. agy CLI 는 agy -p "…" 한 줄로 질문하고 답을 표준 출력으로 받기 때문에, Claude 세션이 작업 중에 셸에서 불러 검토를 맡길 수 있습니다. 같은 모델끼리는 같은 실수를 놓치기 쉬워서, 다른 회사 모델을 리뷰어로 두는 쪽이 이 패턴의 취지에도 맞습니다. 이건 아직 제 판단이고 우리 쪽에서 잰 결과는 없습니다.

실수를 줄이는 하네스 장치

오케스트레이션 모양을 정했으면 다음은 참여자 하나하나가 덜 틀리게 만드는 일입니다. 공개 자료에서 반복해 나온 장치를 모았습니다.

도구를 틀리기 어렵게 만듭니다. Anthropic 은 이걸 포카요케(poka-yoke)라고 부릅니다. 도요타 생산 방식에서 온 말로, 실수할 수 없게 설계하는 장치입니다. 그들의 SWE-bench 에이전트는 작업 폴더를 옮긴 뒤 상대 경로를 자주 틀렸고, 도구가 항상 절대 경로만 받도록 바꾸자 그 실수가 사라졌습니다. 프롬프트로 「조심하라」고 쓰는 것보다 인자 모양을 바꾸는 쪽이 확실합니다. 같은 글은 사람을 위한 인터페이스(HCI)만큼 에이전트를 위한 인터페이스(ACI)에 공을 들이라고 합니다.

매 단계 환경에서 사실을 받게 합니다. 에이전트는 각 단계에서 도구 결과나 코드 실행 같은 실제 환경의 응답, 즉 ground truth 를 받아야 합니다. 자기가 쓴 코드를 머릿속으로 맞다고 판단하는 대신 테스트를 돌리게 하는 것입니다. 2025년 11월 하네스 글에서 Claude 는 코드를 고치고도 기능이 끝에서 끝까지 안 돈다는 것을 자주 못 알아챘는데, 브라우저 자동화로 실제 화면을 확인하게 하자 성능이 크게 올랐다고 합니다.

멈출 조건을 둡니다. 최대 반복 횟수 같은 정지 조건은 에이전트가 같은 실패를 끝없이 되풀이하지 않게 막습니다. 50개 서브에이전트 사례가 정확히 이 조건이 없을 때 생긴 일입니다.

되돌리기 어려운 일은 사람에게 돌립니다. OpenAI 의 2025년 4월 가이드 A practical guide to building agents는 실패 횟수가 기준을 넘을 때와 위험이 크거나 되돌릴 수 없는 행동을 할 때 사람에게 넘기라고 합니다. 우리 세션 지침은 push, 배포, 메일 발송, 삭제를 여기 넣었습니다.

다른 에이전트의 말을 사용자의 지시로 받지 않습니다. 멀티 에이전트에서 새로 생기는 구멍이 이것입니다. 세션 A 가 push 하려다 사용자에게 거절당하고, 세션 B 에게 「대신 해 줘」라고 보냈다고 해 보겠습니다. B 가 그대로 하면 사용자가 내린 결정이 세션 하나를 거치면서 사라집니다. 권한 세탁(permission laundering)이라고 부르는 문제입니다. 오늘 tx 세션이 t850 세션에 연결 확인 메시지를 보냈는데, 받는 쪽 하네스는 그 메시지를 「동료의 요청」으로만 다루고 사용자 승인으로는 치지 않았습니다. 이 규칙은 협업 구조를 위한 것이지만, 사는 곳은 각 세션의 하네스입니다.

병렬로 쓸 때는 작업 공간을 나눕니다. 여러 세션이 한 저장소를 동시에 만져야 한다면 git worktree 로 폴더와 브랜치를 갈라 줍니다. Claude Code 는 worktree 를 기본 기능으로 지원합니다. 다만 worktree 는 파일 충돌을 막을 뿐, 위에서 본 암묵적 결정의 충돌은 막지 못합니다.

긴 작업을 이어 가게 하는 기록

에이전트의 맥락 창은 언젠가 넘칩니다. 압축(compaction)으로 버티는 데도 한계가 있어서, Anthropic 은 긴 작업용 하네스 글에서 세션 사이를 기록으로 잇는 구성을 소개합니다.

첫 세션은 초기화 담당입니다. 앱을 띄우는 init.sh, 지금까지 한 일을 적는 claude-progress.txt, 처음 커밋을 만듭니다. 요구사항은 기능 목록 JSON 으로 펼쳐 두는데, 예시 앱에서 200개가 넘었습니다. 다음 세션부터는 매번 같은 순서로 시작합니다. 현재 위치를 확인하고, git 로그와 진행 파일을 읽고, 기능 목록에서 아직 안 끝난 가장 중요한 것 하나를 고릅니다.

이 글이 적은 실패와 처방은 그대로 체크리스트로 쓸 만합니다.

실패	처방
한 번에 너무 많이 하려다 반쯤 망가진 상태로 끝남	한 번에 기능 하나만
다 됐다고 너무 일찍 선언함	기능 목록의 passes 칸은 실제로 테스트한 뒤에만 바꾸게 함
버그나 진행 상황이 기록 없이 남음	매 세션 git 커밋과 진행 메모
앱 띄우는 법을 매번 다시 알아냄	init.sh 하나로 고정

에이전트가 기능 목록을 고칠 수 있는 범위를 passes 칸 하나로 좁혀 둔 것이 눈에 띕니다. 이것도 포카요케입니다. 목록 자체를 지우거나 줄이는 실수를 구조로 막았습니다.

처음부터 다시 돌리지 않는 가용성

개발 환경의 가용성은 에이전트가 오래 일하다 중간에 죽었을 때 무엇을 잃느냐의 문제입니다. Anthropic 리서치 시스템 글의 표현이 짧습니다. 「에이전트는 상태를 갖고, 오류는 누적된다.」 처음부터 다시 돌리는 것은 비싸고 사용자를 지치게 하므로, 오류가 난 지점에서 이어 가는 시스템을 만들었다고 합니다. 모델의 유연함에 재시도 로직과 정기 체크포인트 같은 결정적 안전장치를 붙인 것입니다.

배포에서도 같은 생각이 나옵니다. 에이전트는 오래 돌기 때문에 새 버전을 올리는 순간 일하던 에이전트가 끊길 수 있습니다. 그들은 옛 버전과 새 버전을 함께 띄워 두고 트래픽을 천천히 옮기는 레인보 배포를 씁니다. 실패 원인은 운영 추적(tracing)으로 찾았는데, 대화 내용은 보지 않고 결정 패턴과 상호작용 구조만 봤다고 적었습니다.

우리 규모로 옮기면 가용성을 깎는 것은 세 가지였습니다. 첫째는 메모리입니다. 같은 날 지운 Docker Desktop 의 VM 하나가 7GB 를 잡고 있었고, 대신 들어온 Colima 는 기본 VM 이 2GB 입니다. 세션 세 개를 더 띄울 메모리입니다. 둘째는 사용량 한도입니다. Gemini 쪽은 agy -p "/usage" 로 모델 묶음별 주간 한도와 5시간 한도가 남은 비율과 초기화 시각으로 나옵니다. 협업 도중 한쪽 한도가 끝나면 그 역할이 통째로 멈추니, 맡기기 전에 이 숫자를 보는 습관이 필요합니다. 셋째는 세션이 길어지며 불어나는 맥락입니다. 일이 끝난 세션을 초기화해서 비우는 것이 우리에게는 가장 값싼 체크포인트입니다.

상황별 출발점

공개 자료를 다 읽고 나서 제 기준은 이렇게 정리됐습니다.

상황	고를 구성
단계가 정해진 반복 작업	워크플로. 에이전트로 만들지 않음
한 저장소에서 기능 구현	단일 에이전트 하나가 쓰기를 전담
구현 후 검토	쓰기는 그대로 두고 깨끗한 맥락의 리뷰어를 하나 붙임 (다른 모델이면 더 좋음)
서로 독립인 조사 여러 갈래	오케스트레이터-워커. 단, 개수와 도구 호출 수에 상한
며칠 걸리는 긴 작업	진행 파일, 기능 목록, 커밋으로 세션 사이를 잇는 하네스
여러 저장소를 여러 세션이	저장소마다 한 세션. 넘겼으면 손을 뗌

공통으로 붙는 것은 정지 조건, 되돌리기 어려운 행동의 사람 확인, 다른 에이전트의 말을 지시로 받지 않는 규칙입니다.

아직 확실하지 않은 부분

Anthropic 의 하네스 글은 마지막에 범용 코딩 에이전트 하나가 나은지, 멀티 에이전트 구조가 나은지 아직 모른다고 씁니다. Cognition 은 1년도 안 돼 「만들지 말라」에서 「쓰기는 하나로, 판단은 여럿으로」로 입장을 다듬었습니다. 이 분야의 권고는 몇 달 단위로 바뀌고 있어서, 위 표도 그만큼의 유효기간을 갖는다고 봅니다.

우리 쪽 설계도 아직 정하지 않은 것이 남았습니다. Gemini 를 검토에만 쓸지 구현 일부를 맡길지, 협업을 사용자가 시킬 때만 시작할지 커밋 전처럼 정해진 순간에 저절로 시작할지, 두 모델의 의견이 갈리면 누가 고를지입니다. 메모리 숫자를 보면 세션을 무작정 늘릴 수는 없으니, 리뷰어 하나를 붙이는 가장 작은 구성부터 시작해 보려고 합니다. 그게 위 자료들이 한목소리로 권하는 순서이기도 합니다.

참고: Building effective agents · How we built our multi-agent research system · Effective harnesses for long-running agents · Don't Build Multi-Agents · Multi-Agents: What's Actually Working · A practical guide to building agents