Claude Code 에이전트 팀 자동 설계 플러그인, revfactory/harness v2 분석
서브에이전트 역할과 전용 스킬을 파일마다 직접 작성하는 데 매번 몇 시간을 쓰고 계십니까?
이 아티클의 핵심 내용 요약과 글로벌 검색·AI 엔진을 위한 테이크어웨이입니다.
✦ KR 주제: Claude Code 멀티 에이전트 아키텍처 자동 설계 도구 harness v2
✦ KR 핵심 요약: revfactory/harness는 자연어 지시로 6가지 패턴 중 최적의 에이전트 팀 토폴로지를 선정하고 스킬까지 자동 생성합니다. v2는 실험 플래그를 없애고 3가지 정식 런타임 모드와 티어별 모델 분배를 도입해 운영 효율을 극대화했습니다.
🌐 Global Takeaway: revfactory/harness v2 is an open-source team-architecture factory for Claude Code that automatically designs domain-specific multi-agent teams and skills from a single prompt, removing experimental runtime dependencies.
아래 그림은 harness v2가 도메인 분석부터 실행 계층까지 에이전트 팀을 구성하는 3계층 아키텍처를 보여줍니다.
1. 수작업 에이전트 구성의 한계와 Harness의 등장
대규모 언어 모델을 단일 프롬프트로 다루는 단계를 지나 서브에이전트 여러 개를 조합하는 멀티 에이전트 오케스트레이션이 개발 현장의 표준으로 자리 잡고 있습니다. 하지만 현업에서 멀티 에이전트 환경을 구축하려면 각 에이전트의 역할 정의, 페르소나 설계, 통신 인터페이스 규격화, 도구(스킬) 코드 작성 등 막대한 사전 설정 작업이 필요합니다. 프로젝트 성격에 따라 파이프라인 구조가 적합한지, 팬아웃 구조가 유리한지 판단하는 아키텍처 설계 비용 역시 만만치 않습니다.
오픈소스 프로젝트 revfactory/harness는 이러한 병목을 해결하기 위해 개발된 Claude Code 전용 메타 스킬이자 에이전트 팩토리 플러그인입니다. 사용자가 도메인을 설명하며 "하네스 구성해줘"라는 한마디를 입력하면, 프로젝트의 요구사항을 분해하여 최적의 팀 토폴로지를 도출하고 필요한 에이전트 정의와 전용 스킬 코드까지 한 번에 프로비저닝합니다.
이 도구는 개발자 황민호(revfactory)가 공개한 오픈소스(Apache-2.0)로, 깃허브 스타 5,000개를 돌파하며 Claude Code 생태계에서 핵심 오케스트레이션 플러그인으로 주목받고 있습니다. 매번 보일러플레이트 코드를 작성하던 엔지니어들에게 팀 아키텍처 설계를 선언형으로 자동화할 수 있는 토대를 제공합니다.
1-1. 한 문장으로 시작하는 자동화 파이프라인
harness의 기본 작동 흐름은 단순한 템플릿 복제가 아닙니다. 사용자의 도메인 설명과 프로젝트 코드베이스 컨텍스트를 읽고 6단계에 걸쳐 설계를 완성합니다.
- 도메인 컨텍스트 분석: 입력된 자연어 요구사항과 레포지토리 파일 트리를 교차 분석해 작업 범위를 식별합니다.
- 아키텍처 토폴로지 매칭: 파이프라인, 팬아웃, 전문가 풀 등 사전 검증된 패턴 중 해당 프로젝트에 적합한 구조를 선택합니다.
- 전문 에이전트 스펙 정의: 각 에이전트의 책임 영역, 입출력 스키마, 허용 도구를 명세화합니다.
- 도메인 전용 스킬 빌드: 각 에이전트가 호출해야 할 커스텀 스킬 함수를 실제 실행 가능한 코드로 자동 생성합니다.
- 품질 검증 필터 적용: 그럴듯하지만 오작동 위험이 있는 결과물을 사전에 걸러내기 위해 비평 메커니즘을 내장합니다.
- 런타임 등록 및 배포: Claude Code 환경 내에 구성된 에이전트와 도구를 플러그인 형태로 즉시 바인딩합니다.
이러한 일련의 과정은 단 한 번의 실행으로 완결되며, 초기 아키텍처 수립에 들어가는 시간을 획기적으로 줄여줍니다.
2. v2 개편: 실험적 플래그 탈피와 안정성 확보
초기 v1 버전은 Claude Code의 실험적 API에 기대어 동작했습니다. 당시에는 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 선언해야만 팀 생성 기능을 활용할 수 있었고, 해당 API의 내부 명세가 릴리스마다 변경되어 상용 워크플로에 도입하기에는 위험 요소가 컸습니다.
harness v2는 이 의존성을 완전히 제거하고 현재 Claude Code 런타임에 기본 탑재된 네이티브 인터페이스만을 사용하도록 아키텍처를 전면 재작성했습니다. 이제 별도의 환경 변수 설정 없이 공식 릴리스 환경에서 안정적으로 동작합니다.
- 실험 플래그 강제
- 단일 Opus 모델 고정
- 2가지 초기 모드
- 네이티브 런타임 구동
- 모델 티어 차등 배분
- 3가지 네이티브 모드
2-1. v1 대비 핵심 개선 사항
v1에서 지적되었던 운영 오버헤드와 모델 비용 문제도 v2에서 집중적으로 개선되었습니다.
| 항목 | harness v1 | harness v2 |
|---|---|---|
| 런타임 플래그 | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 필수 |
실험용 플래그 불필요 (네이티브 지원) |
| 기본 모델 정책 | 모든 에이전트에 opus 모델 강제 할당 |
태스크 복잡도별 모델 티어 차등 배분 |
| 오케스트레이션 모드 | 폐기된 TeamCreate API 기반 2개 모드 | 정식 런타임 기반 3개 네이티브 모드 |
| 피드백 반영 | 수동 프롬프트 및 스킬 수정 | /harness:evolve 내장 명령을 통한 자동 진화 |
v1은 모든 서브에이전트의 모델을 최고 사양인 Opus로 고정하여 단순 포맷팅이나 정적 분석 작업에서도 토큰 비용이 과도하게 청구되는 한계가 있었습니다. v2는 에이전트의 역할 수준에 맞춰 모델 티어를 지능적으로 선택합니다.
3. 세 가지 네이티브 실행 모드
harness v2는 Claude Code 런타임이 제공하는 기본 역량을 다음의 세 가지 실행 모드로 분할하여 프로젝트 요구사항에 맞게 결합합니다.
3-1. 워크플로 오케스트레이션 (Workflow Orchestration)
결정론적 스크립트 실행이 필요한 영역에 사용됩니다. pipeline(), parallel()과 같은 명시적 제어 흐름을 바탕으로 엄격한 스키마 검증과 토큰 예산(budget) 관리를 수행합니다. 대규모 팬아웃 작업이나 정량적 데이터 가공, 반복 검증 루프가 필수적인 프로덕션 파이프라인에 배치됩니다.
3-2. 영속적 에이전트 협업 (Persistent Agent Collaboration)
이름이 지정된 독립 에이전트들이 SendMessage 프로토콜과 공유 작업 목록을 통해 턴(turn)을 넘나들며 컨텍스트를 유지하는 구조입니다. 단발성 질의응답이 아닌, 시스템 전반의 리팩토링이나 기능 추가와 같이 지속적인 대화와 상태 추적이 필요한 복잡한 소프트웨어 설계 작업에 적합합니다.
3-3. 서브에이전트 위임 (Sub-agent Delegation)
독립적인 컨텍스트를 유지할 필요가 없는 경량 작업에 쓰입니다. 메인 워커가 여러 하위 태스크를 일회성(one-shot)으로 병렬 디스패치한 뒤 결과만 취합하는 방식으로, 실행 지연 시간을 최소화하면서 전체 처리 속도를 끌어올립니다.
4. 품질을 담보하는 워크플로 네이티브 검증 패턴
단순히 여러 에이전트를 나열하기만 하면 환각(Hallucination)이 연쇄적으로 전파되어 '그럴듯하지만 틀린 결과물(plausible-but-wrong output)'이 양산될 위험이 있습니다. harness v2는 이를 방어하기 위해 다음과 같은 검증 패턴을 코드 레벨에서 기본 지원합니다.
- 적대적 검증 (Adversarial Verification): 작성 에이전트와 적대적 관계를 맺는 비평 에이전트를 강제 배치하여 코드 결함이나 보안 취약점을 상호 검증합니다.
- 심사위원 패널 (Judge Panels): 복수의 에이전트가 도출한 서로 다른 구현 방안을 두고 사전에 정의된 평가 기준에 따라 점수를 매겨 최선의 안을 채택합니다.
- 소진 루프 (Loop-until-dry): 테스트나 정적 분석 도구에서 지적되는 오류가 완전히 0건이 될 때까지 피드백을 반복 주입하는 안전장치입니다.
- 다각도 스윕 (Multi-modal Sweeps): 텍스트뿐만 아니라 코드 스타일, 런타임 프로파일링 데이터, 테스트 커버리지 보고서를 동시에 대조해 품질 누락을 막습니다.
- 완결성 비평 (Completeness Critics): 원래 사용자가 요청했던 요구사항 체크리스트가 전부 구현되었는지 누락 여부를 최종 검토합니다.
이러한 패턴들은 팀 생성 시 자동으로 오케스트레이션 파이프라인에 삽입되어 신뢰성 높은 결과물을 산출하도록 돕습니다.
5. 설치 방법과 실전 명령어
harness 플러그인을 로컬 개발 환경에 도입하고 에이전트를 초기화하는 과정은 직관적입니다. Claude Code 명령 인터페이스를 통해 직접 추가할 수 있습니다.
5-1. 플러그인 마켓플레이스 등록 및 설치
아래 명령어를 순서대로 실행하여 마켓플레이스 소스를 추가하고 harness 패키지를 설치합니다.
/plugin marketplace add revfactory/harness
/plugin install harness@harness-marketplace
설치가 완료되면 Claude Code 세션 내에서 harness 관련 메타 스킬과 트리거가 활성화됩니다.
5-2. 에이전트 팀 생성 및 진화
플러그인이 등록된 상태에서 프로젝트 요구사항을 자연어로 전달합니다. 한국어와 영어를 모두 기본 지원합니다.
- 팀 생성: "하네스 구성해줘" 또는 "build a harness for this project"
- 피드백 반영 및 진화:
/harness:evolve
팀을 운영하면서 에이전트가 특정 도메인 지식에서 실수를 반복하거나 워크플로 병목이 관찰되면, 피드백을 축적한 뒤 /harness:evolve 명령어를 구동합니다. 이 명령은 누적된 작업 히스토리와 피드백 로그를 분석하여 각 에이전트의 시스템 프롬프트를 보정하고 스킬 명세를 스스로 리팩토링합니다.
6. 도입 시 고려할 제약 사항과 한계
harness v2가 에이전트 팀 설계 비용을 낮춰주지만, 모든 상황에서 만능 해결책이 될 수는 없습니다.
첫째, 세밀한 비즈니스 도메인 지식의 한계입니다. harness는 프로젝트의 코드베이스 구조를 읽고 일반적인 아키텍처 패턴을 구성하지만, 사내 레거시 규정이나 특수 보안 규정과 같은 암묵적 도메인 지식까지 완전히 추론하지는 못합니다. 초기 생성된 스킬 명세를 엔지니어가 직접 리뷰하고 미세 조정하는 작업이 수반되어야 합니다.
둘째, 토큰 소비와 지연 시간의 트레이드오프입니다. 3가지 실행 모드 중 '영속적 에이전트 협업'이나 '적대적 검증 패턴'을 활성화할 경우, 여러 에이전트가 상호 메시지를 교환하면서 단일 에이전트 대비 API 호출 횟수와 토큰 사용량이 증가합니다. 작업의 복잡도에 따라 경량 서브에이전트 모드를 취할 것인지, 심층 검증 루프를 돌릴 것인지에 대한 예산 기준을 설정해야 합니다.
7. 요약 및 권장 전략
revfactory/harness는 멀티 에이전트 환경 구축의 진입 장벽을 낮춰주는 실용적인 메타 스킬입니다. v1의 실험적 요소를 걷어내고 Claude Code 네이티브 런타임에 안착하면서 엔지니어링 안정성을 확보했습니다.
- 단순 스크립트 작성 수준의 작업에는 불필요한 에이전트 분할을 피하고 워크플로 오케스트레이션 중심의 경량 구조를 취합니다.
- 복잡한 시스템 리팩토링이나 도메인 특화 기능 구현 시 "하네스 구성해줘"를 통해 토폴로지와 스킬 뼈대를 빠르게 생성합니다.
- 실제 협업 과정에서 발생하는 오류 패턴을 기록한 뒤
/harness:evolve명령으로 팀 아키텍처를 점진적으로 고도화하는 루프를 구성하는 것이 권장됩니다.
자주 묻는 질문
Q. 기존에 사용하던 실험용 플래그를 계속 켜두어야 하나요?
A. 아닙니다. harness v2는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 의존성을 완전히 제거했으므로 일반 Claude Code 실행 환경에서 플래그 없이 바로 동작합니다.
Q. 에이전트가 생성한 스킬 코드는 어디에 저장되고 수정할 수 있나요?
A. 플러그인이 프로젝트 컨텍스트 내에 스킬 정의 파일을 자동으로 생성합니다. 일반 코드 파일과 동일하므로 개발자가 직접 편집하거나 `/harness:evolve` 명령을 통해 개선할 수 있습니다.
Q. 모든 에이전트에 최고 사양 모델이 적용되어 토큰 비용이 커지지 않나요?
A. v1은 Opus 모델로 고정되었으나, v2는 작업 난이도에 따라 모델 티어를 차등 분배하는 정책을 적용하여 불필요한 토큰 낭비를 줄였습니다.



댓글 0개