클로드 코드 하니스 설계: 멀티 에이전트 오케스트레이션

혼자 돌리는 클로드 코드는 똑똑한 도구입니다. 그러나 작업 단위가 커지면 한 명의 에이전트로는 부족합니다. 이때부터는 모델 자체가 아니라 모델을 둘러싼 하니스(harness)와,
다수의 에이전트를 지휘하는 오케스트레이션 설계가 결과 품질을 좌우합니다. 이 글은 하니스 엔지니어링의 의미, 멀티 병렬 에이전트 패턴,
바이브 코딩이 깨지는 지점과 구조화 코딩으로 전환하는 분기 기준을 디테일하게 정리합니다.

이 가이드는 Claude Code(Anthropic 공식 CLI) 2026년 5월 기준입니다. Managed Agents·서브에이전트 사양은 빠르게 진화 중이므로 Anthropic 공식 문서와 Managed Agents Overview를 함께 참고하세요. 클로드 코드 자체 사용법이 처음이라면 클로드 코드 100배 활용 가이드부터 보시면 도움이 되고, 용어가 낯설면 AI-native 개발자 용어집을 함께 펼쳐두면 좋습니다.

하니스란 무엇이고 왜 엔지니어링하는가#

Anthropic 엔지니어링 팀은 하니스를 모델 자체가 아닌 모든 코드·설정·실행 로직으로 정의합니다. 이 정의에 따르면 Claude Code·Cursor·Codex·Aider·Cline 모두 하니스입니다. 즉 우리가 평소 "AI 코딩 도구"라고 부르는 제품은 사실 모델 + 하니스의 묶음이며,
같은 모델을 쓰더라도 어떤 하니스 안에 두느냐에 따라 결과가 크게 달라집니다.

핵심 통찰은 다음 한 문장으로 요약됩니다.

"하니스의 모든 컴포넌트는 모델이 혼자 못하는 무언가에 대한 가정을 인코딩한다." (Anthropic Engineering, "Harness design for long-running application development")

모델이 약한 영역에는 가드레일·검증·재시도 같은 구조가 필요합니다. 모델이 강해진 영역에서는 같은 구조가 오히려 짐이 되어 제거 대상이 됩니다. 다시 말해 하니스 엔지니어링은 모델 능력의 변화에 맞춰 보조 장치를 더하고 빼는 작업입니다. 모델 버전이 올라갈 때마다 하니스를 점검하지 않으면, 작년의 가드가 올해의 병목이 됩니다.

하니스의 5요소: 컨트롤 플레인의 구성#

Claude Code 환경에서 하니스를 구성하는 다섯 축은 다음과 같습니다. 각 축은 mastery-guide에서 정의한 기초 기능을 오케스트레이션 관점에서 묶어낸 것입니다.

이 5축은 독립이 아니라 서로를 강화합니다. 예를 들어 CLAUDE.md(①)가 "DB 변경은 항상 read-only 워커로 사전 검증"이라는 정책을 명시하면,
그 정책은 서브에이전트 라우팅(④) 규칙으로 작동하고,
권한 화이트리스트(⑤)에 의해 강제됩니다. 정책 한 줄이 세 축에 동시에 영향을 미치는 구조가 잘 설계된 하니스의 특징입니다.

모델 vs 하니스 영향력#

같은 모델이라도 하니스 수준에 따라 결과가 어떻게 달라지는지 직관적으로 정리하면 다음과 같습니다.

표가 시사하는 바는 분명합니다. 하니스 투자에는 한계 효용이 있고, 그 정점은 멀티 에이전트 오케스트레이션입니다. 단, 정점에 가까워질수록 운영·관측 비용도 함께 올라가므로,
모든 작업을 정점으로 끌고 가는 게 답은 아닙니다. 작업 성격에 맞는 지점을 고르는 것이 진짜 엔지니어링입니다.

멀티 병렬 에이전트: 오케스트레이터-워커 패턴#

오케스트레이터-워커 패턴은 멀티 에이전트의 가장 흔한 형태입니다. 메인 에이전트가 지휘자가 되어 작업을 분해 → 병렬 송출 → 결과 집계의 3단계로 처리합니다. 워커는 자신만의 컨텍스트 윈도우를 가지며, 부모에게는 압축된 요약만 돌려줍니다.

3가지 실행 토폴로지#

오케스트레이션은 토폴로지(작업 의존 관계의 그래프 모양)에 따라 세 가지로 나뉩니다.

실전에서 가장 흔한 형태는 DAG입니다. 예를 들어 "코드 변경 → 동시에 테스트 작성·문서 갱신·CHANGELOG 업데이트 → 모든 결과 통합 후 PR 본문 작성" 같은 흐름은 가운데 단계가 병렬,
양 끝이 직렬인 DAG입니다.

단일 메시지 다중 호출: 진짜 병렬은 여기서 나온다#

병렬은 두 가지 방식으로 가능합니다. 하나는 부모가 한 응답 안에서 여러 워커를 동시에 호출하는 방식,
다른 하나는 별도 에이전트 인스턴스를 외부 시스템(예: GitHub Actions)에서 동시에 띄우는 방식입니다. 클로드 코드 안에서는 전자가 기본입니다.

// 메인 에이전트의 한 응답 안에서 3개 Explore 워커를 동시 호출 (의사코드)
Agent(subagent_type=Explore, description="DB 스키마 탐색", prompt="...")
Agent(subagent_type=Explore, description="API 엔드포인트 추출", prompt="...")
Agent(subagent_type=Explore, description="인증·세션 흐름 추적", prompt="...")

이 패턴의 효과는 두 가지입니다. 첫째, 세 개의 무거운 검색이 메인 컨텍스트를 오염시키지 않습니다. 워커들은 각자의 200K 윈도우에서 결과를 만들고 압축된 요약만 돌려보냅니다. 둘째, 세 검색이 동시에 진행되어 직렬 대비 시간이 약 1/N로 줄어듭니다.

다만 동시 실행이 항상 좋은 것은 아닙니다. 워커가 너무 많으면 결과 집계 비용이 분해 이득을 상쇄합니다. 실전 권장은 한 번의 분해당 2–3개 워커,
5개를 넘기기 전에 한 번 멈춰서 진짜 병렬이 필요한지 점검하는 흐름입니다.

멀티 병렬이 빛나는 3가지 시나리오#

언제 멀티 병렬이 직렬보다 명백히 유리한지 정리하면 다음과 같습니다.

1. 레거시 코드베이스 1차 매핑: 스키마·라우팅·인증을 3 워커로 동시에 탐색해 초안 지도를 빠르게 그립니다. 메인은 세 요약을 받아 의존 관계만 그립니다.
2. 테스트 보강: 변경된 함수마다 1 워커씩 띄워 테스트 시나리오 생성·기존 테스트 패턴 검증·초안 작성을 분리합니다. 함수 간 영향이 없을 때 가장 효과적입니다.
3. 마이그레이션 검증: 1 워커는 변경 전 동작 시뮬레이션, 1 워커는 변경 후, 메인이 두 결과의 차이를 비교합니다. 변경 전 동작을 직접 실행할 수 없는 환경에서도 작동합니다.

세 시나리오의 공통점은 작업이 본질적으로 독립적이라는 점입니다. 의존성이 강한 작업을 억지로 병렬로 묶으면 마지막 단계에서 결과가 충돌해 직렬로 다시 풀어야 합니다.

하니스 5축을 오케스트레이션 관점에서 다시 보기#

기초를 익혔다면, 5축 각각이 멀티 에이전트 환경에서 어떻게 재해석되는지가 다음 단계입니다.

1. CLAUDE.md를 "control plane"으로#

기초 단계에서는 CLAUDE.md가 프로젝트 메모리입니다. 오케스트레이션 단계에서는 라우팅 정책의 단일 진실 원천입니다. 다음과 같은 규칙은 모두 컨트롤 플레인에 속합니다.

• "3 파일 이상 영향을 주는 작업은 항상 Plan 모드로 진입한다"
• "DB 스키마 변경은 read-only 워커로 사전 검증을 거친 뒤에만 쓰기 워커가 실행한다"
• "외부 API 호출이 포함된 작업은 사용자 승인을 자동 우회하지 않는다"

이런 정책이 한 곳에 모여 있으면, 메인 에이전트가 새 작업을 받았을 때 어떤 토폴로지로 분해할지를 결정하는 근거가 됩니다.

2. 스킬 체이닝: 직렬 SOP의 코드화#

스킬은 한 장의 마크다운으로 정의되는 절차이며, /name 호출과 모델의 자율 호출이 모두 가능합니다. 두 개 이상의 스킬을 직렬로 묶으면 /review → /fix-tests → /update-changelog 같은 파이프라인이 만들어집니다. 각 스킬은 입력·출력 형식이 명확해야 직렬 합성이 됩니다.

3. MCP를 도구 라우터로#

MCP는 외부 시스템과의 연결 표준입니다. 오케스트레이션 관점에서는 작업별 도구 화이트리스트로 다뤄야 합니다. 모든 MCP를 항상 켜두면 도구 정의가 컨텍스트를 잠식해 실효 윈도우가 줄어들고,
의도 외 호출 위험도 커집니다. 작업 성격에 따라 MCP를 동적으로 켜고 끄는 운영이 안전합니다.

4. 훅(hooks)을 이벤트 버스로#

훅은 특정 이벤트(도구 호출 직전·직후, 응답 종료 등)에 자동으로 실행되는 셸 명령입니다. 오케스트레이션 관점에서 훅은 이벤트 버스입니다. 예를 들어 PostToolUse 훅으로 git 커밋이 발생할 때마다 자동 lint를 돌리거나,
Stop 훅으로 응답 종료 시 데스크톱 알림을 띄우는 식입니다. 훅은 메인 에이전트의 손을 빌리지 않고도 부수 작업을 자동화합니다.

5. 권한 분리: 위험 작업은 한 워커에만#

가장 중요한 운영 원칙은 위험 권한을 한 종류 워커에만 부여하는 것입니다. 메인 에이전트는 항상 read-only로 두고, 쓰기·셸 실행은 별도 워커에 위임합니다. 그 워커는 좁은 도구 화이트리스트와 명확한 입력·출력 계약을 갖습니다. 권한이 분산되면 의도 외 동작의 발생 지점을 추적하기 어려워집니다.

바이브 코딩 vs 구조화된 오케스트레이션#

오케스트레이션 이야기를 하다 보면 자연스럽게 마주치는 질문이 있습니다. "그럼 바이브 코딩은 끝났는가?" 결론부터 말하면 아닙니다. 두 모드는 경쟁이 아니라 비용 분기점에 따라 선택하는 도구입니다.

바이브 코딩의 정의#

바이브 코딩(Vibe Coding)은 Andrej Karpathy가 2025년 2월에 X에 올린 한 줄에서 시작된 표현입니다. 원문 표현을 거칠게 옮기면 "코드 자체를 잊고 바이브에 몸을 맡기는 새로운 코딩",
자연어로 의도만 던지고 결과를 보면서 바로 다음 한마디를 하는 즉흥 반복 흐름입니다. LLM이 충분히 좋아져 손으로 한 줄씩 적을 필요가 줄어든 시점에 이름이 붙은 셈입니다. 2025년 콜린스 사전이 올해의 단어 후보로 거론할 만큼 빠르게 대중화됐습니다.

이 표현이 빠르게 퍼진 이유는 경험 그 자체를 정확히 짚었기 때문입니다. 작은 페이지 한 장, 짧은 스크립트 하나는 바이브 코딩이 가장 빠릅니다. 사양을 정식 문서로 정리하는 시간보다 의도를 한 문장으로 던지는 시간이 압도적으로 짧고,
결과 검증도 즉시 가능합니다.

바이브가 깨지는 지점#

문제는 작업의 비용 구조가 변할 때입니다. 바이브 코딩은 결과 검증이 즉시 가능하고, 실수 비용이 작을 때만 안전합니다. 다음과 같은 신호가 보이면 더 이상 바이브로 가면 안 됩니다.

• 작업이 3 파일 이상 영향을 줍니다.
• 결과가 맞는지 확인하는 비용이 작성 비용보다 큽니다.
• 한 번의 실수가 운영(DB·결제·인증·계약)에 즉시 반영됩니다.
• 결과를 협업자가 PR이나 보고서로 받습니다.

이 시점부터는 분해·정책·검증 체크포인트가 필요한 구조화 오케스트레이션으로 전환해야 합니다.

분기 시그널: 어느 쪽으로 갈지 30초 안에 판단하는 표#

다섯 줄 중 두 줄 이상이 오른쪽이면 구조화로 가는 것이 안전합니다. 한 줄만 오른쪽이면 바이브로 시작해도 됩니다. 두 모드를 자유롭게 오가는 능력이 AI 시대 시니어의 새로운 표식입니다. 바이브만 고집하면 사고가 누적되고,
구조화만 고집하면 작은 일에도 과도한 의식이 붙어 속도가 떨어집니다.

멀티 에이전트 특유의 함정·실패 사례#

멀티 에이전트 환경은 단일 에이전트와 다른 종류의 사고를 만듭니다. 각 항목을 원인 → 증상 → 대응으로 정리합니다.

1. 컨텍스트 기근 (Context Starvation)#

원인: 부모가 너무 많은 워커를 띄워, 자신의 컨텍스트가 워커 결과 요약으로 가득 찹니다.

증상: 다음 결정 단계에서 메인이 이전 정책을 잊은 듯한 동작을 보이거나, 환각률이 갑자기 올라갑니다.

대응: 워커 결과는 짧은 요약 + 키 데이터 포인터 형태로만 받습니다. 라우팅 결정이 끝나면 즉시 압축하거나 디스크에 저장하고 메인 컨텍스트에서 비웁니다.

2. 권한 폭증 (Permission Sprawl)#

원인: 워커 다수에 자동 승인 권한이 누적되어, 어디서 어떤 작업이 일어났는지 추적이 어려워집니다.

증상: 의도하지 않은 파일 수정·외부 호출이 발견되었을 때 책임 워커를 특정하지 못합니다.

대응: 위험 권한은 단일 워커 전용으로 묶고, 메인은 항상 read-only를 유지합니다. 모든 쓰기는 명시적 라우팅을 거쳐야 합니다.

3. 결과 충돌 (Race-Condition 유사)#

원인: 두 워커가 같은 파일·같은 자원을 동시에 수정합니다.

증상: 마지막 쓰기가 이전 쓰기를 덮어써 변경이 사라지거나, git에 충돌이 발생합니다.

대응: 쓰기는 직렬화합니다. 읽기·분석만 병렬화하고, 쓰기 단계는 단일 워커가 순서대로 처리합니다.

4. 의도 분기점 누락#

원인: 부모가 명확한 분해 없이 "둘 다 해줘"라고 던지면
워커들이 같은 가설로 수렴해 동일한 답을 가져옵니다.

증상: 병렬을 띄웠는데 결과가 거의 같아 비용만 두 배가 되고 정보 이득은 미미합니다.

대응: 분해 시 어떤 가설을 검증할지까지 명시해 워커별 관점이 갈리도록 설계합니다. 같은 코드를 보안 관점과 성능 관점으로 따로 보게 하는 식입니다.

5. 비용 통제 실패#

원인: 모든 워커가 가장 비싼 모델로 돌아갑니다.

증상: 한 작업의 토큰 비용이 며칠 만에 예산을 초과합니다.

대응: 모델 라우팅을 적용합니다. 탐색·요약은 Haiku급, 작성·결정은 Opus급, 위험 판단·복잡 추론은 최상위 모델 식으로 작업 단계별 분배가 안정적입니다.

6. Eval 부재#

원인: 멀티 에이전트가 잘 돌아가는지 측정 자체를 하지 않습니다.

증상: 어느 날부터 결과가 나빠졌는데 언제부터인지·왜인지 알 수 없습니다.

대응: 작업 단위마다 성공 기준 한 줄을 미리 적습니다("이 PR이 머지 가능한가?", "이 보고서가 사람 검토 1회로 통과되는가?"). 끝에 자가 점검을 통과해야만 부모가 결과를 수락합니다.

자주 묻는 질문#

Q. 1인 개발자에게도 멀티 에이전트가 의미 있나요?

A. 작업이 3 파일 이상 영향을 주거나, 검증 비용이 작성 비용보다 크면 명백히 의미 있습니다. 1 파일 짜리 빠른 수정에는 분해·집계 오버헤드가 더 큽니다. 즉 하니스는 작업 크기에 비례해서 투자합니다.

Q. 단일 메시지에서 워커를 몇 개까지 띄우는 게 좋나요?

A. 실무 권장은 2–3개입니다. 5개를 넘기면 결과 집계 비용이 분해 이득을 상쇄하기 시작합니다. 정말 5+ 워커가 필요하다면 분해 단위를 잘못 잡았을 가능성을 먼저 점검합니다.

Q. 바이브 코딩을 완전히 버려야 하나요?

A. 아닙니다. 짧은 탐색·프로토타입은 여전히 바이브가 가장 빠릅니다. 핵심은 비용 분기점에서 모드를 전환할 줄 아는 것입니다. 한쪽만 고집하면 다른 쪽의 강점을 잃습니다.

Q. 하니스 엔지니어링은 어디서 더 깊게 배울 수 있나요?

A. 1차 출처를 우선합니다. Anthropic Engineering 블로그의 "Harness design for long-running application development", Managed Agents 문서, Model Context Protocol 사양이 가장 신뢰할 수 있는 출처입니다. 2차 자료는 빠르게 낡습니다.

Q. 멀티 에이전트가 잘 돌아가는지 어떻게 측정하나요?

A. 두 가지 지표가 출발점입니다. 첫째, 작업당 사람이 다시 손대는 비율. 둘째, 분해 시 워커 간 결론 일치율. 일치율이 너무 낮으면 분해가 너무 거칠고, 너무 높으면 의도 분기점이 누락된 신호입니다. 둘 다 시간이 지나면서 추세를 보는 것이 핵심입니다.

함께 보면 좋은 글#

• 클로드 코드 100배 활용 가이드: CLAUDE.md·MCP·서브에이전트 완전 정복: 본 포스트의 전제가 되는 기초 사용법
• AI-native 개발자 용어집: LLM·에이전트·DX·운영까지 35선: 에이전트·MCP·가드레일·eval 등 본문에 나온 용어의 정의 사전
• AI 시대 개발자 생존법: 페어 코딩·코드 리뷰·테스트 워크플로우 7단계: 페어 코딩 워크플로우 일반 원칙

---

Sources

• Anthropic Engineering: Harness design for long-running application development: 1차 출처 (하니스 정의·설계 원칙)
• Anthropic Engineering: Managed Agents: 1차 출처 (에이전트 인프라)
• Claude Managed Agents Overview: 1차 출처 (Managed Agents 사양)
• Claude Code Documentation: 1차 출처 (CLI 사양·서브에이전트·스킬)
• Andrej Karpathy: vibe coding origin tweet (2025-02-02): 1차 출처 (바이브 코딩 정의)
• Model Context Protocol Specification: 1차 출처 (MCP)