플러그인
2026-10-31 개정: SHA 92d9f1b의 v2.1.0을 기준으로 실행 모드·아키텍처·요구사항을 수정했습니다. 초판의 팀 실습은 v1 예시이므로 현재 실행에는 docs/migration-v1-to-v2.md의 변환을 먼저 적용합니다. 재검토 근거는 README.md·skills/harness/SKILL.md·plugin manifest·이전 가이드입니다.
요즘 Claude Code 같은 AI 코딩 도구는 한 명이 아니라 여러 명의 AI가 팀을 이뤄 일을 나눠 하는 방향으로 진화하고 있습니다. 그런데 "팀을 어떻게 짤지"는 사람이 직접 설계해야 합니다 — 누구를 몇 명 둘지, 누가 먼저 일하고 누가 검수할지, 결과를 어떻게 주고받을지. Harness는 바로 그 '팀 설계' 자체를 자동화합니다. 도메인 한 문장을 주면 적절한 팀 구조를 골라 에이전트 정의 파일과 스킬 파일을 만들어내죠.
당신이 "유튜브 콘텐츠 제작 팀이 필요해요"라고 말하면, 이 컨설턴트는 먼저 일의 성격을 분석합니다. 그리고 "리서처 1명 + 대본 작가 1명 + SEO 담당 1명, 그리고 이들을 지휘하는 총괄(감독자) 1명"이라는 조직도를 그립니다. 각 직원에게는 "당신의 역할은 이것, 일하는 원칙은 저것, 결과는 여기에 저장"이라고 적힌 업무 분장표(에이전트 정의)를 나눠주고, 자주 하는 작업은 표준 매뉴얼(스킬)로 만들어 비치합니다. 마지막으로 "누가 누구에게 보고하고, 산출물은 어디서 합치는지"까지 정해줍니다. Harness가 만드는 건 결과물이 아니라 결과물을 만들 '팀 그 자체'입니다.
핵심은 "누가(에이전트)"와 "어떻게(스킬)"를 분리한다는 점입니다. 에이전트는 전문가의 페르소나와 행동 원칙을 담은 .claude/agents/{이름}.md 파일이고, 스킬은 절차적 지식을 담은 .claude/skills/{이름}/SKILL.md 파일입니다. 이 둘을 조합해 하나의 협업 워크플로우(오케스트레이터)로 엮는 것이 Harness가 하는 일의 전부라고 해도 됩니다.
Harness가 2026년에 트렌딩에 오른 데에는 몇 가지 뚜렷한 이유가 있습니다. 첫째, Claude Code가 에이전트 팀(Agent Teams)이라는 멀티에이전트 협업 기능을 실험적으로 열면서, "여러 AI를 어떻게 팀으로 묶을까"가 갑자기 모두의 숙제가 됐습니다. Harness는 그 숙제에 6개의 정형화된 정답지를 제시합니다. 둘째, "스킬을 만드는 스킬"이라는 메타 레이어(L3) 자체가 새로운 흐름입니다 — Karpathy의 autoresearch처럼 'AI가 AI의 작업환경을 만든다'는 재귀적 자동화의 한 갈래죠.
셋째, 작가가 한국 개발자(revfactory, 황민호)라는 점과 README가 영어·한국어·일본어 3개 국어로 제공된다는 점이 국내 커뮤니티의 관심을 끌었습니다. 넷째, 단순 도구를 넘어 harness-100(10개 도메인 100개의 기성품 하네스, 한·영 합쳐 200패키지, 1,808개 마크다운 파일)이라는 생태계까지 펼쳐 보였습니다.
비슷한 도구들과 비교하면 Harness의 위치가 또렷해집니다. 같은 'L3 메타팩토리' 안에서도 세부 층이 다릅니다.
| 도구 | 무엇을 만드나 | Harness와의 관계 |
|---|---|---|
| Harness | 에이전트 팀 구조 + 스킬 (6패턴) | 본인 — 팀 아키텍처 팩토리 |
| Archon | 결정적·재현가능한 런타임 설정 | 같은 L3, 옆 칸. 조합 가능(설계는 Harness→배포는 Archon) |
| meta-harness | 같은 개념의 Codex 포팅 | 같은 L3, 다른 런타임(Codex용) |
| wshobson/agents | 에이전트·스킬 카탈로그(182개+149개) | 부품 공급처. Harness가 설계한 팀에 부품으로 흡수 |
| LangGraph | 상태 그래프 오케스트레이션(LLM 무관) | 다른 트랙. 장기 실행·상태 복구용 |
| 수동 설계 | 사람이 직접 에이전트·스킬 작성 | Harness가 자동화하려는 대상 |
README는 자매 저장소(claude-code-harness)에서 잰 A/B 실험으로 "평균 품질 49.5→79.3, +60%, 15전 15승, 분산 -32%"를 내세웁니다. 인상적이지만 표본이 15개 작업(n=15)뿐이고, 저자 본인이 측정했으며 제3자 재현은 아직 없습니다. 이 숫자만 보고 "무조건 60% 좋아진다"고 결론 내리면 안 됩니다.
드물게도 이 프로젝트는 모든 인용에 "n=15, 저자 측정, 제3자 재현 대기 중"이라는 단서를 같은 문장 안에 강제로 병기하라고 명시합니다. 심지어 FAQ 첫 항목이 "+60%는 과장 아닌가?"이고, 도입 결정 전 "2~4주 내부 파일럿으로 직접 수치를 재보라"고 권합니다. 마케팅 숫자를 스스로 검증 가능한 형태로 공개하는 정직함이 오히려 신뢰를 줍니다.
현재 정본은 2.1.0의 문서·스킬 기반 Claude Code 플러그인이다. 별도 앱 서버를 실행하는 패키지가 아니라 팀 정의·스킬·오케스트레이터를 생성하는 절차를 제공한다. 이번 조사에서는 그 절차를 실행하지 않았다.
| 층 | 역할 |
|---|---|
| Plugin manifest | .claude-plugin/plugin.json의 이름·버전·배포 정보 |
| 메인 스킬 | skills/harness/SKILL.md의 점검·설계·검증 단계 |
| 참고 자료 | execution-modes·team-patterns·model-selection 등 조건부 문서 |
| 진화 스킬 | skills/evolve의 사용 피드백 반영 절차 |
실행 모드는 Workflow 조율, 이름 있는 지속형 에이전트 협업, 일회성 서브에이전트 위임의 세 가지다. 저장소 v2는 TeamCreate·TeamDelete와 실험 플래그 의존을 제거했다고 설명한다. 모델도 전부 opus로 고정하지 않고 업무별 선택 이유를 기록한다. 이는 해당 프로젝트의 계약이며 다른 하니스의 지원 범위로 일반화하지 않는다.
실행 모드를 팀 크기 대신 제어 흐름으로 고른다. 열거 가능한 분산 작업·검증 반복은 Workflow, 맥락을 유지하며 협상할 전문가는 지속형 Agent와 SendMessage·공유 작업, 결과를 한 번 받으면 되는 작업은 일회성 위임에 대응한다. 단계마다 다른 모드를 섞을 수 있다.
// 저장소의 선택 원리를 줄인 의사코드
if (enumerableWork && explicitChecks) choose("workflow")
else if (needsSharedContext) choose("persistent agents")
else choose("one-shot delegation")팀 패턴은 파이프라인·팬아웃/팬인·전문가 풀·생성/검증·감독자·계층형 위임이다. 품질 패턴은 적대적 확인, 심사위원단, 새 항목이 없을 때까지 반복, 여러 기준 탐색, 누락 검토자를 더한다. 결과 스키마·토큰 예산·재개 조건은 execution-modes 참고 자료와 함께 읽는다.
v1 이전은 옛 팀 도구·broadcast·실험 플래그를 제거하고 정해진 fan-out을 Workflow로, 지속 협업을 이름 있는 Agent·SendMessage로 바꾸는 절차다. 모델 일괄 고정도 업무별 선택으로 재검토한다. 여기서 실제 모델 호출이나 이전 작업을 수행하지는 않았다.
생성 대상은 사용자 프로젝트의 .claude/agents, .claude/skills와 CLAUDE.md의 최소 호출 포인터다. 원본 스킬과 생성된 프로젝트 구성을 구분한다. 현재 tree는 문서·프롬프트·manifest 중심이며, 별도 애플리케이션 핵심 소스가 없는 형태를 그대로 분석했다.
Harness의 가장 큰 교훈은 역할(누가)과 절차(어떻게)를 다른 파일로 분리한다는 것입니다. 같은 "리서처" 페르소나가 여러 스킬을 쓸 수도, 여러 에이전트가 한 스킬을 공유할 수도 있죠(1:N, N:1). 이렇게 분리하면 재사용성이 폭발적으로 올라갑니다. 객체지향의 "관심사 분리(SoC)"를 에이전트 설계에 적용한 실전 예시입니다.
📖 한 줄 풀이: references/team-patterns.md의 "스킬 vs 에이전트 구분" 표 한 장이 이 철학을 압축합니다.
소프트웨어 디자인 패턴(싱글톤·옵저버…)처럼, Harness는 멀티에이전트 협업의 패턴 언어를 6개로 정리했습니다. 파이프라인·팬아웃/팬인·전문가풀·생성-검증·감독자·계층적위임. 한 번 익히면 어떤 도메인을 만나도 "이건 생성-검증이네", "여긴 감독자가 맞겠다"처럼 빠르게 골격을 잡을 수 있습니다. 백지에서 고민하는 시간을 없애주는 게 패턴의 가치입니다.
LLM의 작업 기억(컨텍스트)은 공공재이자 비용입니다. Harness는 3단계 로딩으로 이를 관리합니다 — 항상 떠 있는 건 이름+설명(~100단어)뿐, 본문은 트리거될 때, 상세 reference는 정말 필요할 때만. SKILL.md가 500줄에 근접하면 세부를 references/로 쪼개고 "언제 이걸 읽으라"는 포인터만 남깁니다. 큰 시스템 프롬프트를 다루는 모든 사람에게 필요한 감각입니다.
스킬의 description은 유일한 트리거 메커니즘입니다. Claude는 트리거를 보수적으로 판단하므로, "PDF를 처리하는 스킬"(나쁨) 대신 "PDF 읽기·추출·병합·분할·OCR 등 모든 PDF 작업 수행. .pdf를 언급하면 반드시 사용"(좋음)처럼 구체적 상황까지 적어야 합니다. 검증 단계에서는 should-trigger / should-NOT-trigger 쿼리를 8~10개씩 만들어, 특히 키워드는 비슷하나 트리거되면 안 되는 'near-miss'를 잡아냅니다.
"이 스킬이 정말 도움이 되나?"를 감이 아니라 데이터로 확인하는 법. Harness는 같은 프롬프트를 스킬 있는 에이전트와 없는 에이전트(baseline)에 병렬로 던져 산출물을 비교합니다. 객관적으로 검증 가능하면(파일 생성·데이터 추출) assertion으로, 주관적이면(문체·디자인) 사용자 리뷰로 평가하죠. 이 방법론 자체가 자매 저장소의 "+60%" 실험으로 이어집니다. AI 도구의 효과를 측정하는 실전 틀을 배울 수 있습니다.
에이전트 팀 모드에서 각 에이전트 정의에는 '팀 통신 프로토콜' 섹션이 들어갑니다 — "누구로부터 무엇을 받고, 누구에게 무엇을 보내며, 공유 작업목록에서 어떤 작업을 요청하는가". team-examples.md의 worldbuilder.md 전문을 보면, 세계관 담당이 캐릭터 담당에게 사회구조를, 플롯 담당에게 갈등구조를 SendMessage로 넘기는 실제 협업 배선이 보입니다. 분산 시스템의 메시지 패싱을 에이전트에 적용한 셈입니다.
플러그인의 공식 대상은 Claude Code다. 저장소 자체에 별도 GPU·RAM·서버 최소 사양은 제시되지 않는다. 호스트가 제공하는 Workflow·Agent·통신·작업 기능과 선택 모델의 권한·비용 조건을 확인해야 한다. v2 설치에는 실험적 Agent Teams 플래그가 필요하지 않다고 README가 명시한다.
기존 v1 산출물은 단순 재사용 전에 이전 가이드와 대조한다. 모델 수나 동시 작업 수만 늘리면 품질이 올라간다고 가정하지 말고, 작은 예제로 스키마·중단·재개·완료 조건을 확인한다. 초판 A/B 수치는 제작자가 수행한 v1 실험이며 현재 버전의 보편적 성능 보장이 아니다.
Claude Code에서 아래로 설치한 뒤, README의 예시 프롬프트 하나를 그대로 붙여넣어 보세요. 그러면 .claude/agents/와 .claude/skills/에 파일들이 생성됩니다.
# 💡 하는 일: 마켓플레이스 등록 → 플러그인 설치 /plugin marketplace add revfactory/harness /plugin install harness@harness-marketplace # 그 다음 채팅창에 한 문장: Build a harness for deep research. # (또는 한국어로) 딥리서치용 하네스 구성해줘
안심하세요 — 생성된 파일을 지워도 원본 프로젝트는 안전합니다. 먼저 무엇이 만들어지는지 구경하는 게 목적입니다.
실습 A에서 만들어진 .claude/agents/의 파일 하나를 열어, 6개 필수 섹션(핵심 역할 / 작업 원칙 / 입출력 프로토콜 / 팀 통신 프로토콜 / 에러 핸들링 / 협업)이 어떻게 채워졌는지 확인하세요. references/team-examples.md의 worldbuilder.md 전문과 나란히 비교하면, "좋은 에이전트 정의"의 형태가 손에 잡힙니다.
당신이 자동화하고 싶은 일(예: "블로그 글 자동 작성")을 골라, 6패턴 중 무엇이 맞는지 종이에 그려보세요. 생성-검증? 파이프라인? 그리고 팀원을 3명 이내로 정해 각자의 역할·입출력·통신 경로를 손으로 설계해보세요. 그런 다음 Harness에게 같은 요청을 주고 당신의 설계와 Harness의 설계를 비교하면, 어디서 생각이 갈렸는지가 가장 좋은 학습 포인트가 됩니다.
생성된 스킬 하나를 골라, 그 description이 트리거되어야 할 쿼리 8개(공식적/캐주얼/암시적 섞어서)와 트리거되면 안 될 'near-miss' 쿼리 8개(키워드는 비슷하나 다른 도구가 맞는 경우)를 작성해보세요. 그리고 실제로 Claude에 던져 의도대로 트리거되는지 확인합니다. "이 엑셀의 차트를 PNG로 추출"처럼 경계가 모호한 쿼리가 좋은 테스트 케이스입니다.
현실적인 테스트 프롬프트 하나로 서브에이전트를 두 개 띄우세요 — 하나는 생성된 스킬을 읽고 작업, 하나는 같은 프롬프트를 스킬 없이(baseline) 작업. 두 산출물을 assertion(객관)과 리뷰(주관)로 비교해, 스킬의 부가가치를 당신의 도메인에서 직접 수치화해보세요. README가 권하는 "2~4주 내부 파일럿"의 축소판입니다. "+60%"가 내 경우에도 성립하는지 스스로 검증하는 경험이 핵심입니다.
| 주차 | 주제 | 학습 자료 / 키워드 |
|---|---|---|
| 1주 | Claude Code 스킬·플러그인 기본기 | SKILL.md 구조, YAML frontmatter, Plugin/Marketplace, anthropics/skills 공식 예시 |
| 2주 | 멀티에이전트 협업 패턴 | Workflow·지속형 Agent·일회성 위임, 6패턴과 제어 흐름 선택 |
| 3주 | 스킬 작성과 트리거·평가 | Progressive Disclosure, pushy description, should/should-NOT 트리거, With/Without A/B |
| 4주 | 오케스트레이션 & 생태계 | 오케스트레이터·데이터전달·에러핸들링·QA 에이전트, harness-100 실사례, Archon 조합 |
이 4주는 "AI에게 일을 시키는 사람"에서 "AI 팀을 설계하는 사람"으로 넘어가는 다리입니다. 멀티에이전트는 2026년 AI 도구의 최전선이고, Harness는 그 설계 노하우(패턴·통신·평가·컨텍스트 관리)가 한 저장소에 정리돼 있어 큰 그림을 한 번에 볼 수 있는 흔치 않은 교재입니다. harness-100을 함께 보면 100개의 실제 적용 사례까지 덤으로 얻습니다.
| 용어 | 의미 |
|---|---|
| 하네스 (Harness) | 한 도메인 자동화를 위한 "에이전트 + 스킬 + 협업 규칙"의 미리 구성된 한 세트 |
| 메타 스킬 | 스킬을 만들어내는 스킬. Harness는 자신을 'L3 메타팩토리'로 규정 |
| 에이전트 (Agent) | "누가" — 전문가 페르소나 + 행동 원칙. .claude/agents/{name}.md 파일 |
| 스킬 (Skill) | "어떻게" — 절차적 지식 + 도구 번들. .claude/skills/{name}/SKILL.md |
| 에이전트 팀 | 독립 인스턴스 팀원들이 SendMessage·공유 작업목록으로 자체 조율(기본 모드) |
| 서브 에이전트 | 메인이 Agent 도구로 부르는 경량 일꾼. 결과만 반환, 서로 통신 불가 |
| Agent / SendMessage / TaskCreate | 각각 에이전트 실행·직접 메시지·공유 작업목록 관리 도구 |
| 6패턴 | 파이프라인·팬아웃/팬인·전문가풀·생성-검증·감독자·계층적위임 |
| 오케스트레이터 | "누가 언제 어떤 순서로 협업하나"를 정의해 팀 전체를 지휘하는 상위 스킬 |
| Progressive Disclosure | 이름→본문→references 3단계 로딩으로 컨텍스트(토큰)를 아끼는 기법 |
| pushy description | 스킬이 확실히 트리거되도록 상황까지 구체적으로 적은 적극적 설명문 |
| _workspace/ | 팀원들이 중간 산출물을 파일로 주고받는 작업 공간(감사 추적용 보존) |
| L3 메타팩토리 | '다른 하네스를 만들어내는' 최상위 층. Archon(런타임설정)과 옆 칸 관계 |