도구에서 동료로

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.

제목 : 하네스 엔지니어링 with 클로드코드
저자 : 황민호
출간 : 한빛미디어, 2026

AI를 사용해 결과를 만들어내는 과정이 더욱 견고해지고 있다. 이제 하나의 AI를 다루는것 보다 여러 AI에 역할을 부여해 모델을 결정론적으로 제어하는 소프트웨어 로직. 즉, 하네스 엔지니어링이라는 개념이 등장했다. 다소 추상적이고 최신의 내용을 소프트웨어 개발 과정에 어떻게 녹이고 활용하는지 이번 책에서 확인해보자.

병목은 능력이 아니라 구조다

AI가 헛다리를 짚으면 우리는 모델을 탓하거나 더 좋은 버전을 기다린다. 그런데 모델을 고정하고 환경만 바꾼 실험 세 개가 나란히 같은 결론에 닿는다. claude-code-harness가 49.5에서 79.3으로 뛰었고, 잔 볼루크의 Hashline과 Terminal Bench 위의 랭체인도 각각 6.7%에서 68.3%로, 순위권 밖에서 Top5로 같은 폭을 따라갔다. 세대 교체급 향상을 모델은 손도 안 대고 얻은 셈이다. 저자의 결론은 단순하다. 병목은 능력이 아니라 구조다. 답은 모델 안이 아니라 ‘모델 바깥’에 있다.

왜 혼자서는 안 되는가. 단일 에이전트는 계획하고 코딩하고 검증하고 스스로 고치는 네 단계를 같은 모델, 같은 컨텍스트, 같은 가정으로 한 박스 안에서 처리한다. 과제에는 절차가 필요한데, 그 절차를 한 박스가 다 떠안는 데서 누락이 시작된다. 계획할 때 놓친 가정을 검증할 때도 똑같이 놓친다. 자기 출력물을 자기가 검토하는 건 혼자 쓴 PR을 혼자 머지하는 구조다. 리플릿 사건의 원인도 ‘단일 에이전트는 자신의 실수를 잘 보지 못한다’는 한 줄이었다. 터미널에서 같은 파일을 열 번 고치고 같은 grep을 반복하다 컨텍스트가 차서 처음부터 다시 시작하던 경험, 규모만 다를 뿐 같은 패턴이다.

하네스는 모델을 둘러싼 가장자리다

그래서 하네스다. 저자는 이걸 모델을 둘러싼 가장자리, 즉 가중치는 건드리지 않고 그 주변의 권한과 도구, 검증, 상태, 관측을 결정론으로 설계하는 일이라 정의한다. 파인튜닝도 RLHF도 아니다. 소프트웨어 공학사가 어셈블리에서 고급 언어로, GC로, 클라우드로 위임의 사다리를 올라왔는데, 유독 AI 에이전트 칸만 확률론적 시스템에 위임한다. 엄격함은 사라지는 게 아니라 자리를 옮긴다. 안쪽은 확률론, 가장자리는 결정론. 프롬프트가 말로 설득한다면 하네스는 구조로 강제한다.

구조로 강제한다는 말은 빈 폴더에서 곧장 형태를 얻는다. 파일 다섯 개, 에이전트 둘에 스킬 하나, 규칙 하나, 워크스페이스 하나면 author와 reviewer로 나뉜 가장 작은 생성-검증 팀이 선다. 핵심은 둘이 대화나 메모리가 아니라 _workspace/ 공유 파일로만 소통한다는 점이다. 그래서 중간 산출물이 남고 사람이 언제든 끼어든다. reviewer.md를 .bak으로 바꾸면 워크플로가 그 자리에서 끊긴다. 파일이 없으면 존재하지 않는다는 게 그대로 드러난다. 한 명이 두 번 보는 것보다 두 명이 한 번씩 보는 게 낫다는 게 전부다.

누가, 어떻게, 언제 누구와

구성요소는 셋으로 갈린다. 에이전트는 ‘누가’, 스킬은 ‘어떻게’, 오케스트레이터는 ‘언제 누구와’. 새 지식이 역할이나 판단 기준인지, 절차나 워크플로인지, 팀 구성과 실행 순서인지만 물으면 어디로 갈지 거의 자동으로 정해진다. 책임 매트릭스는 그 판단을 외우지 않아도 되게 만든 표다. 판단과 절차의 주권은 끝까지 에이전트와 스킬에 남는다.

에이전트 정의 파일을 저자는 설정이 아니라 역할 계약서라고 부른다. 설정은 값을 저장하지만 계약서는 약속을 저장한다. 호출자에게 보이는 프론트매터 다섯 필드와 그 아래 일곱 섹션, 핵심 역할과 작업 원칙, 입출력 프로토콜, 팀 통신 프로토콜, 에러 핸들링, 협업, 품질 자체 검증이 한 파일 안에서 담당과 판단 기준, 소통 방식을 모두 적어 둔다. 파일에 없으면 그 역할은 존재하지 않고, 프롬프트 파라미터에 역할을 직접 박는 길은 아예 막아 둔다. 그렇게 박으면 다음 날 기억을 잃고 출근하는 직원처럼 세션과 함께 사라지지만, .claude/agents/{name}.md로 적어 두면 어제도 내일도 같은 동료가 된다.

---
name: commit-msg-author
description: "스테이지된 변경(git diff --cached)과 최근 커밋 로그를 읽고 Conventional Commits 형식의 커밋 메시지 초안을 작성한다. '커밋 메시지', 'commit message' 같은 자연어 요청 시 사용."
model: sonnet
tools: Bash, Read, Write
---

하는 일을 한둘로 좁혀 적는 건 하지 않는 일의 경계까지 긋는 일이라, 범위가 흐리면 한 팀에 같은 담당이 둘 생긴다. 출력 전 스스로 점검표를 거치면 뒤 에이전트가 잡기 전에 걸러진다. model과 tools 두 필드는 특히 거버넌스 장치다. 검토자에게서 Write를 빼면 그 도구가 아예 안 보이니 잘못 해석해도 손댈 수 없다. ‘Write 금지’라 적는 건 프롬프트일 뿐, 진짜 가드레일은 자연어에서 파일로, 다시 격리로 세 층을 쌓아야 선다. Vercel이 도구를 15개에서 2개로 줄여 정확도가 80에서 100으로 오른 사례가 이를 받친다. 거꾸로 무엇이든 다 하는 general-assistant식 에이전트는 오케스트레이터가 늘 먼저 불려 전문성 없는 영역까지 답을 내놓고, 단일 에이전트가 제 실수를 못 보던 문제를 되살린다.

스킬은 본문 품질이 아니라 호출 여부에서 먼저 죽는다. 클로드는 본문을 읽기 전에 name과 description만 보고 열지 말지 정하니, 잘 쓴 본문도 모호한 한 줄에 막히면 영영 안 읽힌다. 언제 쓰는지뿐 아니라 언제는 쓰지 말아야 하는지까지 description에 적어야 오발과 미발을 동시에 줄인다.

컨텍스트는 내 것이 아니라 공공재라는 관점도 같은 자리에서 나온다. 스킬 서른 개가 각자 500자씩 먹으면 매 요청마다 15,000자가 고정비로 빠진다. Progressive Disclosure는 파일 분리 관례가 아니라 한정 자원을 여럿이 나눠 쓰는 환경의 설계 원칙이다. ‘ALWAYS pdfplumber, NEVER PyPDF2’ 같은 규칙은 정당한 엣지 케이스에서 과잉 우회를 낳지만, 이유를 적어 주면 클로드가 스스로 판단한다. 인간 매뉴얼은 자의적 판단을 배제하려 규칙을 쓰고, LLM 지시서는 반대로 엣지 케이스에서도 생각을 이어가도록 이유를 심는다.

오케스트레이터는 우체국이 아니다

리더가 모든 메시지를 중개하는 순간 팬아웃은 조용히 순차 파이프라인으로 퇴행한다. 리더가 우체국이 되면 팀원들은 서로 모르는 채 각자 방에 갇힌다. ‘리더를 거치지 않는다’는 원칙의 본질은 성능이 아니라 병렬성 보존이고, 리더는 중계자에서 통합자이자 결정자로 물러앉고 팀원은 직접 대화하는 피어로 올라선다. 세 프리미티브 TeamCreate·TaskCreate·SendMessage가 이 협업을 결정론적 로직으로 고정한다. 작고 즉시 쓸 정보는 메시지, 소유자와 의존성이 있는 일은 태스크, 큰 산출물은 파일. 취향이 아니라 데이터 성질로 갈린다.

병목이 사라지면 팀은 빠른 만큼 잘못된 방향으로도 빠르게 간다. 그래서 리더에게 관측과 경계면이라는 새 책임이 붙는다. 같은 파일을 N번 고치는 팀원에게 다른 접근을 주입하고, 양쪽 명세를 동시에 대조해 인터페이스가 어긋나는지 본다. 한쪽만 읽으면 늘 ‘이쪽은 맞다’가 되니까. 자율적인 팀은 스스로 멈출 이유를 잘 못 찾으니, 멈추게 하는 게 오케스트레이터의 몫이다. 292개 에이전트가 2분 만에 36.8GB를 먹은 사건 뒤로 권장 팀 크기는 3~5명, 일곱을 넘으면 Phase 단위로 갈아 끼운다.

팀에는 모양이 있다

패턴은 메뉴에서 고르는 게 아니라 문제 구조의 번역물이다. 파이프라인의 순서는 더 나은 순서를 고르는 문제가 아니라 논리적으로 가능한 유일한 순서다. 보안 감사를 정적 분석 앞에 두면 깨진 문법 위에서 취약점이 의사코드 수준으로만 맴돌다 재실행 비용을 문다. 순서가 곧 문제의 모양이다.

닮은 패턴일수록 결정적 차이 한 줄이 전부다. 팬아웃·팬인은 같은 입력을 여러 관점이 동시에 보되, 단순 병렬과 갈리는 지점은 팀원끼리 실시간으로 교차 검증한다는 데 있다. 팬아웃은 N명 전원이 일하지만 전문가 풀은 라우터가 고른 한 명만 일하니, 사활은 라우터의 분류 정확도다. 오분류는 엉뚱한 영역에 엉뚱한 변경을 남겨 되돌리기 어려우니, 애매하면 복수 라벨링 후 사람에게 넘기는 게 표준 방어책이다. 또 팬아웃은 리더가 일을 고정 분배하지만 감독자는 워커가 큐에서 스스로 가져간다. 계층적 위임은 2단계를 절대 넘으면 안 된다. 3단계는 고요 속의 외침처럼 의도가 유실되고 지연이 폭발한다.

실전의 기본값은 단일 패턴이 아니라 복합이다. Phase마다 다른 패턴을 쓰고 그 경계를 _workspace/ 파일이 잇는다. 앞에서 손으로 세운 author와 reviewer 팀도 사실 이 여섯 중 하나, 생성-검증 패턴이었다. 그리고 이 모든 게 Saga와 CQRS, work-stealing 같은 분산 시스템 패턴의 재등장이다. AI 협업이 신비한 새 영역이 아니라 수십 년 쌓인 엔지니어링 위에 서 있다는 뜻이다.

그 정신은 하네스를 짜는 과정 자체에도 적용된다. 저자는 하네스 제작을 6단계 파이프라인 메타스킬로 추상화하는데, 이 메타스킬이 자기가 권하는 규칙을 자기가 지킨다. 본문 500줄 이내, references 분리, description 3요소. wc와 ls와 head 세 줄로 30초면 신뢰할 만한지 가늠된다. 자기 규칙을 못 지키는 스킬은 그 자리에서 걸러진다.

18개월짜리 마이그레이션을 6주로

뒷부분은 코드 리뷰, 풀스택 구현, 레거시 마이그레이션, 디버깅 RCA 네 팀을 실전으로 풀어낸다. 네 사례를 관통하는 장치가 일관된다. Edit 권한을 단 한 명에게만 주는 권한 분리, batches.json이나 reproduction.sh의 exit 코드 같은 파일 기반 상태 머신, 최대 3회 같은 종료 조건. 전부 확률적 모델을 소프트웨어 로직으로 감싸는 하네스다. boundary-verifier를 구현 단계에 상주시켜 엔드포인트가 완성될 때마다 즉시 대조하는, QA를 뒤로 미루지 않는 설계도 눈에 띈다.

정점은 레거시 마이그레이션이다. 에어비앤비가 React 테스트 파일 약 3,500개를 Enzyme에서 React Testing Library로 옮기는 데 수작업이면 18개월 걸릴 일을 6주에 끝냈고 97%를 자동화했다. 비결은 더 좋은 프롬프트가 아니라, 에러와 최신 파일 상태를 다시 모델에 투입하는 피드백 루프, 그리고 변환에서 검증, 재시도로 이어지는 상태 기계 파이프라인이었다. 마이그레이션은 큰 리팩터링 하나가 아니라 작은 변환이 수천 번 반복되는 일이라, 복잡도 상위 5% 파일이 전체 시간의 절반을 차지한다. 고정 팬아웃이면 그 무거운 파일이 한 워커에 몰려 나머지가 놀지만, 앞서 본 감독자 패턴은 워커가 큐에서 다음 배치를 스스로 가져가 부하를 고르게 편다.

읽는 비용이 청구서를 채운다

협업 설계를 다 갖춰도 비용 감각이 빠지면 반쪽이다. 저자가 던지는 숫자가 셈을 다시 하게 만든다. 같은 모델에 같은 인원인데 한 팀은 월 1,800달러를 쓰고 다른 팀은 1만 2천 달러를 쓴다. 6.7배 차이가 전적으로 하네스 설계에서 갈린다. 직관과 어긋나는 건, 비용의 99%가 AI가 ‘쓰는’ 출력이 아니라 ‘읽는’ 입력에서 나온다는 점이다. 에이전트 루프는 매 턴 과거 대화 전체를 다시 실어 보내니까, 세션이 길어질수록 호출 한 번이 점점 무거워진다. 택시가 한 걸음 갈 때마다 출발지로 돌아가 총거리를 다시 재는 셈이라는 비유가 그 구조를 정확히 짚는다.

그래서 줄일 레버는 입력 쪽에 있고, 그중 으뜸이 KV 캐시 히트율이다. 같은 토큰도 캐시에 얹히면 단가가 열 배 싸진다. 캐시는 앞쪽 머리말이 한 바이트라도 달라지면 그 뒤가 통째로 깨지는 접두사 방식이라, CLAUDE.md를 자주 고치거나 시스템 프롬프트에 오늘 날짜 한 줄을 박는 순간 돈이 샌다. 늘 똑같은 머리말을 유지하는 게 곧 비용 설계인 셈이다. 한 발 더 나아가, 기계가 확인할 수 있는 규칙은 토큰을 한 푼도 안 쓰고 준수율 100%인 훅으로 넘기고 판단이 필요한 것만 에이전트에 맡기라고 한다. 같은 규칙 여섯 개를 자연어로 부탁하면 다 지킬 확률이 37%인데, 그중 다섯을 훅으로 옮기면 비용은 내려가고 준수율은 올라간다.

이 대목 끝에 저자가 붙이는 관찰이 책 전체를 한 번 더 받친다. 서로 코드를 공유한 적 없는 Stripe와 클로드 코드가 계층 수만 다를 뿐 똑같은 일곱 가지 관심사로 수렴했다는 것이다. 격리, 빠른 피드백, 우아한 실패, 확률과 결정론의 교대 같은 문제는 누가 풀든 비슷한 구조를 요구한다. 하네스가 한철 유행이 아니라 기존 공학의 연장선이라는 주장을, 이번엔 비용의 언어로 다시 확인해주는 셈이다.