LLM for Research 01 - Claude Code용 하네스(Harness) 플러그인으로 나만의 연구 워크플로우를 팀 아키텍처로 제작

TL;DR

• revfactory/harness 플러그인을 써서, 내가 매주 반복하던 연구 워크플로우를 에이전트 팀 + 스킬 구조로 자동화했다.
• 도메인 설명 한 번으로 에이전트 8명 + 스킬 9개 + 오케스트레이터 1개가 몇 분 만에 구축됐다.
• 가장 큰 수확은 "코드 자동화"가 아니라, 내 워크플로우가 어디서 분기되고 어디서 실패 감지되는지를 문서처럼 드러낸 것이었다.
• 연구 내용 자체는 민감 영역이라 이 글에서는 기술적 세부는 블러 처리한다. 중심은 "하네스 구축 경험 그 자체".

---

1. 배경 — 왜 "하네스"가 필요했나

나는 로봇 제어 쪽 연구를 한다. 주기적으로 도는 루프가 있다.

1. 실기 시연(Kinesthetic demonstration) 데이터 수집·전처리
2. 데이터 상관/인과 분석
3. Signal/Case config 설계
4. 정책 학습 (여러 case 병렬)
5. 시뮬레이션 regression 검증
6. 실기 배포 및 안전 감시
7. 주간 보고 / 논문 업데이트

문제는, 이걸 매주 반복하는데도 매번 "어디서부터 다시 돌려야 하지?" 로 시작한다는 것이다. 일부 산출물만 바꿔도 뒷 단계가 실패하고, 실패 원인을 찾다가 한 주가 간다.

LLM 에이전트를 도입해볼까 싶어서 이것저것 시도했지만, 결국 "에이전트가 여러 명 있는 구조를 내가 직접 설계하는 것" 에서 막혔다. 에이전트 정의 파일을 수작업으로 쓰고, 스킬 파일 구조 맞추고, 서로가 부르는 프로토콜을 정하고… 이걸 할 시간이 있으면 연구를 하지.

그러다 발견한 게 revfactory/harness 다.

---

2. revfactory/harness 가 하는 일

한 줄 요약하면 이렇다 [HIGH, 공식 README 기반]:

"하네스 구성해줘" 한 문장이면, 내 도메인 설명을 에이전트 팀 + 스킬 로 변환한다.

조금 더 풀어쓰면 이런 포지션이다 (공식 README 인용, 일부 축약):

• Claude Code 생태계의 L3 Meta-Factory 중 Team-Architecture Factory 서브 층
• 사전 정의된 6가지 팀 아키텍처 패턴 중 하나를 골라줌
  • 파이프라인 / 팬아웃·팬인 / 전문가 풀 / 생성-검증 / 감독자 / 계층적 위임
• 출력물: .claude/agents/ 에이전트 정의 + .claude/skills/ 스킬 정의

"LangGraph 같은 상태 그래프"나 "Archon 같은 런타임 결정성 도구"와는 층이 다르다. LangGraph는 장기 실행·상태 복구가 핵심이고, Archon은 런타임 설정을 결정적으로 뽑는 도구다. Harness는 팀 아키텍처를 설계하는 층이다. 이 구분은 README의 "공존" 테이블에 정리돼 있다. [MEDIUM — 개인적 해석 포함]

실제로 공식 저장소에서 제시한 자체 A/B 측정 결과 [MEDIUM — n=15 self-reported, 제3자 재현은 진행 중이라고 명시]:

• 평균 품질: 49.5 → 79.3 (+60%)
• 15/15 승률
• 출력 분산 −32%
• 과제 난이도가 높을수록 개선 폭 증가 (Basic +23.8 / Advanced +29.6 / Expert +36.2)

수치는 저자 self-reported라는 점은 README에 명시돼 있으니 과대 해석하지 말자. 내가 믿은 건 "수치"보다 "구조화된 팀 아키텍처를 반복 가능하게 뽑아주는 공정" 그 자체였다.

---

3. 구축 준비 — 내가 먼저 한 일

Harness 플러그인을 그냥 부른다고 끝나지 않는다. 도메인 설명을 쓰는 것은 내 몫이다. 이게 이 플러그인의 가장 정직한 부분이다 — "네 워크플로우를 네가 모르면 아무도 대신 못 해준다."

나는 하네스를 부르기 전에 드래프트 템플릿 부터 혼자 썼다. 형식은 이렇다:

1. 도메인 / 목적
2. 입력 / 출력 (경로 / 포맷까지)
3. 주요 서브태스크 (의존성 · 매칭 패턴 · 긴급도)
4. 제약 / 선호 (기존 자산, 언어 톤, 금기 사항)
5. 체크리스트 — 확정 전 검토
6. 불확실 / 추측 사항 (분리)

여기서 배운 팁 3가지:

1. "구체 > 추상" — "정책 학습" 같은 말은 쓰지 말고, "특정 config JSON 기반으로 N개의 case를 병렬로 학습" 처럼 파일 경로와 숫자까지 내려와야 한다. 그래야 뒤에서 에이전트가 자동화할 여지가 생긴다.
2. 실패 사례 > 성공 사례 — 내 경우 과거에 3가지 고질적 실패 패턴이 있었다. 이걸 "재발 방지 규칙"으로 템플릿에 적어두니, 그대로 Deploy/QA 에이전트의 감시 항목이 됐다.
3. 범위 밖을 명시하라 — "이건 이 하네스가 안 한다" 목록을 쓰는 게 범위 안 목록 쓰는 것보다 더 중요했다. 다른 연구 트랙(PPLM-DOB, 외부 공동연구 등)이 잘못 트리거되면 하네스가 안 쓰느니만 못해진다.

드래프트가 다 쓰여지니, 오히려 "나는 내가 이 워크플로우를 이 정도로 명확히 알고 있었나?" 라는 깨달음이 왔다. 하네스 구축의 절반은 사실 이 단계였다.

---

4. 실제 구축 — Harness 6 Phase 워크플로우

Harness 스킬이 공식적으로 제시하는 워크플로우는 6 Phase다 [HIGH, 공식 README]:

Phase 1: 도메인 분석
Phase 2: 팀 아키텍처 설계 (에이전트 팀 vs 서브 에이전트)
Phase 3: 에이전트 정의 생성 (.claude/agents/)
Phase 4: 스킬 생성 (.claude/skills/)
Phase 5: 통합 및 오케스트레이션
Phase 6: 검증 및 테스트

내 경우 각 Phase에서 어떻게 결정했는지, 블러 처리한 예시와 함께 정리한다.

Phase 1 — 도메인 분석

드래프트 템플릿을 그대로 먹였다. 하네스는 이걸 읽고 다음을 확정한다:

• 서브태스크 N개 → 내 경우 7개 (데이터 전처리 / 통계 분석 / config 설계 / 메인 학습 / 대안 알고리즘 정찰 / 제어기 관리 / 배포·안전 QA / 주간 보고)
• 의존성 그래프
• 각 태스크의 "긴급도"

여기서 하네스의 가이드가 좋았던 건, "평소엔 유휴인데 특정 트리거에서만 활성화되는 에이전트" 를 명시적으로 허용한다는 점이었다. 내 워크플로우에는 "현재 알고리즘이 안 되면 대안 알고리즘을 시험하는" 에이전트가 필요했는데, 이걸 상시 돌리면 오버엔지니어링이고, 아예 없애면 분기점에서 수동 전환이 필요하다. "유휴 상태 + 트리거 조건 3종" 으로 정의해두니 깔끔해졌다.

Phase 2 — 팀 아키텍처 설계

핵심 결정 포인트는 "에이전트 팀"(동시 협업) vs "서브 에이전트"(단발 호출) 였다. Harness의 판단 기준은 대략:

모드	권장 상황
에이전트 팀	2명 이상, 실시간 협업 · 메시지 교환 필요
서브 에이전트	단발성 작업, 통신 불필요

내 워크플로우에서 데이터→학습→배포 구간은 실시간 피드백 루프(학습 실패 → config 재설계 → 재학습)가 자주 일어난다. 여기는 에이전트 팀. 반면 주간 보고 는 앞 산출물만 모아서 한 번 쓰면 끝나는 작업이라 서브 에이전트. 결국 하이브리드(3 팀 + 1 서브) 로 갔다.

복합 패턴 조합은 다음처럼 권장됐다 [MEDIUM — 내 도메인 특성 반영]:

파이프라인 (A → B → C → D)
  × 팬아웃/팬인 (B 단계에서 N개 case 병렬)
  × 생성-검증 (B ↔ C, 학습 ↔ 배포 반복)
  × 경량 감독자 (D, 파일 기반 수집)

이 조합이 README의 "team-examples.md" 에 나와 있는 실전 예시와 비슷한 형태였다. 공식 패턴 카탈로그를 참고 자료로 계속 열어두는 게 좋다.

Phase 3 — 에이전트 정의 생성

.claude/agents/{name}.md 파일이 에이전트별로 하나씩 생성됐다. 구조는 대체로 이렇다:

---
name: <agent-name>
description: <언제 이 에이전트가 호출되는지>
model: opus
---

# 역할
# 주 스킬
# 입력 / 출력 계약
# 금기 사항

여기서 비로소 느낀 점 — "에이전트 정의" 는 페르소나가 아니라 계약 이다. "너는 친절한 분석가야" 같은 거 쓰는 게 아니라, "너는 어떤 파일을 읽어서 어떤 파일을 내보내는지" 를 쓴다. 이건 기존 LLM 프롬프트 엔지니어링과 결이 다르다.

Phase 4 — 스킬 생성

스킬은 Progressive Disclosure 패턴을 따른다 [HIGH, 공식 SKILL-writing-guide]. 즉, SKILL.md 는 500줄 이내로 유지하고, 세부 레퍼런스는 references/ 하위로 뺀다. 컨텍스트 효율 때문이다.

내가 만든 스킬 구조 (이름만 일반화):

.claude/skills/
├── <main>-orchestrator/SKILL.md   ← 메인 진입점
├── data-pipeline/SKILL.md
├── stats-analysis/SKILL.md
├── config-design/SKILL.md
├── train-multi/SKILL.md
├── alt-scout/SKILL.md
├── controller-sync/SKILL.md
├── deploy-qa/SKILL.md
└── weekly-report/SKILL.md

각 스킬의 description 필드가 가장 중요하다. 이게 "이 스킬이 언제 자동 로드될지" 를 결정한다. 여기를 소홀히 쓰면 에이전트가 안 부른다. 반대로 너무 광범위하게 쓰면 엉뚱한 상황에 끼어든다. 실전 팁: description에 "should trigger 예시 10개 + should NOT trigger 근접 경계 예시 5개" 를 미리 적어두고, 이걸 디스크립션 작성 기준으로 삼았다.

Phase 5 — 통합·오케스트레이션

가장 중요한 파일이 <main>-orchestrator/SKILL.md 다. 이 스킬은:

1. Phase 0: 컨텍스트 확인 — _workspace/ 에 이전 실행이 남아있는지 보고, 신규 / 부분 재실행 / 전체 재실행을 구분.
2. Phase A/B/C/D: 각 팀 호출 — TeamCreate → TaskCreate → 실시간 SendMessage → TeamDelete 까지 한 사이클.
3. Phase 5: 정리 — 산출물 경로 보고, 감사 로그 보존.

여기서 Harness가 강조하는 규칙 중 특히 유용했던 2개 [HIGH]:

• "모든 Agent/TeamCreate 호출은 model: "opus" 명시 필수" — 안 그러면 팀 구성원마다 모델이 다른 엣지 케이스가 생김.
• "후속 작업 키워드를 description에 반드시 넣어라" — "재실행", "업데이트", "부분", "다시", "이전 결과" 같은 말이 들어가야 사용자가 두 번째 대화에서 "그거 다시 돌려줘" 했을 때 자동 로드된다.

Phase 6 — 검증 및 테스트

Harness의 검증 체계는 3층이다 [HIGH, 공식 skill-testing-guide]:

1. 트리거 검증 — should-trigger 예시 N개, should-NOT-trigger 근접 경계 예시 M개
2. 드라이런 테스트 — 실제 에이전트 호출 없이 의사(pseudo) 실행 시나리오
3. With-skill vs Without-skill 비교 — 스킬이 있을 때/없을 때 결과 차이 측정

나는 시간상 2번까지만 했다. 3번은 다음 주차 사이클 끝나고 시도할 예정.

---

5. 결과물 — 하루 만에 나온 것

드래프트 쓰는 데 반나절, 하네스 돌리는 데 2시간, 검증 체크리스트 돌리는 데 1시간. 총 약 1 working day 만에 다음이 나왔다:

project/
├── CLAUDE.md                      # 트리거 규칙 + 변경 이력
├── .claude/
│   ├── HARNESS_README.md          # 하네스 개요 문서 (자동 생성)
│   ├── agents/                    # 8 에이전트
│   └── skills/                    # 9 스킬 (오케스트레이터 1 + 개별 8)
├── _workspace/                    # 사이클 산출물 (실행 시 자동 생성)
├── harness_template_draft.md      # 내가 쓴 도메인 드래프트
└── ref/harness/                   # 참고용 공식 repo 스냅샷

중요: 파일 자체보다 "내가 앞으로 한 사이클 돌리려면 이 하나의 트리거만 부르면 된다" 는 사실이 가장 컸다. 예:

• "이번 주 새 시연 데이터 들어왔어. 전체 사이클 돌려줘." → 신규 실행
• "특정 case만 재학습해줘." → 부분 재실행 (이전 산출물 그대로 참조)
• "실기에서 XX 문제 또 났어. 재배포 루프 돌려줘." → Phase C부터 재실행 + 피벗 트리거 판정

---

6. 예상치 못했던 수확

세 가지가 컸다.

(a) 내가 몰랐던 "분기점"이 드러났다

드래프트에 서브태스크 의존성을 그려보니, "학습 실패 → config 재설계" 루프 가 내가 기존에 생각하던 것보다 훨씬 빈번한 경로였다는 게 보였다. 기존에는 이걸 "예외 처리" 정도로 취급했는데, 하네스는 이걸 "생성-검증 패턴의 정식 경로" 로 정의하라고 요구했다. 그 결과, 이 경로가 워크플로우의 정식 부분이 됐고, 그 부분의 산출물을 별도 관리하게 됐다.

(b) "범위 밖" 목록의 가치

나는 다른 연구 트랙도 병행 중인데, 하네스 구축 전에는 Claude한테 뭔가 부탁할 때마다 "이건 트랙 A인지 트랙 B인지"를 내가 매번 썼다. 이제는 하네스 트리거 description에 "should NOT trigger" 경계를 명시해놨기 때문에, 다른 트랙 관련 질문을 하면 이 하네스가 알아서 비켜준다. 이게 생각보다 멘탈 코스트를 많이 줄였다.

(c) 주간 보고가 덤으로 정리됐다

마지막 Phase D (서브 에이전트 "주간 보고") 가 앞 Phase 산출물을 그냥 읽어서 정리한다. 주간 보고를 따로 작성하지 않아도, 앞 작업을 하네스 위에서 굴리기만 하면 보고 초안이 자동으로 붙어나온다. 이건 원래 노렸던 기능인데도, 실제로 동작하는 걸 보니 감동이었다.

---

7. 안 좋았던 점 / 주의할 점

공평하게 쓴다.

1. 드래프트 없이는 하네스가 빛이 안 난다. 초반에 대충 "내 워크플로우 이런 거야" 하고 넘기면, 에이전트 정의가 두루뭉술하게 나온다. 결국 드래프트를 제대로 쓰는 데 드는 시간이 하네스 절약 시간의 상당 부분을 잡아먹는다. (그래도 나는 남는다고 본다. 드래프트는 한 번 쓰면 자산이 되니까.)
2. "팀 모드"는 아직 실험적이다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수가 필요하다. 실행 환경에 따라 동작이 살짝씩 다를 수 있다 [MEDIUM — 공식 링크 기반]. 서브 에이전트 모드는 더 안정적인 듯.
3. 자동 스킬 생성은 아직 "초안"이다. Harness가 만든 각 SKILL.md는 사람이 한번 훑어야 한다. 특히 description 필드. 이게 LLM이 쓴 그대로면 트리거 정확도가 떨어질 수 있다.
4. 연구용이라면 "외부 제출/배포 자동화 금지" 룰을 반드시 심어라. 나는 논문 submit, git push, 외부 이메일 발송을 사용자 명시 승인 없이는 절대 수행하지 않도록 CLAUDE.md에 못 박아놨다. 이건 Harness 자체 기능이 아니라 내가 덧붙인 룰이다.

---

8. 정리 — 이게 결국 뭐였나

Harness가 나한테 준 건 두 가지다.

• (도구로서) "내 도메인 설명 → 에이전트 팀 + 스킬" 변환 공정
• (문서로서) 내 연구 워크플로우를 분기/의존성/실패 경로까지 일관되게 기술하는 포맷

개인적인 결론: 반복되는 멀티 스텝 워크플로우가 있고, 그 워크플로우가 매번 같은 실패 패턴을 겪는다면, 하네스 한 번 써볼 만하다. 그게 연구든 콘텐츠 제작이든 소프트웨어 리뷰든.

특히 연구자 관점에서, "내가 매주 뭘 하고 있는지" 를 파일로 굳히는 강제력 이 있다는 게 크다. 논문 1편보다 이 인프라 문서가 미래의 나에게 더 많은 시간을 돌려줄 수도 있겠다, 는 생각.

---

9. 참고 자료

• revfactory/harness: https://github.com/revfactory/harness
• 공식 Harness 100 (10 도메인 × 100 하네스 예시): https://github.com/revfactory/harness-100
• 논문 (저자 self-reported A/B 측정): Hwang, M. (2026). Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality. [MEDIUM — 개인 self-reported 연구]
• Agent Teams 공식 가이드 (Anthropic): https://code.claude.com/docs/en/agent-teams [HIGH]

---

이 글의 기술 도구·수치는 인용 근거와 정확도 라벨([HIGH/MEDIUM/LOW])을 병기했다. 연구 도메인 관련 구체 내용은 의도적으로 블러 처리했다. 이상한 내용이나 잘못 사용하는 것이 있다면 의견부탁합니다...ㅎㅎ