Harness: 하네스를 프로젝트에 맞게 만들어주는 스킬

AI 코딩 에이전트가 좋아졌다고 해서, 바로 팀으로 일도 잘하는 것은 아닙니다.

오히려 실무에서는 더 어려운 문제가 남습니다.
“어떤 역할로 에이전트를 나눌지”, “어떤 순서로 협업시킬지”, “각 에이전트에게 어떤 스킬을 줘야 할지”, “정말 이 구성이 성능을 높였는지 어떻게 검증할지” 같은 문제입니다. Harness는 바로 이 지점에 들어옵니다. 이 프로젝트는 새로운 에이전트 런타임을 만드는 도구가 아니라, 도메인별 에이전트 팀과 스킬을 설계·생성하는 메타 스킬로 설계되어 있습니다. Claude Code 안에서 “이 프로젝트용 하네스를 만들어줘”라고 말하면, .claude/agents/와 .claude/skills/ 구조를 자동으로 만들어 주는 식입니다. (GitHub)

 

GitHub - revfactory/harness: A meta-skill that designs domain-specific agent teams, defines specialized agents, and generates th

 

프로젝트 소개

Harness는 revfactory가 공개한 Claude Code 플러그인입니다. 플러그인 메타데이터에는 저자가 robin, 저장소 소유자가 revfactory, 라이선스는 Apache-2.0, 플러그인 버전은 1.0.1로 기록되어 있습니다. 설치도 Claude Code 플러그인 방식과 글로벌 스킬 복사 방식 둘 다 지원합니다. (GitHub)

이 프로젝트를 한 문장으로 요약하면 이렇습니다.

에이전트를 잘 쓰는 법이 아니라,
에이전트 팀을 잘 설계하고 그 팀이 쓸 스킬을 체계적으로 생성하는 법을 문서화한 자동화 도구.

저장소 구조를 보면 이 성격이 더 분명해집니다. 런타임 코드가 가득한 프레임워크라기보다, .claude-plugin/plugin.json, skills/harness/SKILL.md, 그리고 여러 레퍼런스 문서로 구성된 설계 지향형 플러그인입니다. 핵심 로직은 코드보다 Markdown 기반 스킬 정의에 실려 있고, 실제 산출물은 사용자 프로젝트 내부의 .claude/agents/와 .claude/skills/에 생성됩니다. (GitHub)

Harness가 전제하는 개발 환경도 명확합니다. 이 프로젝트는 Claude Code의 Agent Teams 기능을 적극적으로 활용하며, README에는 Agent Teams 사용을 위해 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정이 필요하다고 적혀 있습니다. 즉, 범용 멀티에이전트 프레임워크라기보다 Claude Code 생태계에 특화된 팀 설계 플러그인입니다. (GitHub)

왜 이 프로젝트가 등장했을까

에이전트를 한두 번 써보면 금방 드러나는 한계가 있습니다.

처음에는 “코드 짜줘”, “문서 써줘” 같은 단일 요청이 잘 먹힙니다. 그런데 작업이 복잡해지면 문제가 달라집니다. 예를 들어 풀스택 개발, 대규모 코드 리뷰, 심층 리서치, 데이터 파이프라인 설계 같은 작업은 한 번의 프롬프트로 끝나지 않습니다. 분석, 설계, 구현, 검증, QA가 서로 다른 관점으로 얽혀 있고, 종종 병렬화와 교차 검토가 필요합니다. Harness는 이런 복잡한 작업을 위해 README에서 6단계 워크플로우를 제시합니다. 도메인 분석, 팀 아키텍처 설계, 에이전트 정의 생성, 스킬 생성, 오케스트레이션 통합, 검증 및 테스트까지 한 번에 다룹니다. (GitHub)

이 프로젝트가 흥미로운 이유는 “에이전트를 많이 붙이면 좋아진다” 같은 단순한 멀티에이전트 낙관론을 따르지 않기 때문입니다. 오히려 문서 전반에서 언제 팀을 쓰고, 언제 서브에이전트로 충분한지, 스킬 설명문을 어떻게 써야 실제로 잘 트리거되는지, 생성한 스킬이 baseline보다 낫다는 걸 어떻게 비교할지 같은 운영상의 문제를 구체적으로 다룹니다. 즉, Harness는 멀티에이전트 자체보다 에이전트 구성의 공학화에 가깝습니다. (GitHub)

핵심 기능

1) 에이전트 팀 아키텍처를 설계한다

Harness는 에이전트 조합을 임의로 만들지 않습니다. README와 레퍼런스 문서에서 6가지 아키텍처 패턴을 제시합니다.

• Pipeline
• Fan-out/Fan-in
• Expert Pool
• Producer-Reviewer
• Supervisor
• Hierarchical Delegation (GitHub)

이게 중요한 이유는, 대부분의 팀형 에이전트 실험이 “일단 역할 몇 개 나누고 돌려보자” 수준에서 끝나기 때문입니다. Harness는 작업 성격에 맞춰 패턴을 먼저 고르도록 만듭니다. 예를 들어 순차 의존성이 강하면 Pipeline, 병렬 조사 후 통합이면 Fan-out/Fan-in, 생성 후 리뷰 체계가 중요하면 Producer-Reviewer를 고릅니다. 이것은 단순한 프롬프트 템플릿이 아니라, 협업 구조를 먼저 설계한 뒤 프롬프트를 그 구조에 맞춰 파생시키는 접근입니다. (GitHub)

2) Agent Teams를 기본값으로 둔다

Harness의 가장 선명한 철학은 이것입니다.
기본은 서브에이전트가 아니라 Agent Teams다.

레퍼런스 문서에 따르면 Agent Teams 모드에서는 리더가 TeamCreate로 팀을 만들고, 팀원은 독립 인스턴스로 실행되며, SendMessage로 직접 통신하고, TaskCreate/TaskUpdate 기반의 공유 작업 목록으로 자체 조율합니다. 반면 서브에이전트는 메인 에이전트가 Agent(...) 도구로 호출하고, 결과를 메인에게만 반환합니다. 그래서 팀 간 협업, 반박, 발견 공유가 중요하면 Agent Teams를 우선하고, 단순 위임이면 서브에이전트를 선택하도록 가이드합니다. (GitHub)

이 설계는 실무적으로 꽤 현실적입니다.
복잡한 작업에서는 “잘하는 에이전트 한 명”보다 “서로 다른 관점이 충돌하며 보완하는 구조”가 더 중요할 때가 많기 때문입니다.

3) 에이전트 정의와 스킬을 함께 생성한다

Harness는 팀 설계에서 끝나지 않습니다. 실제 결과물로 .claude/agents/와 .claude/skills/를 생성합니다. README의 출력 예시에도 analyst, builder, qa 같은 에이전트 정의와 analyze/build 스킬 구조가 포함되어 있습니다. SKILL 문서 역시 핵심 원칙으로 에이전트 정의와 스킬을 함께 생성한다고 못 박고 있습니다. (GitHub)

이 조합이 중요한 이유는, 역할만 나눠 놓고 각 역할의 작업 방법론이 비어 있으면 결국 매번 프롬프트를 다시 길게 써야 하기 때문입니다. Harness는 “역할”과 “실행 습관”을 같이 고정합니다.

4) 스킬 설명문을 트리거 엔진처럼 다룬다

SKILL 문서에서 특히 인상적인 부분은 description을 바라보는 태도입니다. Harness는 description이 사실상 스킬의 유일한 트리거 메커니즘이며, Claude가 트리거를 보수적으로 판단하므로 description을 적극적으로, 거의 “pushy”하게 써야 한다고 설명합니다. PDF 예시에서는 “PDF 문서를 처리하는 스킬” 같은 모호한 문구보다, 어떤 작업을 언제 반드시 이 스킬로 처리해야 하는지까지 넣으라고 권장합니다. (GitHub)

이건 실무적인 통찰입니다.
많은 팀이 스킬 품질을 본문 지침에서만 찾는데, 실제 사용성은 언제 스킬이 자동으로 호출되느냐에 크게 좌우됩니다. Harness는 이 부분을 구조적으로 다룹니다.

5) Progressive Disclosure로 컨텍스트 비용을 줄인다

Harness는 스킬을 한 파일에 다 몰아넣기보다, 필요한 상세 지식을 조건부로 분리하는 방식을 장려합니다. skill-writing-guide.md에는 Progressive Disclosure 패턴이 등장하고, 예시로 도메인별 reference 파일을 나누거나, 메인 skill에서 세부 레퍼런스를 링크하는 구조를 보여줍니다. (GitHub)

이 패턴의 장점은 분명합니다.

• 기본 스킬은 짧고 명확하게 유지할 수 있다.
• 필요할 때만 상세 문서를 불러와 컨텍스트를 쓴다.
• 스킬이 비대해져 자동 트리거 성능이 떨어지는 것을 막는다.

즉, Harness는 단순 생성기가 아니라 LLM 컨텍스트 예산까지 고려한 스킬 설계 도구입니다. (GitHub)

6) 결과를 검증하는 테스트 방법론까지 포함한다

이 프로젝트가 진짜로 공들인 부분은 검증입니다. skill-testing-guide.md에서는 테스트 프롬프트를 다양하게 만들고, 같은 프롬프트를 with-skill과 baseline으로 병렬 실행해서 비교하는 구조를 제안합니다. 새 스킬을 만들 때 baseline은 “스킬 없이 같은 프롬프트를 실행한 결과”, 기존 스킬을 개선할 때는 “수정 전 스킬 버전”입니다. (GitHub)

이건 굉장히 좋은 습관입니다.
많은 AI 자동화 프로젝트가 “잘 되는 것 같다” 수준에서 끝나는데, Harness는 최소한 비교군을 두고 개선을 확인하라고 요구합니다. 즉, 스킬을 감으로 다듬는 대신 평가 가능한 산출물로 다루게 합니다. (GitHub)

프로젝트 아키텍처 분석

Harness의 아키텍처를 코드 실행 관점이 아니라 생성 파이프라인 관점으로 보면 더 이해가 쉽습니다.

이 구조의 핵심은 Harness가 직접 비즈니스 작업을 수행하는 것이 아니라, 다른 에이전트들이 잘 수행하도록 사전 구성을 생성한다는 점입니다. README의 설명과 SKILL 문서의 워크플로우는 모두 이 방향으로 정렬되어 있습니다. (GitHub)

좀 더 내부적으로 쪼개 보면 이런 식입니다.

이 설계에서 눈여겨볼 부분은 세 가지입니다.

첫째, 패턴 선택이 생성보다 앞선다는 점입니다.
보통은 역할을 먼저 적고 협업은 나중에 생각하는데, Harness는 협업 구조를 먼저 결정합니다. (GitHub)

둘째, 오케스트레이터를 별도 설계 대상으로 본다는 점입니다.
오케스트레이터 템플릿 문서에는 TeamCreate, TaskCreate, 절대 경로 사용, Phase 간 의존성, 에러 핸들링, 테스트 시나리오 같은 원칙이 명시돼 있습니다. 즉, 오케스트레이터는 단순 glue code가 아니라 팀 운영 규칙의 중심입니다. (GitHub)

셋째, QA를 사후 단계가 아니라 구조적 역할로 포함한다는 점입니다.
QA 가이드에서는 통합 정합성 검증을 강조하며, “양쪽 코드를 동시에 열어” 경계면을 확인하라고 안내합니다. 또 QA를 전체 완성 후 한 번만 돌리는 대신, 모듈 완성 직후부터 개입시키라고 설명합니다. (GitHub)

이 프로젝트가 잘한 점

1. “멀티에이전트”를 프롬프트 감성에서 아키텍처 문제로 끌어올렸다

Harness는 에이전트 팀을 신기한 데모로 다루지 않습니다.
Pipeline, Fan-out/Fan-in, Supervisor 같은 패턴으로 구조화합니다. 이 접근은 팀 설계를 재사용 가능한 자산으로 바꾸는 데 유리합니다. (GitHub)

2. 생성보다 운영을 더 진지하게 다룬다

description 트리거, Progressive Disclosure, 에러 핸들링, 테스트 비교, QA 체크리스트 같은 내용은 “예쁘게 만들어주는 생성기”보다 훨씬 실전적입니다. 이 프로젝트는 생성 이후에 실제로 굴러가는지를 더 중요하게 보는 편입니다. (GitHub)

3. 실사용 예시가 꽤 넓다

README에는 딥 리서치, 풀스택 웹 개발, 웹툰 제작, 유튜브 콘텐츠 기획, 코드 리뷰, API 문서화, 데이터 파이프라인 설계, 마케팅 캠페인까지 예시 프롬프트가 제시됩니다. 즉, 특정 소프트웨어 개발 워크플로우에만 묶인 도구는 아닙니다. (GitHub)

아쉬운 점도 있다

Harness는 매우 흥미롭지만, 동시에 전제가 강한 도구입니다.

첫째, Claude Code의 Agent Teams 기능에 깊게 의존합니다. 그래서 범용 오픈소스 오케스트레이터처럼 다른 런타임에 그대로 이식되는 구조는 아닙니다. (GitHub)

둘째, 저장소의 본질이 코드 프레임워크보다 문서형 메타 스킬이기 때문에, 일반적인 라이브러리처럼 API를 import해서 쓰는 경험을 기대하면 다소 낯설 수 있습니다. 이 프로젝트의 핵심 자산은 실행 코드가 아니라 설계 지침과 생성 규칙입니다. (GitHub)

셋째, README에 소개된 Harness 100이나 효과성 연구는 저장소 안에서 언급되지만, 블로그 글을 쓰는 시점에서 저는 이 저장소 자체를 중심으로 분석했고, 외부 리포지토리와 논문 내용을 추가 검증하지는 않았습니다. 그래서 그 수치 자체보다는 이 저장소가 어떤 문제의식을 갖고 설계됐는가에 초점을 맞춰 보는 편이 더 안전합니다. (GitHub)

개발자 관점에서 언제 쓰면 좋을까

Harness는 이런 상황에서 특히 잘 맞습니다.

복잡한 작업을 반복적으로 수행할 때

예를 들어 팀에서 자주 하는 일이 이런 식이라면 좋습니다.

• 아키텍처 리뷰 + 보안 리뷰 + 성능 리뷰를 병렬로 돌리고 싶다
• 신규 서비스 개발에서 설계, 구현, QA 역할을 분리하고 싶다
• 특정 도메인 리서치를 여러 관점으로 조사한 뒤 종합하고 싶다
• 코드 생성보다, 생성 체계 자체를 표준화하고 싶다

즉, 일회성 프롬프트보다 반복 가능한 협업 구조가 필요한 팀에 더 잘 맞습니다. README의 사용 예시와 팀 예제 문서도 이 방향을 뒷받침합니다. (GitHub)

반대로 이런 경우에는 과할 수 있다

작은 스크립트 한 개 수정, 파일 하나 요약, 단일 리팩터링처럼 작업 범위가 작고 에이전트 간 협업이 필요 없는 경우에는 서브에이전트나 단일 에이전트가 더 간단할 수 있습니다. Harness의 문서도 1개 에이전트이거나 통신이 불필요하면 서브에이전트를 선택하라고 안내합니다. (GitHub)

실제로 어떤 식으로 쓰일까

아래는 Harness가 만들어낼 법한 구조를 이해하기 위한 예시입니다.

1) 에이전트 정의 예시

---
name: architecture-reviewer
description: 시스템 아키텍처, 모듈 경계, 의존성 구조를 검토하는 전문가
---

# Architecture Reviewer

## 역할
- 서비스 경계와 책임 분리를 검토한다
- 병목, 결합도, 변경 비용이 큰 지점을 찾는다
- 결과는 개선 제안 중심으로 정리한다

2) 스킬 예시

---
name: review-architecture
description: 아키텍처 리뷰, 계층 구조 점검, 모듈 의존성 분석, 서비스 경계 검토 요청이 있으면 반드시 사용
---

# 아키텍처 리뷰 스킬

## 목표
코드베이스의 구조적 문제를 찾고 개선안을 제시한다.

## 출력 형식
# Architecture Review
## Summary
## Findings
## Recommendations

## 체크 포인트
- 순환 의존성
- 과도한 공유 모듈
- 인프라 코드와 도메인 코드의 결합

3) 오케스트레이터 개념 예시

# review-orchestrator

1. architecture-reviewer, security-reviewer, performance-reviewer 팀을 생성한다.
2. 각 리뷰어에게 독립 분석 작업을 할당한다.
3. 공통 이슈는 팀 메시지로 교차 검증한다.
4. 최종적으로 findings를 통합해 단일 보고서를 생성한다.

이 예시는 저장소의 정확한 샘플 파일 복제가 아니라, README와 레퍼런스 문서가 설명하는 생성 방향을 개발자 눈높이에서 재구성한 것입니다. 실제 Harness는 이 과정을 .claude/agents/, .claude/skills/, 오케스트레이터 문서 형태로 자동화하려는 프로젝트입니다. (GitHub)

한 줄 평

Harness는 “에이전트를 더 똑똑하게 만드는 도구”라기보다,
에이전트 협업을 설계 가능한 시스템으로 만드는 도구에 가깝습니다.

요즘 AI 도구들은 대개 실행 능력 자체를 강조합니다. 하지만 실무에서 더 부족한 것은 종종 실행 능력이 아니라 구조입니다. 누가 무엇을 맡고, 언제 협업하고, 어떤 스킬이 언제 발동하고, 결과를 무엇과 비교해 검증할지. Harness는 바로 이 구조를 문서와 규칙, 생성물로 고정하려고 합니다. (GitHub)

그래서 이 프로젝트는 이런 개발자에게 특히 흥미롭습니다.

• AI 에이전트를 “한 번 잘 쓰는 것”보다 “계속 비슷한 품질로 쓰는 것”이 중요한 팀
• 멀티에이전트 협업을 장난감이 아니라 운영 체계로 보고 싶은 팀
• Claude Code 안에서 도메인 특화 에이전트 팀을 표준화하고 싶은 팀

한마디로, Harness는 에이전트 시대의 팀 템플릿 엔진입니다.