Harness: Claude Code 에이전트 팀을 설계하는 방법
date
Apr 13, 2026
slug
harness-claude-code-agent-team
author
status
Public
tags
Blog
Github
Study
summary
인턴을 하면서 Claude Code용 메타 스킬 플러그인 Harness를 공부하며, 복잡한 작업을 에이전트 팀과 스킬로 분해하는 방식과 설치/사용법, 도입 시 주의점을 정리합니다.
type
Post
thumbnail
category
📗 Docs
updatedAt
May 5, 2026 04:40 PM
인턴을 하면서 Claude Code의 에이전트 팀과 스킬 구조를 찾아보다가
Harness라는 플러그인을 공부해보았습니다. 처음에는 단순히 여러 에이전트를 만들어주는 도구라고 생각했는데, 실제로는 도메인에 맞는 에이전트 팀 구조와 스킬, 오케스트레이터를 함께 설계해 주는 메타 스킬에 가깝다는 걸 알 수 있었습니다.이번 글에서는 제가 정리한 내용을 바탕으로 Harness가 무엇인지, 어떤 구조로 동작하는지, 실제로 어떻게 설치하고 사용할 수 있는지 정리해보려고 합니다.
Harness란 무엇인가요?
Harness는 Claude Code용 팀 아키텍처 팩토리입니다. 사용자가 “하네스 구성해줘” 또는 “Build a harness for this project”라고 요청하면, 해당 도메인에 맞는 에이전트 정의와 스킬을 생성합니다.
생성되는 주요 산출물은 다음과 같습니다.
.claude/agents/: 전문 에이전트 정의 파일
.claude/skills/: 각 에이전트가 사용할 스킬
- 오케스트레이터 스킬: 에이전트 팀을 어떤 순서와 규칙으로 조율할지 정의
CLAUDE.md포인터: 새 세션에서도 하네스가 트리거될 수 있도록 최소한의 안내 기록
즉 Harness는 어떤 작업을 직접 수행하는 단일 에이전트가 아니라, 복잡한 작업을 처리할 수 있는 에이전트 팀과 작업 방식을 만들어주는 도구입니다.
왜 필요한가요?
Claude Code에 복잡한 작업을 요청하면 기본적으로 하나의 에이전트가 분석, 구현, 검증, 문서화까지 모두 처리하게 됩니다. 작은 작업에서는 문제가 없지만, 작업이 커질수록 한 에이전트가 모든 컨텍스트를 들고 가기 어렵습니다.
Harness는 이 문제를 역할 분리로 해결합니다.
예를 들어 풀스택 웹사이트를 만든다고 하면 다음처럼 나눌 수 있습니다.
- 요구사항을 분석하는 에이전트
- UI/UX를 설계하는 에이전트
- 프론트엔드를 구현하는 에이전트
- 백엔드 API를 구현하는 에이전트
- QA와 테스트를 담당하는 에이전트
각 에이전트는 자신의 역할에 맞는 스킬을 사용하고, 오케스트레이터는 이 팀이 어떤 순서로 협업해야 하는지 조율합니다.
핵심 구조
Harness의 핵심은 에이전트, 스킬, 오케스트레이터를 분리하는 것입니다.
구성 요소 | 역할 |
에이전트 | 누가 작업하는지 정의합니다. 예: analyst, builder, qa |
스킬 | 어떻게 작업하는지 정의합니다. 작업 절차, 기준, reference를 담습니다. |
오케스트레이터 | 여러 에이전트를 어떤 순서로 실행하고, 산출물을 어떻게 주고받을지 정의합니다. |
하네스의 존재와 트리거 규칙만 가볍게 기록합니다. |
중요한 점은 에이전트 역할을 매번 프롬프트에 직접 넣는 것이 아니라,
.claude/agents/{name}.md 파일로 남긴다는 점입니다. 이렇게 해야 다음 세션에서도 같은 팀 구조를 재사용할 수 있습니다.지원하는 팀 아키텍처 패턴
Harness는 6가지 팀 아키텍처 패턴을 기준으로 작업을 설계합니다.
패턴 | 설명 | 적합한 상황 |
파이프라인 | 순차적으로 이어지는 작업 | 분석 → 설계 → 구현 → 검증처럼 앞 단계 산출물이 다음 단계 입력이 되는 경우 |
팬아웃/팬인 | 여러 작업을 병렬 처리 후 통합 | 리서치, 코드 리뷰처럼 여러 관점을 동시에 봐야 하는 경우 |
전문가 풀 | 상황에 따라 필요한 전문가만 호출 | 입력 유형에 따라 보안/성능/문서 전문가가 달라지는 경우 |
생성-검증 | 생성 후 리뷰어가 품질 검수 | 초안 생성 후 QA나 리뷰가 필요한 경우 |
감독자 | 중앙 에이전트가 작업을 동적으로 분배 | 작업량이 가변적이고 진행 중 재배치가 필요한 경우 |
계층적 위임 | 큰 작업을 하위 작업으로 재귀 분해 | 큰 프로젝트를 여러 하위 영역으로 나눠야 하는 경우 |
공식 문서 기준으로는 Agent Teams가 기본 실행 모드입니다. 2개 이상의 에이전트가 협업하고 서로 피드백을 주고받아야 한다면 팀 모드를 먼저 고려합니다. 반대로 단발성 작업이거나 결과만 반환하면 충분한 경우에는 서브 에이전트 방식이 더 가볍습니다.
설치 방법
가장 권장되는 방식은 Claude Code 플러그인 마켓플레이스를 통한 설치입니다.
/plugin marketplace add revfactory/harness /plugin install harness@harness
직접 설치도 가능합니다.
git clone https://github.com/revfactory/harness.git cp -r harness/skills/harness ~/.claude/skills/harness
추가로 Agent Teams 기능이 필요하므로 환경 변수 설정을 확인해야 합니다.
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
사용 방법
설치 후 Claude Code에서 다음처럼 요청하면 됩니다.
하네스 구성해줘 하네스 설계해줘 이 프로젝트에 맞는 에이전트 팀 구축해줘 Build a harness for this project Design an agent team for this domain
운영 중인 하네스를 점검하거나 수정할 때는 다음처럼 요청할 수 있습니다.
하네스 점검해줘 하네스 현황 알려줘 에이전트/스킬 동기화해줘 이전 결과 기반으로 업데이트해줘
실제 워크플로우
README에서는 전체 흐름을 6개 Phase로 설명합니다.
Phase 1: 도메인 분석 Phase 2: 팀 아키텍처 설계 Phase 3: 에이전트 정의 생성 Phase 4: 스킬 생성 Phase 5: 통합 및 오케스트레이션 Phase 6: 검증 및 테스트
다만 실제
SKILL.md를 보면 여기에 두 가지가 더 강조됩니다.첫째, Phase 0에 해당하는 현황 감사입니다. 기존
.claude/agents/, .claude/skills/, CLAUDE.md가 있는지 먼저 확인하고, 신규 구축인지 기존 확장인지 운영/유지보수인지 분기합니다.둘째, Phase 7에 해당하는 하네스 진화입니다. 하네스는 한 번 만들고 끝나는 것이 아니라, 실행 후 피드백을 받아 에이전트 정의, 스킬, 오케스트레이터,
CLAUDE.md 변경 이력을 계속 갱신하는 구조입니다.그래서 실제 운영 관점에서는 다음 흐름으로 이해하는 것이 더 정확합니다.
현황 감사 -> 도메인 분석 -> 팀 아키텍처 설계 -> 에이전트 정의 생성 -> 스킬 생성 -> 오케스트레이션 구성 -> 검증 및 테스트 -> 피드백 기반 진화
스킬 작성에서 중요한 점
Harness가 생성하는 스킬은 Progressive Disclosure 구조를 따릅니다. 항상 모든 내용을 컨텍스트에 넣지 않고, 필요한 단계에서 필요한 문서만 읽도록 설계합니다.
기본 구조는 다음과 같습니다.
skill-name/ ├── SKILL.md └── references/
SKILL.md에는 핵심 워크플로우와 트리거 규칙만 두고, 세부 가이드는 references/로 분리합니다. 이렇게 하면 컨텍스트를 아끼면서도 필요한 순간에는 깊은 지식을 불러올 수 있습니다.스킬 description도 중요합니다. Claude는 스킬 트리거를 보수적으로 판단하기 때문에, description에는 이 스킬이 언제 반드시 사용되어야 하는지 구체적으로 적어야 합니다.
검증도 하네스의 일부입니다
Harness에서 인상적이었던 부분은 에이전트와 스킬을 생성하는 것에서 끝나지 않고, 검증까지 포함한다는 점입니다.
대표적인 검증 방식은 다음과 같습니다.
- 에이전트 파일과 스킬 파일이 올바른 위치에 있는지 확인
- 스킬 frontmatter의
name,description확인
- 트리거되어야 하는 문장과 트리거되면 안 되는 문장을 나눠 테스트
- With-skill vs Without-skill 결과 비교
- 오케스트레이터의 데이터 전달 경로에 끊긴 부분이 없는지 드라이런
이 부분은 실제 팀에서 사용하려면 특히 중요해 보였습니다. 에이전트 팀은 구조가 복잡해질수록 좋아질 수도 있지만, 반대로 통신 경로가 불명확하면 오히려 혼란이 커질 수 있기 때문입니다.
핵심 원칙 4가지
제가 정리한 Harness의 핵심 원칙은 다음과 같습니다.
- 에이전트와 스킬을 파일로 남겨 재사용 가능하게 만듭니다.
- 2개 이상의 에이전트가 협업한다면 Agent Teams를 먼저 고려합니다.
CLAUDE.md에는 자세한 규칙이 아니라 오케스트레이터를 찾기 위한 포인터만 둡니다.
- 하네스는 고정물이 아니라 피드백을 반영하며 계속 진화하는 시스템으로 관리합니다.
정리
Harness는 단순히 에이전트를 많이 만드는 도구가 아닙니다. 복잡한 작업을 어떤 역할로 나누고, 어떤 스킬을 부여하고, 어떤 순서와 규칙으로 협업시킬지 설계하는 메타 스킬입니다.
Harness의 핵심은 자동화보다 구조화에 가깝다고 느꼈습니다. Claude Code를 잘 쓰기 위해서는 좋은 프롬프트뿐 아니라, 작업을 안정적으로 반복할 수 있는 팀 구조와 검증 루프가 필요할 것 같습니다.