모델보다 하네스가 제품을 결정한다 — 하네스 엔지니어링 완전 정리 (feat. Claude Code 분석)

AI 에이전트를 만들다 보면 이런 경험을 하게 됩니다.

"GPT-4 쓰는데 왜 Claude Code보다 못하지? 모델이 비슷한데 결과가 왜 이렇게 다르지?"

모델 성능 차이가 아니에요. 하네스 엔지니어링 수준 차이입니다. 이번 글에서는 하네스 엔지니어링이 뭔지, 어떤 구성요소로 이루어지는지, 그리고 Claude Code가 이걸 어떻게 구현했는지 분석해 드릴게요.

---

하네스 엔지니어링이란?

AI 에이전트가 "실험실에서 잘 되네" 수준을 넘어서 실제 프로덕션에서 안정적으로 동작하게 만드는 설계와 구축 작업 전체예요.

모델은 이미 충분히 똑똑해요. GPT-4, Claude, Gemini 다 비슷한 수준이에요. 근데 어떤 제품은 잘 되고 어떤 제품은 망하는 이유가 뭐냐 — 하네스 엔지니어링 수준 차이입니다.

실제 사례를 보면 명확해요. Vercel이 에이전트 툴을 80% 줄였더니 오히려 성능이 올라갔어요. Manus는 같은 모델로 하네스를 5번 갈아엎었더니 결과가 완전히 달라졌고요. 모델을 바꾼 게 아니라 하네스를 바꾼 거예요.

---

하네스 엔지니어링의 6가지 핵심 구성요소

1. 컨텍스트 관리

에이전트의 가장 큰 약점이 컨텍스트 창 한계예요. 작업이 길어지면 앞에서 한 내용을 까먹어요.

하네스 엔지니어링에서 이걸 해결하는 방법은 네 가지입니다.

압축(Compaction) — 오래된 내용을 요약해서 컨텍스트를 절약해요. 외부 메모리 — 중요한 정보는 DB에 따로 저장해두고 필요할 때 불러요. 체크포인트 — 작업 중간중간 상태를 저장해서 중단돼도 이어서 할 수 있게 만들어요. 초기화 프롬프트 설계 — 새 컨텍스트 시작할 때 이전 맥락을 잘 전달하는 구조를 만들어요.

2. 툴 설계

에이전트한테 툴을 얼마나, 어떻게 줄지 설계하는 게 엄청 중요해요.

흔한 오해가 "툴 많이 줄수록 에이전트가 더 잘하겠지"인데, 현실은 반대예요. 툴이 많으면 에이전트가 뭘 써야 할지 헷갈려서 오히려 성능이 떨어지고 무한루프가 발생해요.

핵심 원칙은 이렇습니다. 툴은 최소한으로 유지하되 꼭 필요한 건 다 있게 하고, 각 툴의 역할을 명확하게 정의하고, 위험한 툴(DB 삭제, 이메일 발송 등)은 별도 승인 게이트를 적용해요.

3. Human-in-the-Loop 설계

에이전트가 모든 걸 혼자 하게 두면 언젠가 반드시 사고가 납니다. 어디서 사람이 개입해야 하는지 설계하는 게 하네스 엔지니어링의 핵심이에요.

승인 게이트 — "DB 전체 삭제할게요" 같은 건 무조건 사람 확인을 받아요. 신뢰도 임계값 — 에이전트가 확신 못 하면 자동으로 사람한테 넘겨요. 중간 리뷰 포인트 — 긴 작업은 중간에 사람이 방향을 확인하는 구간을 설계해요. 롤백 메커니즘 — 잘못됐을 때 되돌릴 수 있는 구조를 만들어요.

4. 멀티에이전트 조율

복잡한 작업은 하나의 에이전트로 못 해요. 여러 에이전트를 어떻게 나누고 조율할지 설계해야 합니다.

작업 분해, 에이전트 간 통신 프로토콜, 의존성 관리(A가 끝나야 B가 시작), 에이전트들이 서로 다른 결론을 낼 때의 충돌 해결 로직이 여기 포함돼요.

5. 실패 모드 설계

하네스 엔지니어링에서 가장 많은 시간을 쓰는 부분이에요. 잘 되는 경우를 설계하는 게 아니라 망하는 경우를 전부 예상하고 대비하는 것이에요.

주요 실패 패턴은 다섯 가지예요.

• 무한루프 — 에이전트가 같은 작업을 반복
• 목표 표류 — 작업하다가 원래 목표에서 벗어남
• 과도한 확신 — 틀렸는데 맞다고 우기면서 계속 진행
• 조기 완료 — 덜 됐는데 끝났다고 선언
• 컨텍스트 손실 — 긴 작업에서 앞 내용을 까먹고 처음부터 다시

각 실패 패턴마다 감지 로직과 복구 로직을 설계하는 게 하네스 엔지니어링이에요.

6. 관찰가능성 (Observability)

에이전트가 뭘 하는지 볼 수 없으면 고칠 수가 없어요.

툴 호출 로깅, 의사결정 추적(왜 이 행동을 선택했는지 추론 과정 기록), 작업 완료율·평균 소요 시간·실패 지점 같은 성능 지표, 토큰 사용량과 API 호출 횟수 비용 추적이 여기 포함돼요.

---

Claude Code로 보는 하네스 엔지니어링 실전

Claude Code를 본질만 뽑으면 이렇게 됩니다.

하나의 에이전트 루프
+ 툴 (bash, read, write, edit, glob, grep, browser...)
+ 온디맨드 스킬 로딩
+ 컨텍스트 압축
+ 서브에이전트 스폰
+ 의존성 그래프가 있는 태스크 시스템
+ 비동기 메일박스로 팀 조율
+ 병렬 실행을 위한 worktree 격리
+ 권한 거버넌스

각 구성요소별로 어떻게 구현했는지 뜯어볼게요.

 

컨텍스트 관리

컨텍스트 한계에 가까워지면 자동으로 오래된 툴 출력을 지우고, 필요하면 대화를 요약해요. 여기서 중요한 게 세 가지예요.

CLAUDE.md는 프로젝트 규칙과 컨벤션을 저장해두면 매 세션마다 자동으로 로드돼요. 대화 기록에 의존하는 게 아니라 파일로 영속적으로 관리하는 거예요. Auto memory는 작업하면서 Claude가 자동으로 학습한 내용을 저장하고, 매 세션 시작 시 MEMORY.md 첫 200줄이 로드돼요. /compact 명령으로 수동 압축도 가능하고 /compact focus on API changes처럼 포커스를 지정할 수도 있어요.

 

툴 설계

Vercel이 툴을 80% 줄였더니 성능이 오른 것처럼, Claude Code도 툴을 무한정 주지 않아요. 스킬은 온디맨드 로드 방식이에요. 세션 시작 시 스킬 설명만 보이고, 실제 내용은 사용할 때만 로드됩니다. MCP 서버는 모든 요청에 툴 정의를 추가하기 때문에 서버 몇 개만 있어도 작업 시작 전에 컨텍스트를 많이 잡아먹거든요.

 

Human-in-the-Loop

Plan mode가 대표적인 승인 게이트예요. 실행 전에 계획을 먼저 보여주고 사람이 확인하면 진행해요. 파일시스템 접근도 하네스가 통제해요. 모델이 수행하는 파일시스템 작업을 정확히 제어하는 구조입니다.

 

실패 모드 대응

에이전트의 실패 패턴이 두 가지로 나타났어요. 한 번에 너무 많이 하려고 시도하는 것(앱을 원샷으로 만들려 함)과 작업이 완료되지 않았는데 완료됐다고 선언하는 조기 완료예요.

Claude Code가 이걸 해결한 방법은 초기화 에이전트가 사용자의 초기 프롬프트를 확장한 포괄적인 기능 요구사항 파일을 작성하게 하는 거예요. Claude.ai 클론 예시에서는 200개 이상의 기능이 나왔고, 이것들이 전부 "failing" 상태로 표시돼서 이후 코딩 에이전트들이 완전한 기능이 어떤 것인지 명확한 기준을 갖게 됩니다.

 

멀티에이전트

tmux로 여러 Claude Code 인스턴스를 Manager/Worker 역할로 나눠서 오케스트레이션하는 것도 가능해요. 코드베이스를 능동적으로 탐색하고, 병렬 작업을 위해 서브에이전트를 스폰하고, MCP를 통해 외부 툴과 통합하는 구조입니다.

---

왜 하네스가 진짜 해자(Moat)인가

모델은 이미 누구나 API로 쓸 수 있어요. OpenAI, Anthropic, Google 다 공개돼 있어요. 모델은 상품(commodity)이에요.

근데 하네스는 회사마다 달라요. 수개월에서 수년의 실전 경험이 쌓여야 제대로 된 하네스가 나와요.

"모델을 fine-tune하는 건 몇 주면 돼. 프로덕션 수준의 하네스를 만드는 건 몇 달~몇 년이야. 하네스가 진짜 해자다."

Claude Code가 2025년 한 해에만 176번 업데이트된 게 이걸 보여줘요. 모델을 176번 바꾼 게 아니라 하네스를 176번 다듬은 거예요.

---

마무리

Claude Code가 잘 되는 이유는 어떤 단일한 트릭 때문이 아니에요. 오히려 하지 않는 것 때문이에요. 에이전트인 척 하지 않고, 경직된 워크플로우를 강요하지 않고, 정교한 의사결정 트리로 모델을 간섭하지 않아요. 툴, 지식, 컨텍스트 관리, 권한 경계를 제공하고 그냥 비켜줍니다.

AI 에이전트를 만들 때 모델 선택에 시간을 쏟기 전에, 하네스를 어떻게 설계할지 먼저 고민하세요. 그게 제품 품질을 결정합니다. 😄

---