Claude Code 하네스란? revfactory/harness와 내 allhaness 비교

Posted on by

저는 처음에 “하네스”라는 단어를 보면서도, 사실 한동안 같은 층으로 착각했습니다. Claude Code 생태계에서 흔히 말하는 하네스가 에이전트와 스킬을 잘 만들어주는 생성기인지, 아니면 프로젝트가 굴러가게 만드는 운영 장치인지 문맥이 바뀌면 의미가 통하지 않거든요. 이번 세션에서 제가 다시 정리한 건 단순합니다. 같은 철자로 불리지만, 목적과 산출물이 다릅니다.

revfactory/harness는 팀 설계와 스킬 생성에 강하고, allhaness(standard-harness-lite)는 문서와 런타임을 붙여 운영 판단을 남기는 쪽에 가깝습니다. 둘 중 하나가 다른 하나를 대체하지 않습니다.

저는 요즘은 이름을 먼저 고르지 않고, 표의 열 두 개만 골라 적습니다. 에이전트 위치와 상태 판정입니다. 여기서 갈리면 나머지 논의가 훨씬 가벼워집니다.

지금 결론

비교의 핵심은 생성기 하네스와 운영 하네스를 나누는 일입니다. revfactory/harness 쪽은 도메인별 에이전트 팀 설계와 에이전트 정의, 스킬 자동 생성까지 이어지는 메타 스킬 플러그인에 가깝고, 워크플로가 여러 Phase로 정리되어 Marketplace 설치 후 .claude/agents/, .claude/skills/ 같은 산출물을 자동으로 채우는 방향입니다. 반면 제가 쓰는 allhaness 계열은 프로젝트 폴더 안에 docs/, agent-project/agents/, harness/state/, logs/를 두고 harness_ctl.sh로 bootstrap, status, lead, capture, loop를 돌리는, 문서와 런타임이 같이 움직이는 운영 허브에 가깝습니다.

둘 다 하네스라고 부르지만, 하나는 주로 만들기와 구조화에, 다른 하나는 주로 굴리기와 기록에 무게가 실립니다. 그래서 어느 게 더 좋냐보다 지금 내 병목이 생성인지 운영인지가 먼저입니다. 생성이 병목이면 revfactory 쪽을 연구할 가치가 있고, 운영이 병목이면 allhaness 같은 레일(Idempotency에서 CPS, Design, Evaluation, Maintenance로 이어지는 흐름)이 더 직접적으로 닿습니다.

시간과 리뷰 부담 측면에서도 갈립니다. revfactory는 산출물이 많아질수록 생성 결과를 사람이 훑고 합치는 비용이 커질 수 있습니다. allhaness는 반대로 런타임 루프와 로그 정책을 유지하려면 운영 습관과 문서 규율을 지속적으로 갱신해야 합니다. 둘 다 설치하고 끝 타입은 아닙니다.

핵심 비교 (revfactory vs allhaness)

항목 revfactory/harness allhaness (standard-harness-lite)
한 줄 정의 메타 스킬 플러그인 — 팀 설계+스킬 자동 생성 문서+런타임 결합형 운영 하네스 스타터
설치 Marketplace/글로벌 스킬 복사 폴더 복제 → bootstrap
산출물 .claude/agents/, .claude/skills/ docs/, agent-project/, harness/, logs/
에이전트 위치 전역 .claude/ 프로젝트 로컬
상태 판정 없음 (생성 후 수동) harness_ctl.sh status/lead/loop
운영 단계 지원 X O (Status→Incident→Decision→Maintenance)
의존성 Agent Teams 실험 플래그 없음 (bash+python)
복수 LLM 대응 X O (첫 말 계약 + 문서 규율)

revfactory/harness는 공개 정보 기준으로 6 Phase 워크플로, Marketplace 설치, Agent Teams 실험 기능 필요 같은 전제가 붙습니다. 또한 아키텍처 패턴으로 Pipeline, Fan-out과 Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation 같은 협업 구조를 명시적으로 다루는 틀이 있습니다. 실행 모드도 Agent Teams(2명 이상 협업, 기본)와 Subagents(단발)로 나뉩니다.

allhaness 쪽은 standard-harness가 공장이면 lite는 매일 들고 다니는 작업 가방처럼 가볍게 들고 다니면서도 상태 판정과 판단 철학을 남기려는 스타터에 가깝습니다. 가방 비유 자체가 본질은 아니고, 그 안의 운영 레일이 본질에 가깝습니다. Capture Policy도 raw인 events.jsonl과 distilled인 session_log.md로 남겨서, 나중에 그때 왜 그렇게 판단했는지를 추적할 수 있게 만드는 쪽에 초점이 있습니다.

표를 읽을 때 저는 설치와 산출물 열부터 보지 않고, 에이전트 위치와 상태 판정 열을 먼저 봅니다. 전역 .claude/에 쌓이는 구조는 공유와 재사용에 강하지만, 프로젝트 단위 책임을 분리하기 어려울 수 있습니다. 반대로 프로젝트 로컬은 이동과 아카이브가 쉬운 대신, 팀 전체 표준을 강제하기엔 또 다른 합의가 필요합니다.

의존성 열도 놓치기 쉽습니다. Agent Teams 실험 플래그는 환경에 따라 켜고 끄는 비용이 생깁니다. bash와 python만으로 굴리는 쪽은 의존성은 단순해 보이지만, 대신 운영 규약을 문서로 유지할 책임이 사람에게 남습니다.

왜 같은 단어가 다른 층이 되었나

Claude Code 주변에서 하네스라는 말은 종종 잘 굴러가게 만든 실행 계층으로 정의됩니다. 제 볼트 운영 가이드에서도 하네스는 프롬프트만이 아니라 health check, 재시작, 폴백, 상태 저장까지 포함한 실행체로 설명합니다. 그런데 revfactory/harness는 그 정의와 겹치면서도, 동시에 메타 스킬이 팀과 스킬을 생성한다는 색이 강합니다. 이름은 비슷한데, 첫인상의 중심축이 다릅니다.

그래서 회의에서 같은 단어로 말해도 서로 다른 그림을 그리는 경우가 생깁니다. 한쪽은 폴더가 채워지는 속도를 말하고, 다른 쪽은 장애 대응 시간을 말합니다. 표로만 잡아도 대화가 정렬되는 경우가 많았습니다.

생성기 하네스는 반복되는 설계 작업을 자동화하는 쪽으로 이득이 큽니다. 도메인 템플릿이 쌓일수록 시작 속도가 빨라지고, 팀 단위 에이전트 구성을 표준화하기 좋습니다. 운영 하네스는 실행 중에 무슨 일이 일어났는지를 남기고, 상태를 판정하고, 사건을 처리하고, 유지보수로 이어지게 만드는 쪽으로 이득이 큽니다. 둘 다 필요하지만, 같은 폴더 한 군데에 억지로 합치면 책임이 뭉개질 수 있습니다.

또 하나의 이유는 실패 모양이 다르다는 점입니다. 생성기 쪽 실패는 보통 중복과 네이밍, 합치기 충돌처럼 파일이 늘어난 뒤에 드러납니다. 운영 쪽 실패는 로그는 있는데 해석이 안 되거나, 상태는 초록인데 현장은 붉은색인 식으로 늦게 드러납니다. 그래서 예방 체크도 서로 다릅니다.

저는 개인 FDE식으로 움직이는 허브를 프로젝트 안에 두는 편이 더 편했습니다. 전역 .claude/에 에이전트가 많아질수록 이 프로젝트 전용 규칙과 공통 규칙이 섞여서 디버깅이 느려지는 느낌이 들 때가 있거든요. 반대로 revfactory 계열은 팀 템플릿을 빠르게 뽑아내고 실험할 때 매력적입니다. 특히 여섯 가지 아키텍처 패턴을 기준으로 협업 구조를 설계할 때, 말로만 흐르던 역할 분담을 파일로 고정하는 데 도움이 됩니다.

같은 주간에 두 축을 동시에 바꾸면 회고가 어려워집니다. 저는 한 번에 한 축만 바꾸고, 변경 이유를 session_log.md 한 줄이라도 남기는 식으로 속도를 조절했습니다.

정리하면, revfactory/harness는 만들기와 표준화에 강하고, allhaness는 돌리기와 기록에 강합니다. 저는 둘을 경쟁 구도로 보기보다, 파이프라인의 앞단과 뒷단으로 나누는 편이 운영 난이도가 낮았습니다.

공개된 규모감만 놓고 보면 revfactory 쪽은 harness-100으로 10개 도메인, 100개 하네스, EN/KO 200개 패키지, 1,808개 MD 파일로 구성된 대형 생태가 있습니다(GitHub revfactory/harness-100). GitHub 스타 수는 조회 시점 기준 약 346개입니다. 저자가 공개한 A/B 연구에서는 품질 점수 49.5→79.3(+60%), 15/15 승, 분산 약 32% 감소라는 수치가 소개됩니다(revfactory/claude-code-harness). 다만 이 수치는 독립 재현 검증이 아닌 저자 자체 연구라는 점은 반드시 짚고 넘어가야 합니다.

실수 TOP 5

  1. 하네스를 자동 배포 장치로 오해
    둘 다 자동을 연상시키지만, 기본적으로는 개발자의 판단과 리뷰를 전제로 합니다. 특히 생성기 하네스는 산출물이 많아질수록 리뷰 부담이 누적됩니다.

  2. 전역 에이전트만 늘리고 운영 레일이 없음
    에이전트 파일이 많아지면 누가 최종 책임인지가 흐려집니다. Status→Incident→Decision→Maintenance로 이어지는 운영 단계가 없으면, 생성 속도만 빨라지고 사후 정리는 늘 밀립니다.

  3. 실험 플래그 의존을 간과
    revfactory는 Agent Teams 실험 기능이 필요합니다. 조직 정책이나 클라이언트 버전에 막히면 “문서상으로는 되는데 내 터미널에서는 안 됨”이 나올 수 있습니다.

  4. 로그를 raw만 쌓고 distilled를 안 만듦
    이벤트 로그만 쌓이면 나중에 검색은 되지만 결정 근거가 읽기 어렵습니다. 반대로 요약만 남기면 디버깅에 필요한 단서가 사라집니다.

  5. 복수 LLM 대응을 기술만으로 해결하려 함
    첫 말 계약과 문서 규율이 없으면 모델만 바뀌고 혼선은 그대로입니다. Marketplace 설치가 쉬워 보여도, 생성물이 전역 .claude/에 쌓이는 정책이 팀 규칙과 맞는지는 별개입니다.

언제 이 선택이 맞고, 언제 아닌가

revfactory/harness가 맞는 쪽 에이전트 팀 템플릿을 빠르게 뽑아내고 실험해야 할 때, Pipeline이나 Producer-Reviewer 같은 협업 패턴을 파일로 고정하고 싶을 때, Marketplace 기반으로 팀원과 동일한 생성 워크플로를 공유하고 싶을 때입니다. 신규 도메인을 여러 개 열어서 같은 패턴으로 에이전트 묶음을 복제해야 할 때도 해당합니다.

revfactory/harness가 덜 맞는 쪽 이미 운영 중인 프로젝트에서 상태 판정과 사건 처리, 유지보수 기록이 더 급할 때는 굳이 생성기부터 확장하지 않아도 됩니다. 실험 플래그나 조직 정책 때문에 Agent Teams 전제가 불안정할 때도 부담이 큽니다.

allhaness(standard-harness-lite)가 맞는 쪽 프로젝트 로컬에 오케스트레이터를 두고 문서와 런타임을 같이 움직이게 하고 싶을 때, harness_ctl.sh로 bootstrap과 status, lead, capture, loop 같은 운영 루프를 명시하고 싶을 때, 빌드 단계와 운영 단계를 같은 레일로 묶고 싶을 때입니다. 장애가 났을 때 재현에 필요한 정보가 채팅 로그에만 남는 게 싫을 때도 해당합니다.

allhaness가 덜 맞는 쪽 에이전트 정의를 대량 생성이 1순위이고 Marketplace 기반 메타 스킬이 더 빠를 때, 팀 표준을 전역 .claude/에 통째로 올리는 정책이 이미 고정돼 있을 때입니다.

비용 측면에서, revfactory는 생성과 합치기에 시간이 들고, allhaness는 루프와 문서 갱신에 시간이 듭니다. 둘 다 한 번 세팅하고 방치와는 거리가 있습니다.

저는 이번 주에 반복해서 설명한 문장을 메모해 두는 편입니다. 그 문장이 팀 구조와 스킬 정의 쪽이면 생성기 축을, 상태와 결정과 롤백 쪽이면 운영 축을 우선했습니다. 둘 다 필요해 보일 때는 범위를 나눠서 한 주에 한 축만 건드리는 식으로 부담을 줄였습니다.

FAQ

1. Claude Code에서 하네스는 공식 용어인가요? 생태계에서 관행적으로 쓰이는 말에 가깝고, 프로젝트마다 정의가 조금씩 다릅니다. 무엇을 하네스라 부를지를 먼저 합의하는 게 안전합니다.

2. revfactory/harness를 쓰면 운영 하네스가 자동으로 생기나요? 운영 단계 지원은 기본 전제로 깔려 있지 않습니다. 생성 후 운영은 별도 설계가 필요합니다.

3. allhaness는 Claude Code 전용인가요? 문서 규율과 런타임 스크립트를 중심에 두는 편이라, 멀티 런타임 IDE 정책처럼 공통 .claude/와 프로젝트 로컬을 같이 쓰는 환경에서도 조정할 여지가 있습니다.

4. Agent Teams 실험 기능이 꺼져 있으면 revfactory는 완전히 쓸모 없나요? 항상 그렇진 않지만, 협업 실행 모드 전제가 걸리는 부분은 제약으로 작동할 수 있습니다. Subagents 중심으로 범위를 줄이거나, 생성만 쓰고 실행은 사람이 나누는 식으로 우회합니다.

5. harness-100 같은 대형 패키지는 바로 도입해도 되나요? 파일 수가 많아질수록 검색과 중복, 네이밍 충돌 리스크가 커집니다. 작은 도메인부터 샘플링해서 팀 규칙과 합치는 편이 부담이 적습니다.

6. allhaness의 Capture Policy는 왜 raw와 distilled를 둘 다 쓰나요? raw는 사실 재구성에 강하고, distilled는 회고와 전달에 강합니다. 둘 중 하나만 고르면 나중에 후회하는 경우가 많았습니다.

7. 둘 다 쓰는 구성은 현실적인가요? 현실적입니다. 다만 전역 생성과 프로젝트 운영의 경계를 명확히 해야 합니다. 같은 파일을 두 도구가 동시에 덮어쓰면 실패 포인트가 됩니다.

8. 복수 LLM 대응은 무엇을 의미하나요? 모델을 바꿔도 문서에 남는 계약(첫 말, 출력 형식, 책임 분리)이 있어야 운영이 유지됩니다. 기술 스위치만으로 해결되지 않습니다.

참고 자료

함께 보면 좋은 글