Harness 소개
Harness는 사용자로부터 도메인 프롬프트 한 문장을 받아 에이전트 팀의 구조와 그 팀이 사용할 스킬을 한꺼번에 생성해 주는 Claude Code용 메타 스킬입니다. 사용자가 "build a harness for this project" 또는 한국어로 "하네스 구성해줘" 라고 말하면, 사전 정의된 6가지 팀 아키텍처 패턴 중 도메인에 맞는 것을 골라 .claude/agents/ 안의 에이전트 정의 파일과 .claude/skills/ 안의 스킬 파일을 생성하는 방식으로 동작합니다.
Harness는 자신을 Claude Code 생태계의 L3 메타 팩토리(Meta-Factory) 계층, 그중에서도 팀 아키텍처 팩토리(Team-Architecture Factory) 라는 하위 계층에 위치시키고 있습니다. 같은 L3 계층의 이웃 프로젝트인 Archon이 결정론적 런타임 구성 자체를 만들어 내는 데 초점을 둔다면, Harness는 그 위에서 누가 어떤 역할로 협업할지의 팀 구조 와 그 팀이 사용할 스킬을 생성한다는 점에서 다른 위치를 차지합니다.
Harness의 6가지 팀 아키텍처 패턴
Harness는 도메인을 분석한 뒤 다음 6가지 패턴 중 하나(또는 여러 개의 조합)를 팀 청사진으로 선택합니다.
| 패턴 | 설명 |
|---|---|
| Pipeline | 순차 의존성이 있는 작업을 단계별로 흘려보냅니다. |
| Fan-out / Fan-in | 병렬로 처리할 수 있는 독립 작업을 분기 후 취합합니다. |
| Expert Pool | 맥락에 따라 필요한 전문가 에이전트만 선택적으로 호출합니다. |
| Producer-Reviewer | 생성 에이전트와 검수 에이전트를 짝으로 둬서 품질을 확보합니다. |
| Supervisor | 중앙 슈퍼바이저가 동적으로 작업을 분배합니다. |
| Hierarchical Delegation | 상위 에이전트가 하위 에이전트에게 재귀적으로 위임합니다. |
이 패턴들은 단순한 분류표가 아니라 Harness가 자동으로 인스턴스를 만들어 내는 단위입니다. README의 "Use Cases — Try These Prompts" 섹션은 딥 리서치, 풀스택 웹 개발, 웹툰 에피소드 제작, 유튜브 콘텐츠 기획, 코드 리뷰, API 문서 생성, 데이터 파이프라인 설계, 마케팅 캠페인 같은 도메인을 예시로 들면서 각각이 위 패턴들로 어떻게 표현되는지를 보여 줍니다.
Harness의 6단계 워크플로우
Harness는 도메인 한 문장에서 실제 팀이 만들어지기까지를 다음 6단계로 정의합니다.
Phase 1: Domain Analysis
↓
Phase 2: Team Architecture Design (Agent Teams vs Subagents)
↓
Phase 3: Agent Definition Generation (.claude/agents/)
↓
Phase 4: Skill Generation (.claude/skills/)
↓
Phase 5: Integration & Orchestration
↓
Phase 6: Validation & Testing
Phase 1은 사용자 발화에서 도메인의 본질을 추출하는 단계이고, Phase 2는 다중 에이전트 협업이 필요한지(Agent Teams 모드) 아니면 단발성 작업으로 충분한지(Subagents 모드)를 결정합니다. Phase 3과 4에서 실제 마크다운 정의 파일이 프로젝트의 .claude/ 디렉터리에 생성되며, Phase 5는 에이전트 간 데이터 전달과 오류 처리, 팀 협업 프로토콜을 연결하는 단계입니다. Phase 6은 트리거 검증, 드라이런 테스트, with-skill 대 without-skill 비교 테스트로 결과물을 검증합니다.
Harness의 실행 모드
Harness는 사용 시점에 두 가지 실행 모드 중 하나를 선택합니다.
| 모드 | 설명 | 권장 상황 |
|---|---|---|
| Agent Teams (기본값) | TeamCreate + SendMessage + TaskCreate 조합으로 다중 에이전트를 조율합니다. | 협업이 필요한 2개 이상의 에이전트 |
| Subagents | Agent 도구를 직접 호출하는 단발성 모드입니다. | 일회성 작업, 에이전트 간 통신이 필요 없는 경우 |
Agent Teams 모드를 사용하려면 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 을 설정해 Claude Code의 실험적 에이전트 팀 기능을 활성화해야 합니다.
Harness가 만들어 내는 산출물
Harness 실행이 끝나면 프로젝트에는 다음 구조로 파일이 생성됩니다.
your-project/
├── .claude/
│ ├── agents/ # 에이전트 정의 파일
│ │ ├── analyst.md
│ │ ├── builder.md
│ │ └── qa.md
│ └── skills/ # 스킬 파일
│ ├── analyze/
│ │ └── SKILL.md
│ └── build/
│ ├── SKILL.md
│ └── references/
스킬은 Progressive Disclosure 원칙에 따라 자동 생성된다고 README는 설명하며, 이는 모든 컨텍스트를 한 번에 노출하지 않고 필요한 시점에 단계적으로 펼치는 구성을 의미합니다.
Harness의 자체 A/B 측정 결과
Harness는 부속 저장소 revfactory/claude-code-harness 에서 15개의 소프트웨어 엔지니어링 과제로 with harness 와 without harness 를 비교한 통제 실험 결과를 함께 공개하고 있습니다. README의 수치를 그대로 옮기면 다음과 같습니다.
| 지표 | Harness 미사용 | Harness 사용 | 변화 |
|---|---|---|---|
| 평균 품질 점수 | 49.5 | 79.3 | +60% |
| 승률 | — | — | 100% (15 / 15) |
| 출력 분산 | — | — | −32% |
저자는 이 수치가 n = 15 의 저자 측정 A/B 결과이며 제3자 재현은 아직 진행되지 않았다 는 단서를 README의 FAQ Q1에 명시하고 있습니다. 또한 과제 난이도가 높을수록 효과가 커진다고 보고합니다(Basic +23.8, Advanced +29.6, Expert +36.2). 도입 결정에 쓰기 전에 2~4주 정도의 내부 파일럿으로 직접 측정해 볼 것을 권장한다는 안내도 함께 적혀 있습니다.
Harness와 이웃 프로젝트
Harness는 README에서 자신을 팀 아키텍처 팩토리 로 한정하고, 같은 L3 메타 계층의 이웃 프로젝트와의 관계를 다음과 같이 정리합니다.
- coleam00/Archon: 결정론적 런타임 구성 팩토리. Harness와 같은 L3 계층의 이웃 하위 계층이라고 자기 자리를 잡고 있습니다.
- SaehwanPark/meta-harness: 같은 개념의 Codex 런타임 포트입니다.
- affaan-m/ECC: 여러 하네스 위에 표준화 계층을 얹는 교차 하네스 워크플로우 계층입니다.
- wshobson/agents: 서브 에이전트와 스킬 카탈로그(182개 에이전트, 149개 스킬). Harness가 만드는 팀의 부품 공급 으로 통합할 수 있습니다.
Harness 설치
Claude Code의 플러그인 마켓플레이스를 통해 설치하는 방법이 가장 단순합니다.
# 마켓플레이스 등록
/plugin marketplace add revfactory/harness
# 플러그인 설치
/plugin install harness@harness
전역 스킬로 직접 설치하려면 저장소의 skills/harness 디렉터리를 사용자의 ~/.claude/skills/harness 에 복사합니다.
cp -r skills/harness ~/.claude/skills/harness
설치 후 Claude Code 안에서 "Build a harness for this project" 또는 "하네스 구성해줘" 같은 문장으로 호출하면 됩니다.
Harness 라이선스
Harness는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있는 permissive 라이선스입니다.
Harness 공식 홈페이지
Harness 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 