(원리)하네스 엔지니어링 구축하기

`revfactory/harness`는 하네스를 어떻게 구축하는가

기준 저장소: https://github.com/revfactory/harness 확인 일자: 2026-04-18

한 줄 요약

revfactory/harness는 하네스를 직접 실행하는 런타임이라기보다, Claude Code 안에서 도메인별 하네스를 설계하고 생성하게 만드는 메타 스킬(plugin + skill) 이다.

즉 이 저장소의 핵심은:

사용자가 "하네스를 구축해줘"라고 요청한다.
harness 스킬이 현재 프로젝트를 분석한다.
그 결과로 .claude/agents/, .claude/skills/, 오케스트레이터 스킬, 최소한의 CLAUDE.md 포인터를 생성한다.
이후부터는 생성된 하네스가 프로젝트 안에서 반복적으로 작동한다.

1. 이 저장소가 실제로 만드는 것

이 저장소는 프로젝트 안에 아래와 같은 하네스 산출물을 만들도록 설계되어 있다.

your-project/
└── .claude/
    ├── agents/
    │   ├── analyst.md
    │   ├── builder.md
    │   └── qa.md
    └── skills/
        ├── analyze/
        │   └── SKILL.md
        ├── build/
        │   ├── SKILL.md
        │   └── references/
        └── {domain}-orchestrator/
            └── SKILL.md

따라서 revfactory/harness의 역할은 "일을 대신 수행하는 에이전트 묶음"이라기보다:

어떤 에이전트가 필요한지 결정하고
각 에이전트 정의 파일을 만들고
에이전트가 사용할 스킬을 만들고
전체 흐름을 묶는 오케스트레이터 스킬을 만드는

하네스 생성기에 가깝다.

2. 저장소 자체의 구조

README 기준 핵심 구조는 아래와 같다.

harness/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── harness/
│       ├── SKILL.md
│       └── references/
│           ├── agent-design-patterns.md
│           ├── orchestrator-template.md
│           ├── team-examples.md
│           ├── skill-writing-guide.md
│           ├── skill-testing-guide.md
│           └── qa-agent-guide.md
└── README.md

이 구조를 보면 구축 방식이 분명하다.

plugin.json: 이 저장소를 Claude Code plugin으로 설치하게 하는 진입점
skills/harness/SKILL.md: 실제 "하네스를 구축하는" 메인 메타 스킬
references/*: 아키텍처 패턴, 오케스트레이터 템플릿, 스킬 작성법, 테스트 방법을 담은 설계 레퍼런스

즉, plugin이 껍데기이고, 실질적 구축 로직은 harness 스킬 안에 들어 있다.

3. 구축 흐름의 핵심: 6단계 + 감사(Phase 0)

skills/harness/SKILL.md를 보면 이 저장소는 하네스 구축을 대략 아래 순서로 진행한다.

Phase 0. 현황 감사

가장 먼저 현재 프로젝트의 기존 하네스를 읽는다.

프로젝트/.claude/agents/
프로젝트/.claude/skills/
프로젝트/CLAUDE.md

여기서 판단하는 것은 세 가지다.

신규 구축인지
기존 하네스 확장인지
운영/유지보수 요청인지

또한 기존 파일과 CLAUDE.md 기록이 서로 어긋나는 drift도 점검한다.

Phase 1. 도메인 분석

이 단계에서 하네스를 "무슨 일을 하는 구조"로 만들지 결정한다.

프로젝트 도메인 파악
핵심 작업 유형 식별
기존 에이전트/스킬과 충돌 여부 확인
코드베이스 탐색
사용자 숙련도 감지

즉, 범용 템플릿을 그대로 복사하는 것이 아니라 프로젝트와 사용자 수준에 맞게 맞춤형 설계를 하려는 구조다.

Phase 2. 팀 아키텍처 설계

여기서 중요한 것은 agent team과 subagent를 구분해서 고르는 것이다.

기본값: agent team
대안: subagent
필요 시: hybrid

그리고 6가지 패턴 중 하나를 고른다.

Pipeline
Fan-out / Fan-in
Expert Pool
Producer-Reviewer
Supervisor
Hierarchical Delegation

즉 이 하네스는 "에이전트를 몇 개 만들지"보다 먼저, 협업 구조를 어떤 패턴으로 설계할지를 결정한다.

Phase 3. 에이전트 정의 생성

이 단계에서 .claude/agents/{name}.md 파일을 만든다.

핵심 원칙은 분명하다.

에이전트 역할을 즉석 프롬프트로만 넣지 말 것
반드시 파일로 정의할 것
역할과 원칙, I/O, 에러 핸들링, 협업 규칙을 문서화할 것

즉 하네스를 "사람 머릿속 운영"이 아니라 파일 기반 운영 구조로 고정한다.

Phase 4. 스킬 생성

이 단계에서 .claude/skills/{name}/SKILL.md를 만든다.

중요한 설계 원칙은 세 가지다.

스킬은 어떻게 하는가를 담는다.
description은 매우 적극적으로 써서 트리거를 유도한다.
Progressive Disclosure로 컨텍스트 비용을 관리한다.

이 저장소는 스킬을 3층 구조로 본다.

Metadata: 항상 보이는 name + description
SKILL.md 본문: 스킬이 호출될 때 로드
references/: 필요할 때만 읽는 세부 문서

즉 하네스 구축의 핵심 철학이 context economy에 맞춰져 있다.

Phase 5. 통합 및 오케스트레이션

여기서 개별 에이전트와 개별 스킬을 하나의 팀 워크플로우로 엮는다.

핵심 산출물은 오케스트레이터 스킬이다.

오케스트레이터는:

누가
언제
어떤 순서로
어떤 방식으로 협업하는지

를 정의한다.

이 점이 중요하다. 이 저장소에서 하네스는 단순한 agent 모음이 아니라, 오케스트레이터가 있는 구조화된 팀이다.

Phase 6. 검증 및 테스트

생성한 스킬과 하네스를 바로 끝내지 않고 테스트한다.

레퍼런스 문서 기준 검증 항목은 다음과 같다.

트리거 검증
dry-run 테스트
with-skill vs baseline 비교
assertion 기반 정량 평가
반복 개선 루프

즉 revfactory/harness는 하네스를 "만드는 것"만이 아니라, 검증 가능한 운영 구조로 다듬는 것까지 포함한다.

4. 이 저장소가 보는 하네스의 본질

이 저장소를 읽으면 하네스의 정의가 비교적 명확하다.

하네스는:

에이전트 정의 파일
에이전트가 쓰는 스킬
전체를 묶는 오케스트레이터
이를 뒷받침하는 최소한의 CLAUDE.md 포인터

로 이루어진 구조화된 협업 환경이다.

따라서 이 저장소에서 하네스 구축은:

프롬프트를 잘 쓰는 일이 아니라 에이전트, 스킬, 실행 모드, 오케스트레이션, 검증을 파일로 설계하는 일

로 이해하는 것이 맞다.

5. 왜 Agent Team을 기본값으로 두는가

agent-design-patterns.md 기준으로 이 저장소는 subagent보다 agent team을 우선한다.

이유는 다음과 같다.

팀원 간 직접 통신이 가능하다
공유 작업 목록으로 자체 조율이 가능하다
발견 공유, 상충 토론, 교차 검증이 가능하다
복잡한 문제일수록 품질이 좋아진다고 본다

반대로 subagent는:

가볍고 빠르며
토큰 효율이 좋고
결과만 메인에 반환하면 되는 작업에 적합하다

즉 이 저장소의 관점에서:

agent team = 협업 중심 기본 구조
subagent = 경량 대안

이다.

이 부분은 발표에서 매우 중요하다. 하네스 = 서브에이전트 모음이 아니라, 이 저장소에서는 오히려 팀 기반 협업 구조를 기본 하네스로 본다.

`agent team`과 `subagent`를 쉽게 구분하면

많이 헷갈리는 지점은 여기다.

agent team은 여러 에이전트가 역할을 나누고 협업하는 구조다.
subagent는 메인 흐름에서 떼어낸 하위 작업을 분리된 context에서 처리하고 결과만 돌려주는 구조다.

짧게 줄이면:

agent team = 같이 일하는 구조
subagent = 따로 일시키는 구조

따라서 보통 아래처럼 판단하면 된다.

서로 검토, 반박, 조정, 교차검증이 필요하면 agent team
독립적으로 던져두고 결과만 받으면 되면 subagent

예시:

논문 주장 점검, 반론 검토, 코드 리뷰, 전략 설계: agent team
문헌 훑기, 로그 정리, 파일 탐색, 초안 생성: subagent

즉 Phase 2에서 먼저 정하는 것은 "몇 명 만들까"가 아니라:

이 문제는 협업형 문제인가, 위임형 문제인가

이다.

6. Progressive Disclosure는 왜 중요한가

revfactory/harness를 이해할 때 꼭 잡아야 하는 개념이 Progressive Disclosure다.

뜻은 단순하다.

처음부터 모든 정보를 한꺼번에 로드하지 않고, 필요할 때만 다음 층의 정보를 열어 주는 방식

이 저장소는 스킬을 대략 3층 구조로 다룬다.

name + description
SKILL.md 본문
references/ 아래 세부 문서

로드 방식은 이렇게 이해하면 된다.

평소에는 description만 얇게 보인다.
실제로 스킬이 호출되면 SKILL.md 본문이 로드된다.
더 깊은 규칙이나 예시는 필요할 때만 references/에서 읽는다.

이 설계가 중요한 이유는 context window 때문이다.

처음부터 모든 규칙을 다 넣으면 context가 빨리 찬다.
context가 빨리 차면 성능이 떨어진다.
그래서 하네스는 정보를 단계적으로 드러내도록 설계된다.

비유로 하면:

책상 위에 모든 책을 다 펼쳐놓는 것이 아니라, 목차만 두고 필요할 때 해당 책만 꺼내는 방식

이다.

발표용 한 줄:

Progressive Disclosure는 필요한 정보만 단계적으로 드러내서 context 비용을 줄이는 설계 방식이다.

7. 실제 구축 절차를 한국어로 풀어쓰면

사용자가 Claude Code에서 다음처럼 말한다.

"이 프로젝트용 하네스를 구축해줘."

그러면 이 plugin/skill은 대략 이렇게 작동한다.

현재 프로젝트의 .claude 상태와 CLAUDE.md를 점검한다.
프로젝트 도메인과 반복 작업 유형을 분석한다.
에이전트 팀이 필요한지, 서브에이전트가 적합한지 판단한다.
적절한 협업 패턴을 선택한다.
.claude/agents/*.md에 전문 에이전트를 정의한다.
.claude/skills/*/SKILL.md에 에이전트별 스킬을 만든다.
전체를 묶는 오케스트레이터 스킬을 만든다.
CLAUDE.md에는 새 세션에서도 이 하네스를 다시 찾을 수 있게 최소 포인터를 남긴다.
테스트 프롬프트로 트리거와 품질을 검증한다.
결과를 보고 수정하면서 하네스를 진화시킨다.

즉, 구축은 일회성 생성이 아니라 설계 → 생성 → 연결 → 검증 → 개선의 루프다.

8. Plugin, Skill, Marketplace를 이 맥락에서 어떻게 이해할까

하네스를 설명하다 보면 skill, plugin, marketplace가 쉽게 섞인다. 여기서는 층위를 나눠서 이해하는 것이 중요하다.

Skill

skill은 특정 작업을 반복 가능하게 만든 지침 또는 플레이북이다.

예:

데이터 변수 탐색 방법
회귀 결과 점검 절차
논문 초안 작성 규칙

즉 skill은 "어떻게 하는가"를 담는 단위다.

Plugin

plugin은 스킬 하나만 담는 기능이 아니라, 필요하면 여러 skill, agent, 도구 연동, MCP 서버 연결, 설치 정책이나 일부 설정까지 묶어서 배포하는 패키지다.

즉:

skill이 개별 도구라면
plugin은 도구 상자이자 작업환경 묶음이다

따라서 "내가 만든 스킬을 다른 프로젝트나 팀원에게 재사용시키고 싶다"는 요구가 커지면 plugin 층위로 올라간다.

Marketplace

marketplace는 그렇게 만든 plugin을 보여 주고, 찾고, 설치하고, 관리하는 카탈로그다.

중요한 점:

plugin은 배포 단위
marketplace는 배포물을 보여 주는 목록/유통 층위

10. 학습 자료용 핵심 Q&A

Q1. 하네스 엔지니어링이란 무엇인가

AI가 지속적으로 좋은 결과를 내도록 프롬프트, 컨텍스트, 도구, 역할 분리를 구조적으로 설계하는 일

또는 더 쉽게:

AI를 잘 쓰는 요령이 아니라, AI가 잘 일하게 만드는 운영 구조를 설계하는 것

Q2. 하네스는 결국 서브에이전트 팀을 만드는 것인가

부분적으로만 맞다.

subagent는 하네스의 한 구성요소일 수 있다.
하지만 하네스 전체는 context 관리, 역할 분리, 스킬 설계, 오케스트레이션, 검증까지 포함한다.

즉:

하네스 엔지니어링 > 서브에이전트 구성

이다.

Q3. agent와 subagent의 차이는 무엇인가

agent: 일을 수행하는 주체를 넓게 가리키는 일반 개념
subagent: 메인 agent가 특정 하위 작업을 맡기기 위해 호출한 하위 agent

짧게:

모든 subagent는 agent이지만, 모든 agent가 subagent는 아니다

Q4. agent team과 subagent의 차이는 무엇인가

agent team: 여러 에이전트가 역할을 나누고 협업하는 구조
subagent: 하위 작업을 독립적인 context에서 처리한 뒤 결과만 돌려주는 구조

짧게:

agent team = 같이 일하는 구조
subagent = 따로 일시키는 구조

Q5. Progressive Disclosure란 무엇인가

처음부터 모든 정보를 다 넣지 않고, 필요할 때만 다음 층의 정보를 여는 방식

하네스 문맥에서는:

context 비용을 줄이기 위한 단계적 정보 로딩 설계

를 뜻한다.

결론

revfactory/harness에서 하네스 구축이란, 프로젝트의 작업 유형을 분석한 뒤 그에 맞는 에이전트 팀 구조, 개별 스킬, 오케스트레이터, 검증 절차를 .claude 파일 체계로 구현하는 것이다.

목록으로 돌아가기