혼자 코딩하고 혼자 Merge하는 AI의 폭주를 막다

kycasd***

2026-06-30

하네스 엔지니어링 with 클로드 코드

스스로 일하는 에이전트 팀을 설계하고 운영하는 방법인 하네스 엔지니어링을 체계적으로 정리한 최초의 실전서

저자 : 황민호
출간 : 2026-06-11

상세보기

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

단일 AI 에이전트는 자신의 실수를 보지 못한다

2026년 현재, Claude Code나 Cursor 같은 AI 코딩 도구는 개발자의 일상이 되었습니다. 프롬프트 하나면 순식간에 코드를 뱉어내는 시대지만, 실무에 이를 적용하다 보면 곧 거대한 벽에 부딪히게 됩니다. 바로 단일 에이전트의 구조적 한계입니다.

가장 치명적인 문제는 AI가 '자신의 실수를 스스로 보지 못한다'는 점입니다. 혼자 PR을 작성하고 스스로 Merge해버리는 구조가 AI 에이전트의 기본값이기 때문입니다. 실제로 2025년 7월에는 한 기업에서 에이전트가 프로덕션 데이터를 삭제하고 "복구 불가"라고 거짓 보고를 했던 끔찍한 사고도 있었습니다.

이러한 통제 불능의 AI를 어떻게 시스템 안으로 안전하게 편입시킬 수 있을까요? 카카오 FDE팀의 황민호(로빈 황) 수석이 집필한 신간 <하네스 엔지니어링>은 이 질문에 대한 가장 완벽하고 체계적인 해답을 제시하는 최초의 실전서입니다.

"모델이 아니라 하네스가 결과를 결정한다." 깃허브 3천 스타를 받은 검증된 아키텍처가 담긴 실전 바이블.

하네스(Harness), 모델 밖의 통제선을 긋다

책에서 말하는 '하네스'란 모델 내부의 가중치를 건드리는 것이 아닙니다. 대신 모델 바깥에 권한, 도구, 검증, 관측을 설계하여 에이전트가 통제된 환경 속에서 스스로 일하게 만드는 구조를 뜻합니다.

가장 충격적이었던 것은 저자가 직접 수행한 A/B 테스트 결과였습니다. 동일한 클로드 모델을 사용했음에도, 단순히 .claude/ 디렉토리의 환경 구성(하네스)을 바꾼 것만으로 성능이 49.5점에서 79.3점으로 수직 상승했다는 기록은 엔지니어로서 엄청난 인사이트를 주었습니다. '프롬프트 엔지니어링'이라는 주술적 영역에서 벗어나, 철저한 '시스템 아키텍처'의 영역으로 AI를 끌어올린 것입니다.

단일 에이전트를 넘어, 팀으로 움직이는 AI. 책임의 분리가 시스템의 안정성을 만든다.

에이전트 팀을 지휘하는 3가지 기둥

이 책은 하네스 시스템을 에이전트, 스킬, 오케스트레이터라는 세 가지 핵심 기둥으로 분해하여 설명합니다.

에이전트(Agent): 가드레일을 통해 에이전트가 '할 수 없는 것'을 파일로 명확히 정의합니다.
스킬(Skill): 'Description' 한 줄이 모델의 호출 여부를 결정한다는 원리(Why-First 원칙 등)를 통해, 도구를 정교하게 설계하는 법을 다룹니다.
오케스트레이터(Orchestrator): 이 책의 백미입니다. 3인 이상의 에이전트가 모였을 때 리더에게 병목이 생기는 현상을 막기 위해, 오케스트레이터를 이벤트 루프와 피어(Peer) 통신(TeamCreate, TaskCreate, SendMessage)으로 풀어내는 과정은 기존 분산 시스템 설계와 완벽하게 맞닿아 있습니다.

파이프라인, 생성-검증, 감독자 패턴 등. 복잡한 AI 프레임워크 없이 Git과 마크다운만으로 구현이 가능하다.

6가지 아키텍처 패턴과 메타스킬

개발자로서 당장 실무에 적용해 보고 싶었던 파트는 후반부의 6가지 아키텍처 패턴이었습니다. 파이프라인, 팬아웃/팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임 등 상황에 맞는 패턴을 플로우차트를 통해 선택하는 기준을 제시합니다.

특히 코드 리뷰 자동화, 풀스택 기능 구현, 그리고 자그마치 3,500개의 레거시 테스트 파일을 마이그레이션한 시나리오 등은 현업에서 마주하는 골칫거리들을 AI 팀이 어떻게 해결할 수 있는지 완벽한 청사진을 제공합니다. 복잡한 파이썬 프레임워크 지식 없이, Git과 마크다운 파일만 다룰 줄 안다면 이 모든 파이프라인을 구축할 수 있다는 점이 이 책의 가장 큰 무기입니다.