Harness: 한 줄의 프롬프트로 Claude Code를 위한 완전한 에이전트 팀 구축하기

당신에게는 Claude Code가 있습니다. 당신은 심도 있는 연구 파이프라인(research pipeline), 풀스택 앱 스캐폴드(full-stack app scaffold), 코드 리뷰 시스템과 같이 야심 찬 무언가를 구축하고 싶습니다. 에이전트(agent)를 수동으로 연결하며 각 정의를 일일이 직접 작성할 수도 있습니다. 아니면 "이 프로젝트를 위한 harness를 구축해줘"라고 입력하고 Harness가 이를 수행하도록 맡길 수도 있습니다.

Harness는 당신이 구축하고자 하는 것에 대한 평이한 영어 설명을 입력받아 즉시 실행 가능한 에이전트 팀을 생성하는 Claude Code 플러그인입니다. 에이전트 정의(agent definitions), 스킬 파일(skill files), 오케스트레이션 로직(orchestration logic) 등 모든 것을 만들어냅니다.

이것은 어떤 문제를 해결하나요?

Claude Code에서 멀티 에이전트(Multi-agent) 작업을 수행하려면 많은 사전 스캐폴딩(scaffolding) 작업이 필요합니다. 당신은 다음을 수행해야 합니다:

.claude/agents/ 마크다운 파일에 각 에이전트의 역할과 책임을 정의
작업이 수행되는 방식을 설명하는 스킬 파일(skill files)을 .claude/skills/에 작성
에이전트들이 어떻게 통신하고 작업을 인계(hand off)할지 결정
오류 케이스(error cases) 및 검증(validation) 처리

사소하지 않은 프로젝트의 경우, 실제 코드를 한 줄도 쓰기 전에 몇 시간의 작업이 소요됩니다. Harness는 이를 단 한 번의 대화형 프롬프트(conversational prompt)로 압축합니다.

6가지 아키텍처 패턴

Harness는 단순히 에이전트들을 폴더에 쏟아붓는 것이 아닙니다. 당신의 도메인(domain)에 따라 검증된 6가지 팀 구조 중 하나를 선택합니다:

Pipeline (파이프라인) — 에이전트들이 순차적으로 실행되며, 각 에이전트가 다음 에이전트에게 결과물을 전달합니다. 계획(plan), 작성(write), 테스트(test), 배포(deploy)와 같이 명확한 단계가 있는 모든 작업에 적합합니다.

Fan-out/Fan-in (팬아웃/팬인) — 코디네이터(coordinator)가 병렬 에이전트들을 생성하고, 그들의 결과를 수집하여 병합합니다. 독립적인 스레드(threads)가 동시에 실행될 수 있는 연구(research)나 코드 리뷰(code review)에 적합합니다.

Expert Pool (전문가 풀) — 현재 작업에 필요한 요구 사항에 따라 선택적으로 호출되는 전문가 에이전트들입니다. 다양한 하위 문제(sub-problems)가 존재하는 도메인에 적합합니다.

Producer-Reviewer (생성자-검토자) — 한 에이전트는 생성하고, 다른 에이전트는 비판(critique)합니다. 콘텐츠 생성, 문서화, 또는 품질 게이트(quality gates)가 중요한 모든 작업에 적합합니다.

Supervisor (감독관) — 중앙 에이전트가 다음에 수행해야 할 작업에 따라 워커(worker)들에게 동적으로 작업을 라우팅(route)합니다. 개방형 워크플로우(open-ended workflows)에 적합합니다.

계층적 위임 (Hierarchical Delegation) — 복잡한 작업이 여러 계층을 거쳐 세분화되는 하향식 재귀적 위임 (top-down recursive delegation) 방식입니다. 대규모 엔지니어링이나 프로젝트 관리 (project management)에 적합합니다.

Harness는 사용자의 설명을 읽고 가장 적합한 패턴을 선택합니다. 또한 사용자가 명시적으로 가이드할 수도 있습니다.

설정 (Setup)

사전 요구 사항 (Prerequisites)

Claude Code가 설치되어 있어야 하며, 에이전트 팀 (agent teams) 기능이 활성화되어 있어야 합니다. 에이전트 팀은 아직 기능 플래그 (feature flag) 뒤에 숨겨져 있습니다:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

이 설정이 유지되도록 셸 프로필 (.zshrc, .bashrc 등)에 추가하세요.

플러그인 마켓플레이스 (Plugin Marketplace)를 통한 설치

Claude Code 내부에서 다음을 실행하세요:

/plugin marketplace add revfactory/harness

그 다음:

/plugin install harness@harness

끝입니다. 이제 플러그인을 Claude Code 세션에서 전역적으로 사용할 수 있습니다.

수동 설치 (전역 스킬 (Global Skill))

직접 관리하는 것을 선호한다면, 저장소 (repo)를 클론(clone)하고 스킬을 직접 복사하세요:

git clone https://github.com/revfactory/harness.git
cp -r harness/skills/harness ~/.claude/skills/harness

이렇게 하면 스킬 파일이 Claude Code의 전역 스킬 디렉토리에 저장되어 모든 프로젝트에서 사용할 수 있게 됩니다.

사용법 (Using It)

설치가 완료되면 Claude Code 내부에서 자연어 프롬프트 (natural language prompt)로 실행하세요. 특별한 구문은 없으며, 원하는 내용을 설명하기만 하면 됩니다.

예시: 심층 조사 에이전트 팀 (deep research agent team)

심층 조사를 위한 harness를 구축해줘. 웹 검색, 학술 자료, 커뮤니티 여론 등 다양한 관점에서 어떤 주제든 조사하고, 그 결과를 교차 검증하여 종합적인 보고서를 작성할 수 있는 에이전트 팀이 필요해.

예시: 코드 리뷰 파이프라인 (code review pipeline)

종합적인 코드 리뷰를 위한 harness를 구축해줘. 아키텍처, 보안 취약점, 성능 병목 현상, 코드 스타일을 병렬로 체크하는 에이전트들을 원하며, 모든 조사 결과를 하나의 보고서로 병합해야 해.

예시: 풀스택 개발 (full-stack development)

풀스택 웹사이트 개발을 위한 harness를 구축합니다. 팀은 와이어프레임(wireframe)부터 배포(deployment)까지 조정된 파이프라인 내에서 디자인, 프론트엔드 (React/Next.js), 백엔드 (API), 그리고 QA 테스트를 처리해야 합니다.

이 중 하나를 실행하고 나면, Harness는 프로젝트에 다음과 같은 파일들을 생성합니다:

your-project/
├── .claude/
│   ├── agents/
...

에이전트(agent) 파일은 각 에이전트의 페르소나(persona), 역량(capabilities), 그리고 제약 사항(constraints)을 정의합니다. 스킬(skill) 파일은 각 에이전트가 따르는 단계별 절차를 정의합니다. 사용자는 모든 파일을 읽고 편집할 수 있으며, 그 어떤 것도 블랙박스(black box)로 남겨두지 않습니다.

6단계 워크플로(Six-Phase Workflow)의 모습

Harness는 단순히 파일들을 쏟아내는 것이 아닙니다. 구조화된 프로세스를 실행합니다:

도메인 분석 (Domain Analysis) — 프롬프트를 읽고 주요 행위자(actors), 입력(inputs), 출력(outputs)을 식별합니다.
팀 아키텍처 설계 (Team Architecture Design) — 6가지 패턴 중 적절한 것을 선택하고 팀 구조를 스케치합니다.
에이전트 정의 생성 (Agent Definition Generation) — .claude/agents/ 마크다운(markdown) 파일들을 작성합니다.
스킬 생성 (Skill Generation) — 점진적 공개 (Progressive Disclosure, 필요한 시점에 필요한 컨텍스트만 로드하는 방식)를 적용하여 .claude/skills/ 파일들을 작성합니다.
통합 및 오케스트레이션 (Integration and Orchestration) — 에이전트 간의 데이터 전달 및 에러 핸들링(error handling)을 연결합니다.
검증 및 테스트 (Validation and Testing) — 트리거 검증(trigger verification) 및 드라이 런(dry-run) 테스트를 설정합니다.

그만한 가치가 있는가?

해당 리포지토리(repo)에는 15가지 소프트웨어 엔지니어링 작업을 다루는 동반 리포지토리(revfactory/claude-code-harness)의 A/B 테스트 결과가 포함되어 있습니다:

지표	Harness 미사용 시	Harness 사용 시
평균 품질 점수	49.5 / 100	79.3 / 100
...

개선 효과는 작업의 복잡도에 따라 비례하여 나타났습니다: 기본 작업에서 +23.8점, 고급 작업에서 +29.6점, 전문가 수준의 작업에서 +36.2점이 향상되었습니다. 문제가 어려울수록 구조화된 방식이 더 큰 도움이 됩니다.

한 가지 중요한 주의 사항은, 이것이 n=15인 저자 측정 연구이며, 제3자에 의한 재현 결과는 아직 발표되지 않았다는 점입니다.

명확하게 도움이 되는 부분:

새로운 프로젝트를 시작하면서 정의를 내리는 데 시간을 허비하지 않고 에이전트 스캐폴딩 (Agent Scaffolding)을 구축하고 싶은 경우
작업이 팀 패턴으로 깔끔하게 매핑되는 여러 개의 뚜렷한 하위 문제들로 구성된 경우
다양한 팀 아키텍처 (Team Architectures)를 빠르게 실험해보고 싶은 경우
임시 프롬프팅 (Ad-hoc prompting)으로는 일관되지 않은 결과가 발생하는 충분히 복잡한 무언가를 구축하고 있는 경우

생성되는 것 vs 유지 관리하는 것

Harness는 시작점을 생성합니다. 생성된 파일은 일반 마크다운 (Markdown) 형식으로, 읽기 쉽고 편집 가능하며 버전 관리 (Version-controllable)가 가능합니다. 생성 후에는 사용자가 해당 파일에 대한 소유권을 갖습니다.

생태계 적합성

Harness는 Claude Code 네이티브 (Claude Code-native)입니다. 기본적으로 Gemini CLI나 Codex와는 작동하지 않으며, 이를 위한 meta-harness라는 Codex 포트 (Port)가 존재합니다.

상태 복구가 가능한 장기 실행 오케스트레이션 (Orchestration)을 위해 LangGraph를 사용하고 있다면, Harness는 대체재가 아닙니다. LangGraph는 세션 전반에 걸친 지속적인 상태 (Persistent state)와 복구를 처리하며, Harness는 Claude Code 내에서의 팀 아키텍처 설계를 처리합니다. 이들은 서로 다른 계층 (Layers)을 차지합니다.

빠른 참조

# 에이전트 팀 활성화
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

...

결론

Harness는 실제적인 문제를 해결합니다. 멀티 에이전트 스캐폴딩 (Multi-agent scaffolding)은 처음부터 작성하기 지루하고, 실수하기 쉬우며, 일관성을 유지하기 어렵습니다. Harness는 구조적인 작업을 처리하므로 사용자는 도메인 로직 (Domain logic)에 집중할 수 있습니다.

Repository: github.com/revfactory/harness
License: Apache 2.0