revfactory-harness-blog
Harness 오픈소스: 한 문장으로 Claude Code 에이전트 팀을 찍어내는 메타 스킬
"하네스 구성해줘" 한 문장이면 프로젝트에 맞는 AI 에이전트 팀과 스킬이 디스크에 통째로 만들어집니다. 오늘 살펴볼 Harness(revfactory/harness)는 Claude Code용 "팀 아키텍처 팩토리" 오픈소스예요. 직접 일을 하는 도구가 아니라, 일할 팀을 설계하고 생성해 주는 상위 레이어라는 점이 핵심입니다.
결론부터 말씀드리면, Harness는 에이전트를 손으로 짜던 작업을 한 단계 위로 끌어올린 메타 스킬입니다. AI 에이전트·자동화에 관심 있는 1인 기업이나 개발자라면, "에이전트 팀을 어떻게 설계할 것인가"라는 요즘 가장 뜨거운 질문에 대한 한 가지 답을 여기서 볼 수 있어요.
Harness란 무엇인가요?
**Harness(revfactory/harness)**는 Claude Code를 위한 메타 스킬입니다. 도메인 설명 한 줄을 분석해 전문 에이전트 팀(
.claude/agents/)과 그들이 쓸 스킬(.claude/skills/)을 자동 생성합니다. 콘텐츠를 직접 만들지 않고, "다른 에이전트 팀"을 만들어 주는 게 특징이에요.
동작은 의외로 단순합니다. 사용자가 "하네스 구성해줘"(또는 "build a harness for this project") 한 줄을 던지면, Harness가 도메인 설명을 읽고 → 어떤 팀 아키텍처가 맞는지 판단하고 → 에이전트 정의를 만들고 → 스킬을 생성하고 → 배선과 검증까지 마칩니다. 결과로 해당 프로젝트 전용 에이전트 팀이 만들어지죠.
비유하자면, Harness는 "직원을 직접 일 시키는 매니저"가 아니라 "프로젝트에 맞는 팀 조직도와 업무 매뉴얼을 자동으로 짜주는 조직설계 컨설턴트"에 가깝습니다.
검증된 메타 정보도 탄탄합니다. 2026-06-25 GitHub 기준 ⭐ 7,717개(약 7.7천), forks 1,054개, 버전 1.2.0, 라이선스는 Apache-2.0이에요. 저장소는 2026-03-26에 생성돼 약 3개월 만에 이 규모에 도달했고, 마지막 푸시는 2026-06-10로 활발히 유지보수되고 있습니다. 작성자는 카카오 소속 한국 개발자 황민호(Minho Hwang, @revfactory) 님이고요. 참고로 GitHub 언어 통계엔 HTML이 잡히지만, 이건 데모 홈페이지 때문이고 실질 자산은 마크다운(스킬·에이전트 정의)입니다.
6가지 팀 아키텍처 패턴과 6 Phase 워크플로우
Harness는 "팀을 어떻게 짤지"를 6가지 패턴으로 구조화했습니다. 도메인에 맞춰 이 중에서 골라 조합하죠.
| 패턴 | 구조 | 적합한 작업 |
|---|---|---|
| 파이프라인 (Pipeline) | 순차 의존 — A→B→C | 단계가 앞 결과에 의존하는 작업 |
| 팬아웃/팬인 (Fan-out/Fan-in) | 병렬 분기 후 취합 | 서로 독립적인 병렬 작업 |
| 전문가 풀 (Expert Pool) | 상황별 선택 호출 | 케이스마다 다른 전문가가 필요한 작업 |
| 생성-검증 (Producer-Reviewer) | 생성 후 품질 검수 | 산출물 품질 게이트가 필요한 작업 |
| 감독자 (Supervisor) | 중앙 에이전트가 동적 분배 | 작업 분배를 런타임에 판단 |
| 계층적 위임 (Hierarchical Delegation) | 상위→하위 재귀 위임 | 큰 작업을 하위 팀으로 쪼개는 작업 |
생성 절차는 6단계 워크플로우로 돌아갑니다. ① 도메인 분석 → ② 팀 아키텍처 설계(6 패턴 중 선택) → ③ 에이전트 정의 생성 → ④ 스킬 생성 → ⑤ 통합·오케스트레이션 배선 → ⑥ 검증·테스트 순서예요.
실제 SKILL.md엔 이 앞에 **Phase 0(현황 감사)**도 들어 있습니다. 이미 하네스가 있는 프로젝트라면 설계와 실제의 어긋남(drift)을 감지하고, "신규 생성 / 확장 / 운영" 중 어느 분기로 갈지 판단하죠. 처음 만드는 것뿐 아니라 운영 중인 하네스의 확장까지 다룬다는 뜻이에요.
차별점: 진화 메커니즘 · Progressive Disclosure · A/B 검증
Harness를 다른 도구와 구분 짓는 세 가지가 있습니다.
하네스 진화 메커니즘
/harness:evolve 스킬이 핵심입니다. 하나의 하네스는 "초기 생성본 → 실제로 손봐진 상태 → 출시 상태"로 변해 가는데, evolve는 그 사이의 아키텍처 델타를 팩토리로 되먹입니다. 다음에 같은 도메인 하네스를 만들 때 빈 초안이 아니라 "이미 출시에 가까운 초안"에서 시작하게 되죠. 팩토리가 자기 산출물의 실사용 결과를 학습해 다음 산출물 품질을 끌어올리는 피드백 루프입니다.
Progressive Disclosure (단계적 정보 공개)
컨텍스트 비용을 줄이는 3단계 로딩 방식이에요. 메타데이터(name + description, 항상 로드, 약 100단어) → SKILL.md 본문(트리거될 때만, 500줄 미만) → references(정말 필요할 때만, 분량 무제한). "모든 지식을 항상 컨텍스트에 올리면 토큰이 폭증한다"는 문제를 구조적으로 푼 것으로, Claude Code 스킬 설계의 공식 권장 패턴과 같은 발상입니다.
A/B로 검증된 +60%
부속 저장소 revfactory/claude-code-harness의 통제 실험에서, 15개 소프트웨어 엔지니어링 과제로 하네스 미적용 vs 적용을 비교했습니다. 평균 품질 점수가 49.5 → 79.3, 즉 **+60%(상대 증가율)**이고 승률은 15/15(100%)였어요. 다만 이 수치는 작성자 자체 통제 실험 기준이고 외부 독립 재현은 확인되지 않았습니다. "검증된 사실"이라기보다 "작성자가 실험으로 제시한 근거"로 받아들이는 게 정확해요.
규모를 보여주는 자산도 있습니다. revfactory/harness-100 저장소엔 10개 도메인 100개 에이전트 팀 하네스(한·영 200패키지)가 들어 있고, 총 마크다운 파일이 1,808개예요. "한 문장으로 팀을 찍어낸다"는 주장의 실물 카탈로그인 셈이죠.
생태계에서 Harness의 자리
README는 "경쟁이 아니라 공존"이라는 프레임으로 생태계 지도를 그립니다. Harness의 위치는 L3 Meta-Factory, 즉 다른 하네스를 생성하는 가장 상위 추상화 층이에요.
| 프로젝트 | 레이어 | 역할 |
|---|---|---|
| revfactory/harness | L3 Meta-Factory | 팀 아키텍처 팩토리 (본체) |
| coleam00/Archon | L3 | 런타임 결정성 설정 팩토리 |
| SaehwanPark/meta-harness | L3 | 같은 컨셉의 Codex 런타임 포트 |
| affaan-m/ECC | L2 | 여러 하네스 위 표준화 층 |
| wshobson/agents | 부품 | 서브에이전트·스킬 카탈로그 (182 agents, 149 skills) |
| LangGraph | 런타임 | 상태 그래프 오케스트레이션 |
요점은 Harness가 "에이전트 카탈로그"(wshobson/agents 같은 부품 모음)나 "오케스트레이션 런타임"(LangGraph)과 다른 층에 있다는 거예요. 그것들을 조합해 쓰도록 팀을 설계하는 메타 레이어죠.
참고로 Harness가 생성하는 산출물이 올라타는 기반인 Claude Code의 Agent Teams 기능은 Anthropic 공식 문서에 명시된 실제 기능입니다. 한 세션이 팀 리더가 되어 작업을 분배·취합하고, 팀원은 각자의 컨텍스트 윈도우에서 독립 작동하며 서로 직접 통신해요. 다만 Agent Teams는 아직 experimental(기본 비활성)이고, 과거 setup/cleanup용으로 쓰이던 도구들은 현재 제거돼 별도 setup 단계 없이 동작합니다.
QJC 관점: 우리가 손으로 짓는 걸 공장으로 찍어낸다
저희 QJC는 작은 기업이지만 큰 기업의 AI 전환(AX)을 Claude Code·Codex·Hermes로 돕습니다. 그 과정에서 견적·콘텐츠·회의록·세무 같은 도메인별 에이전트와 라우팅 룰, 스킬을 손으로 만들어 운영해 왔어요. Harness를 보면 저희가 매번 손으로 하던 "팀 설계" 단계를 한 문장으로 자동화하려는 메타 레이어라는 게 보입니다. 우리가 그리던 조직도를 찍어내는 공장에 해당하죠.
흥미로운 건 구조적 공명입니다. 저희 콘텐츠 자동화 시스템이 이미 쓰는 패턴들이 Harness의 6 패턴과 상당 부분 겹쳐요. 감독자 역할의 director, 생성-검증 페어 구조, 페어 병렬 dispatch(팬아웃/팬인), Phase 게이트(파이프라인)는 Harness 6 패턴 중 4종에 직접 대응합니다. 다시 말해 저희는 이미 "Harness가 자동 생성하려는 결과물"을 수작업으로 운영 중이고, Harness는 그 생성 자동화의 가치를 보여주는 셈이에요.
다만 객관적으로 경계할 점도 분명합니다. 앞서 말한 +60%는 작성자 자체 실험이고, Agent Teams 자체가 아직 experimental이라 "한 문장으로 완성 팀이 뚝딱"이라는 기대는 현실과 거리가 있어요. 실제로는 생성 후 사람의 검토·수정이 필요할 가능성이 높습니다. "초안 자동 생성 가속기"로 보는 게 현실적이에요. 라이선스가 Apache-2.0(permissive)이라 상업적 차용·수정 부담이 낮다는 점은 사내 도구로 검토할 때 장점이고요.
마무리
Harness는 "에이전트를 만드는 일" 자체를 자동화한 메타 스킬입니다. 6가지 팀 아키텍처 패턴, 6 Phase 워크플로우, 진화 메커니즘, 그리고 1,808개 마크다운으로 이뤄진 100개 하네스 카탈로그까지 — "한 문장으로 팀을 찍어낸다"는 주장을 구체적인 구조와 실물로 뒷받침하고 있어요.
AI 에이전트 팀 설계를 고민하고 계신다면, Harness가 어떻게 문제를 푸는지 한 번 들여다볼 가치가 충분합니다. 직접 도입까지는 검토가 필요하더라도, "에이전트 코디네이션을 어떻게 구조화할 것인가"에 대한 좋은 레퍼런스가 되어 줄 거예요.
자주 묻는 질문 (FAQ)
Q: 하네스(harness)가 뭔가요?
여기서 하네스는 Claude Code 프로젝트에 설치하는 에이전트 팀과 스킬의 묶음을 뜻합니다. Harness 오픈소스는 그 하네스를 "한 문장으로 자동 생성"해 주는 메타 스킬이에요. 즉 도메인 설명만 주면 전문 에이전트 팀과 그들이 쓸 스킬을 디스크에 만들어 줍니다.
Q: 어떻게 설치하나요?
플러그인 마켓플레이스를 쓰는 방법이 권장됩니다. /plugin marketplace add revfactory/harness 후 /plugin install harness@harness-marketplace를 실행하면 돼요. 또는 cp -r skills/harness ~/.claude/skills/harness로 스킬을 직접 복사할 수도 있습니다. 설치 후엔 "하네스 구성해줘" 한 줄로 사용해요.
Q: 기존 에이전트 카탈로그(wshobson/agents 등)와 뭐가 다른가요?
에이전트 카탈로그는 미리 만들어진 에이전트·스킬을 모아 둔 "부품 공급원"입니다. Harness는 그 부품들을 조합해 프로젝트에 맞는 팀을 설계하고 생성하는 한 층 위의 메타 팩토리(L3)예요. 카탈로그가 재료라면 Harness는 그 재료로 조직을 짜는 설계 도구라고 보시면 됩니다.
Q: A/B 실험의 +60%는 믿을 수 있나요?
부속 저장소의 15개 과제 통제 실험에서 평균 품질이 49.5 → 79.3(+60%)으로 나온 건 사실이지만, 이건 작성자 자체 실험 결과입니다. 외부 독립 재현은 아직 확인되지 않았어요. 효과의 방향성을 참고하되, "검증 완료된 절대 수치"로 받아들이기보다 도입 시 직접 검증해 보시길 권합니다.
