6가지 아키텍처 패턴 + 60% 품질 향상: 이 오픈소스 프로젝트가 하네스 엔지니어링을 개념에서 도구로 바꾸다

지난주 우리는 Anthropic과 OpenAI의 하네스 엔지니어링에 대한 다양한 해석과, 강력 지지부터 회의론까지 아우르는 9명의 블로거들의 다양한 입장을 정리했습니다. 개념적 논의는 활발했지만, 핵심 질문은 여전히 남아 있었습니다: 구체적으로 어떻게 구현할 것인가? 이제 누군가가 답을 제시했습니다.

개발자 revfactory가 Harness라는 Claude Code 플러그인을 만들었습니다. 이는 하네스 엔지니어링의 개념을 설치하고 실행할 수 있는 도구로 직접 전환합니다. 사용자가 수행하려는 작업을 알려주면, Agent 정의 파일, Skill 파일, 협업 프로토콜, 테스트 케이스를 포함한 완전한 Agent 팀 아키텍처를 자동으로 생성하여 .claude/agents/ 및 .claude/skills/ 디렉토리에 배치합니다.

이 프로젝트가 무엇을 하는지 자세히 살펴보겠습니다.

Harness는 6가지 내장 Agent 팀 협업 패턴을 제공하며, 각각은 일반적인 작업 유형에 해당합니다.

파이프라인(Pipeline) 은 강한 의존성을 가진 순차적 작업에 적합합니다. 한 Agent의 출력이 다음 Agent로 직접 전달됩니다. 예를 들어, 소설 쓰기: 세계관 구축이 먼저 이루어져야 캐릭터 디자인이 가능하고, 캐릭터 설정이 완료되어야 줄거리를 구성할 수 있습니다. 병목 현상이 명확하며, 어떤 링크라도 막히면 전체 라인이 중단됩니다.

팬아웃/팬인(Fan-out/Fan-in) 은 가장 자연스러운 다중 Agent 패턴입니다. 여러 전문가가 동일한 입력을 병렬로 분석하고, 결과는 마지막에 집계됩니다. 산업 조사에 특히 유용합니다: 한 Agent는 공식 문서를 확인하고, 다른 Agent는 미디어 보도를 확인하며, 또 다른 Agent는 커뮤니티 토론을 확인하고, 다른 Agent는 경쟁사 배경을 확인한 후 최종적으로 종합 보고서를 작성합니다.

전문가 풀(Expert Pool) 은 라우터를 통해 입력 유형에 따라 동적으로 작업을 해당 전문가에게 할당합니다. 코드 리뷰가 일반적인 시나리오입니다: 보안 문제는 보안 전문가에게, 성능 문제는 성능 전문가에게 할당됩니다. 모든 전문가가 동시에 온라인 상태일 필요는 없습니다.

생산자-검토자(Producer-Reviewer) 는 Anthropic의 글에서 발견된 핵심 결과를 직접 반영합니다. Agent가 자신의 작업을 평가하는 것은 거의 무용지물이며, 반드시 독립적인 생성자와 검토자로 분할되어야 합니다. Harness는 이 패턴을 제품화했으며, 무한 루프를 방지하기 위해 최대 2-3회의 재시도 제한이 내장되어 있습니다.

감독자(Supervisor) 는 동적 할당 측면에서 팬아웃과 다릅니다. 팬아웃은 작업을 사전에 할당하는 반면, 감독자는 런타임에 실제 상황에 따라 동적으로 스케줄링합니다. 대규모 코드 마이그레이션이 이 패턴에 적합합니다: 감독자가 파일 목록을 분석하고 복잡성에 따라 파일을 동적으로 여러 마이그레이션 Agent에 배치합니다.

계층적 위임(Hierarchical Delegation) 은 특히 복잡한 문제를 처리하며, 큰 작업을 재귀적으로 더 작은 작업으로 분해하여 하위로 위임합니다. 2단계로 제한되며, 그 이상은 지연 시간과 컨텍스트 손실로 이어집니다.

이 6가지 패턴은 임의로 선택되지 않았습니다. 두 번째 단계(팀 아키텍처 설계)에서 Harness는 전문화 수준, 병렬화 가능성, 컨텍스트 범위, 재사용성의 4가지 차원을 기준으로 자동 평가합니다.

패턴 정의만으로는 충분하지 않습니다. Harness에는 5개의 완전한 팀 구성 템플릿이 포함되어 있습니다.

연구 팀(Research Team) 은 팬아웃/팬인 패턴을 사용하며, 4명의 전문화된 연구원과 1명의 코디네이터로 구성됩니다. 공식 문서 연구원, 미디어 연구원, 커뮤니티 연구원, 배경 연구원이 병렬로 작업하며, 모순된 정보를 발견하면 SendMessage를 사용하여 상호 검증합니다.

SF 소설 팀(Sci-Fi Novel Team) 은 파이프라인과 팬아웃을 혼합하여 사용하며, 4단계에 걸쳐 6명의 Agent로 구성됩니다. 1단계: 세계관 디자이너, 캐릭터 디자이너, 줄거리 설계자가 병렬로 작업하고 서로 통신합니다. 2단계: 작가가 텍스트를 초안합니다. 3단계: 과학 컨설턴트와 연속성 검토자가 병렬로 검토합니다. 4단계: 작가가 최종 원고를 수정합니다. 가장 흥미로운 점은 각 단계의 팀이 사용 후 해체되고, 다음 단계를 위해 새로운 팀이 생성된다는 것입니다.

웹툰 제작 팀(Webtoon Production Team) 은 생산자-검토자 패턴을 사용하며, 단 2명의 Agent로 구성됩니다: 아티스트가 스토리보드를 생성하고, 검토자는 PASS, FIX, REDO 중 하나의 결과를 제공합니다. 최대 2회 재시도가 적용되며, 그 후에는 강제로 통과시켜 완벽주의적 무한 루프를 방지합니다.

코드 리뷰 팀(Code Review Team) 은 팬아웃/팬인과 동료 토론 메커니즘을 사용합니다. 보안 검토자, 성능 검토자, 테스트 검토자가 병렬로 작업합니다. 핵심은 검토자가 SendMessage를 사용하여 직접 상호 검증할 수 있다는 점입니다. 예를 들어, 보안 검토자가 SQL 인젝션 위험을 발견하면 성능 검토자에게 직접 알려 관련 쿼리를 확인하도록 합니다.

코드 마이그레이션 팀(Code Migration Team) 은 감독자 패턴을 사용하며, 1명의 감독자가 N명의 마이그레이션 실행자를 동적으로 스케줄링합니다. 감독자는 복잡성에 따라 파일을 배치로 할당하고, 실행자는 작업을 요청하고 진행 상황을 보고하며, 실패한 작업은 자동으로 재할당됩니다.

이 프로젝트에서 가장 설득력 있는 부분은 포함된 A/B 테스트 데이터 세트입니다.

15개의 소프트웨어 엔지니어링 작업이 Harness를 사용한 방법과 사용하지 않은 방법 두 가지로 완료되었습니다. 결과: 평균 품질 점수가 49.5에서 79.3으로 60% 향상되었습니다. Harness는 15개 작업 모두에서 승리하여 100% 승률을 기록했습니다. 출력 분산은 32% 감소하여 결과가 더 안정적이고 예측 가능함을 의미합니다.

더 흥미로운 점은 작업 복잡성별 분석입니다: 기본 작업은 23.8%, 중간 작업은 29.6%, 전문가 수준 작업은 36.2% 향상되었습니다. 작업이 복잡할수록 Harness의 가치가 더 커집니다. 이는 Anthropic 실험의 결론과 매우 일치합니다: 단일 Agent는 간단한 작업을 처리할 수 있지만, 복잡한 작업은 하네스 없이는 거의 불가능합니다.

Harness는 Skill 생성을 위해 점진적 공개(Progressive Disclosure)라는 설계를 사용하여 매우 실용적인 문제를 해결합니다: 너무 길게 작성된 Skill 파일은 엄청난 양의 컨텍스트 윈도우를 소비합니다.

접근 방식은 3계층입니다: 메타데이터 계층은 항상 로드되고(이름, 설명, 트리거 단어), 기본 skill.md 본문은 500줄 미만으로 유지되며, 상세 참조 자료는 references/ 디렉토리에 배치되어 필요 시 로드됩니다. 이렇게 하면 Agent는 일반적으로 매우 적은 토큰을 소비하며, 특정 도메인을 깊이 파고들어야 할 때만 해당 참조 문서를 로드합니다.

이 아이디어는 Claude Code Skill을 작성하는 모든 사람에게 가치가 있습니다. 우리의 자체 게시 Skill은 이미 600줄을 초과했습니다. 아마도 문제 해결 및 템플릿 세부 정보를 references로 이동하는 것을 고려해야 할 것입니다.

앞서 개괄한 전체 그림을 되돌아보면, 이 프로젝트는 하네스 엔지니어링을 개념적 논의에서 도구 단계로 발전시킵니다.

첫 번째 전환: "하네스를 설계해야 합니다"에서 "하네스를 자동으로 생성하도록 돕습니다"로.

Anthropic과 OpenAI의 글은 본질적으로 "하네스는 중요하니 잘 설계하세요"라고 말합니다. 하지만 어떻게 설계할까요? 어떤 패턴을 써야 할까요? 에이전트는 어떻게 소통해야 할까요? 이러한 질문들은 독자가 스스로 해결해야 할 과제로 남겨졌습니다. Harness 프로젝트는 선택과 생성을 모두 자동화합니다. 요구사항을 설명하면 완전한 아키텍처를 출력합니다.

두 번째 전환: 단일 패턴에서 패턴 라이브러리로.

이전 논의에서 Anthropic은 Producer-Reviewer(생성자 + 평가자)에, OpenAI는 Pipeline(계층형 아키텍처)에 집중했습니다. 하지만 실제 시나리오는 이 두 가지보다 훨씬 다양합니다. 여섯 가지 패턴을 체계적으로 다룸으로써 단순한 작업부터 복잡한 작업까지 대부분의 협업 요구를 해결합니다.

세 번째 전환: "제 생각엔 괜찮습니다"에서 "데이터가 말하게 하자"로.

회의론자 Chayenne Zhao의 말이 맞았습니다. 개념적 글만으로는 하네스 엔지니어링이 실제로 유용한지 판단하기 어렵습니다. 이 프로젝트는 15개 작업에 대한 A/B 테스트를 통해 정량적 증거를 제공합니다. 60%의 품질 향상과 100%의 승률은 개념이 아니라 숫자입니다.

간과하기 쉬운 몇 가지 설계 선택 사항:

모든 에이전트 호출은 model: "opus"를 강제로 지정합니다. 에이전트 팀 시나리오에서 추론 품질은 협업 품질을 직접 결정합니다. 더 약한 모델을 사용하면 토큰은 절약되지만 협업이 쉽게 무너집니다.

파일 시스템을 협업 인프라로 사용. 에이전트 간 중간 산출물은 _workspace/ 디렉토리에 통일되어 저장되며, 명명 규칙은 {단계}_{에이전트}_{산출물}.{확장자}입니다. 이는 커뮤니티 토론에서 Leo가 언급한 내용과 완전히 일치합니다. 파일 시스템은 가장 기본적인 프리미티브입니다. 파일만이 지속성, 세션 간 협업, 다중 에이전트 공유 상태를 동시에 해결할 수 있기 때문입니다.

검증 프레임워크는 형식에 불과하지 않습니다. 각 Skill은 이를 트리거해야 하는 8-10개의 쿼리와 트리거하지 말아야 하는 8-10개의 쿼리를 작성해야 하며, 특히 근접 오탐지 테스트 케이스에 중점을 둡니다. 이러한 수준의 엄격함은 대부분의 에이전트 도구에서 드뭅니다.

팀 규모에 대한 엄격한 제한. 2명에서 7명까지, 각 구성원은 3~6개의 작업을 담당합니다. 계층적 위임은 최대 2단계로 제한됩니다. 이러한 제약은 실제 경험에서 얻은 교훈에서 비롯됩니다. 에이전트가 너무 많으면 조정 비용이 기하급수적으로 증가하고, 계층이 너무 많으면 컨텍스트 손실이 심각해집니다.

몇 가지 한계점도 분명히 해야 합니다.

Agent Teams 기능은 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 수동으로 활성화해야 합니다. 이는 이 기능이 아직 Claude Code 내에서 실험적 단계임을 나타냅니다. 안정성과 성능은 더 많은 실제 사용을 통해 검증되어야 합니다.

A/B 테스트의 15개 작업은 모두 소프트웨어 엔지니어링 시나리오입니다. 다른 영역(글쓰기, 연구, 디자인)에서의 효과는 데이터로 뒷받침되지 않습니다.

여섯 가지 패턴 간 선택에 대한 조언은 여전히 상대적으로 거친 수준입니다. 실제로는 혼합 사용이 필요할 가능성이 높습니다. SF 소설 예제는 이미 Pipeline과 Fan-out을 모두 사용하고 있지만, 이러한 하이브리드 패턴에 대한 모범 사례는 아직 탐색 중입니다.

그러나 하네스 엔지니어링을 개념에서 설치 가능한 도구로 전환한 첫 번째 프로젝트로서 방향은 옳습니다. 적어도 "하네스 엔지니어링이 유용한가?"에 대한 논쟁을 멈추고 "더 잘 사용하는 방법"에 대한 연구를 시작할 수 있습니다.

via revfactory/harness GitHub / Anthropic Engineering Blog / OpenAI Blog