요즘 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주 내부 파일럿으로 직접 수치를 재보라"고 권합니다. 마케팅 숫자를 스스로 검증 가능한 형태로 공개하는 정직함이 오히려 신뢰를 줍니다.
GitHub의 언어 통계는 "HTML 100%"라고 뜨지만(랜딩 페이지 index.html 때문), Harness의 실체는 마크다운 파일 묶음입니다. 코드를 실행하는 게 아니라, Claude(LLM)가 읽고 따라 하는 지시서의 집합이죠. 따라서 "기술 스택"을 이해하려면 Harness가 올라탄 Claude Code 플랫폼을 봐야 합니다.
| 구성요소 | 역할 |
|---|---|
| Claude Code | 실행 런타임. 이 플러그인이 동작하는 유일한 공식 환경 |
| Agent Teams (실험적) | 여러 Claude 인스턴스를 팀으로 묶는 기능. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 켬 |
| Skills 시스템 | YAML frontmatter + 마크다운으로 절차적 지식을 정의하는 표준 |
| Plugin / Marketplace | /plugin marketplace add로 설치하는 배포 체계 |
| 모델 | 모든 에이전트는 model: "opus" 고정 — 추론 품질이 결과 품질에 직결되므로 |
| 도구 | 하는 일 |
|---|---|
| TeamCreate | 팀을 만들고 팀원(에이전트)들을 스폰 |
| SendMessage | 팀원 간 직접 메시지. {to:"all"}은 브로드캐스트(비쌈) |
| TaskCreate / TaskUpdate | 공유 작업 목록 — 의존성 관리 + 팀원이 스스로 작업 요청(claim) |
| Agent | 서브 에이전트 직접 호출(경량 모드). subagent_type로 타입 지정 |
| Read / Write | _workspace/에 중간 산출물을 파일로 주고받음 |
| 산출물 | 형식 / 위치 |
|---|---|
| 에이전트 정의 | .claude/agents/{name}.md — YAML frontmatter(name, description) + 6개 필수 섹션 |
| 스킬 | .claude/skills/{name}/SKILL.md + 선택적 references/·scripts/·assets/ |
| 오케스트레이터 | 팀 전체를 조율하는 상위 스킬 1개(데이터 흐름·에러 핸들링·테스트 시나리오 포함) |
| 커맨드 | 생성하지 않음 — 산출물 체크리스트에 ".claude/commands/ 아무것도 안 만듦"이 명시 |
--- 두 줄 사이에 넣는 메타데이터 블록. 에이전트·스킬 파일에서는 여기에 name(이름)과 description(설명/트리거 조건)을 적습니다. Claude는 이 description만 보고 "지금 이 스킬을 써야 하나?"를 판단하므로, frontmatter는 트리거의 핵심입니다.references/는 정말 필요할 때만 읽습니다. "두꺼운 매뉴얼을 통째로 외우지 말고, 목차만 기억했다가 필요한 챕터만 펴 보라"는 원리입니다.Harness는 "하네스 구성해줘"를 받으면 아래 6단계 컨베이어를 한 칸씩 통과시킵니다. 도메인 한 문장이 들어가서 완성된 에이전트 팀이 나옵니다.
SendMessage로 서로 직접 대화하고 공유 작업목록으로 자체 조율합니다 — 발견을 공유하고 서로 도전하며 품질이 올라가지만 토큰 비용이 큽니다. 서브 에이전트(경량)는 메인이 Agent 도구로 일꾼을 부르고 결과만 받는 방식 — 가볍고 빠르지만 일꾼끼리는 대화 못 합니다.Harness의 첫 갈림길은 "팀이냐 서브에이전트냐"입니다. 기본은 팀이고, 통신이 정말 불필요할 때만 서브에이전트를 씁니다.
Harness의 심장은 references/agent-design-patterns.md에 정의된 6개 패턴입니다. 도메인의 작업 성격에 맞는 조직도를 여기서 고릅니다.
| 패턴 | 구조 한줄 | 대표 예시 |
|---|---|---|
| ① 파이프라인 | 분석→설계→구현→검증 (순차 의존) | 소설: 세계관→캐릭터→플롯→집필 |
| ② 팬아웃/팬인 | 병렬로 흩뿌렸다가 결과 통합 | 종합 리서치: 4개 관점 동시 조사→통합 |
| ③ 전문가 풀 | 라우터가 상황별 전문가만 호출 | 코드 리뷰: 보안/성능/구조 중 해당만 |
| ④ 생성-검증 | 생성가↔검증가 쌍, 문제시 재생성 | 웹툰: artist 생성→reviewer 검수 |
| ⑤ 감독자 | 중앙이 상태 보고 동적으로 분배 | 대규모 코드 마이그레이션 배치 할당 |
| ⑥ 계층적 위임 | 상위→하위로 재귀 위임(2단계 권장) | 풀스택 앱: 총괄→프론트/백엔드 팀장 |
가장 "에이전트 팀다운" 패턴은 ②팬아웃/팬인입니다 — 팀원들이 서로 발견을 공유하고, 한 명의 발견이 다른 사람의 조사 방향을 실시간으로 바꿉니다. 아래는 리서치 팀의 통신 패턴입니다.
Harness 전체를 관통하는 일관된 약속이 몇 가지 있습니다. 첫째, "누가(에이전트)"와 "어떻게(스킬)"를 철저히 분리합니다. 에이전트는 페르소나·원칙을, 스킬은 절차적 지식을 담죠. 둘째, 에이전트는 반드시 파일로 정의합니다 — Agent 도구 프롬프트에 역할을 직접 박는 것은 금지인데, 파일로 있어야 다음 세션에서 재사용되고 팀 통신 프로토콜이 명시되기 때문입니다. 셋째, 스킬 설명은 적극적(pushy)으로 씁니다("PDF 작업이면 반드시 이 스킬 사용"처럼). 넷째, 본문에 "ALWAYS/NEVER" 대신 '왜 그런지' 이유를 설명합니다 — LLM은 이유를 알면 엣지 케이스에서도 옳게 판단하니까요.
| 전략 | 방식 | 적합한 경우 |
|---|---|---|
| 메시지 기반 | SendMessage 직접 통신 | 실시간 조율, 피드백 교환 |
| 태스크 기반 | TaskCreate/Update 작업 상태 공유 | 진행 추적, 의존 관리, 작업 자체 요청 |
| 파일 기반 | _workspace/에 쓰고 읽기 | 대용량·구조화 산출물, 감사 추적 |
권장 조합은 태스크(조율) + 파일(산출물) + 메시지(실시간 소통)입니다. 파일명은 {phase}_{agent}_{artifact}.{ext}(예: 01_analyst_requirements.md) 컨벤션을 따르고, 중간 파일은 _workspace/에 보존해 사후 검증·감사에 씁니다.
| 위치 | 역할 |
|---|---|
| skills/harness/SKILL.md | 이 프로젝트의 두뇌. 6단계 절차의 본문(500줄 이내) |
| references/agent-design-patterns.md | 6패턴·실행모드·에이전트 정의 구조·분리기준의 원전 |
| references/team-examples.md | 리서치·소설·웹툰·코드리뷰·마이그레이션 5개 팀의 실제 파일 예시 |
| .claude/agents/*.md (생성물) | 각 파일이 한 명의 전문가 = "누가" |
| .claude/skills/*/SKILL.md (생성물) | 각 폴더가 하나의 절차 매뉴얼 = "어떻게" |
Harness의 가장 큰 교훈은 역할(누가)과 절차(어떻게)를 다른 파일로 분리한다는 것입니다. 같은 "리서처" 페르소나가 여러 스킬을 쓸 수도, 여러 에이전트가 한 스킬을 공유할 수도 있죠(1:N, N:1). 이렇게 분리하면 재사용성이 폭발적으로 올라갑니다. 객체지향의 "관심사 분리(SoC)"를 에이전트 설계에 적용한 실전 예시입니다.
📖 한 줄 풀이: references/agent-design-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 (현재 유일한 공식 환경). Codex는 자매 포팅 meta-harness 사용 |
| 필수 플래그 | 에이전트 팀 모드: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정 필요 |
| 모델 | 모든 에이전트 model: "opus" 권장 — 추론 품질이 결과 품질에 직결 |
| 설치 | /plugin marketplace add revfactory/harness → /plugin install harness@harness-marketplace, 또는 skills/harness를 ~/.claude/skills/에 복사 |
| 토큰 비용 | 에이전트 팀은 팀원마다 별도 인스턴스라 비용이 큼. 팀원 수를 적정하게(아래) 유지 |
| 로컬 자원 | 무거운 컴파일·GPU 불필요 — 마크다운 기반 플러그인이라 디스크·메모리 부담 거의 없음 |
Harness의 "요구사항"은 공장 설비가 아니라 인건비(토큰)에 가깝습니다. 팀원이 많을수록 결과가 좋아지는 게 아니라, 오히려 조율 오버헤드와 비용만 커집니다. README는 "3명의 집중된 팀이 5명의 산만한 팀보다 낫다"고 못박습니다. 소규모(5~10작업)는 2~3명, 중규모(10~20작업)는 3~5명, 대규모(20+작업)도 5~7명을 넘기지 말라는 가이드라인이 그래서 중요합니다.
세션당 한 팀만 활성화 가능하고(Phase 사이에 해체→재구성은 가능), 중첩 팀 불가(팀원이 자기 팀을 못 만듦), 리더 고정(이전 불가)입니다. 그래서 계층적 위임(⑥)을 3단계 이상 깊게 짜려 하면 막힙니다 — 1단계는 팀, 2단계는 서브에이전트로 구현하거나 평탄화하라고 권합니다. "팀이 만능"이 아님을 아는 게 설계의 시작입니다.
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주 | 멀티에이전트 협업 패턴 | Agent Teams(TeamCreate/SendMessage/TaskCreate), 6패턴, 팀 vs 서브에이전트 |
| 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 도구로 부르는 경량 일꾼. 결과만 반환, 서로 통신 불가 |
| TeamCreate / SendMessage / TaskCreate | 각각 팀 생성·팀원간 메시지·공유 작업목록 관리 도구 |
| 6패턴 | 파이프라인·팬아웃/팬인·전문가풀·생성-검증·감독자·계층적위임 |
| 오케스트레이터 | "누가 언제 어떤 순서로 협업하나"를 정의해 팀 전체를 지휘하는 상위 스킬 |
| Progressive Disclosure | 이름→본문→references 3단계 로딩으로 컨텍스트(토큰)를 아끼는 기법 |
| pushy description | 스킬이 확실히 트리거되도록 상황까지 구체적으로 적은 적극적 설명문 |
| _workspace/ | 팀원들이 중간 산출물을 파일로 주고받는 작업 공간(감사 추적용 보존) |
| L3 메타팩토리 | '다른 하네스를 만들어내는' 최상위 층. Archon(런타임설정)과 옆 칸 관계 |