『하네스 엔지니어링 with 클로드 코드』 하네스 엔지니어링 이해하기

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

책을 읽게 된 계기

하네스 엔지니어링은 2026년 상반기에 나온 용어로 알고 있습니다. 컨텍스트 엔지니어링을 넘어, 하네스 엔지니어링을 통해 AI가 더 잘 돌아가게끔 만드는 방법이 화제가 되면서 너도나도 적용해보던 것 같습니다. 그런데 저는 정작 이 단어를 들어보기만 했지, 제대로 공부해본 적이 없었습니다.

언젠가부터 마음에 걸렸습니다. 에이전트를 만들고 워크플로우를 설계해서 AI를 쓴다는데, 대체 그걸 어떻게 한다는 건지 궁금했습니다. 무엇보다 제가 진행하는 개인 프로젝트에 적용해서 AI를 제대로 한번 써보고 싶었습니다. 그래서 "하네스 엔지니어링이라는 게 어떤 건지부터 공부해보자"는 마음으로 이 책을 집어 들었습니다.

인사이트

"아, 이게 하네스 엔지니어링이구나"

책을 따라가며 2인 팀으로 — 정말 최소한의 팀으로 — 하네스를 직접 만들어봤습니다. 만들어 돌려보는 순간 "아, 이게 하네스 엔지니어링이구나" 싶었습니다.

하네스는 스킬(Skill), 에이전트(Agent), CLAUDE.md 같은 요소로 작업 환경 자체를 미리 설정해두는 기술입니다. 이걸 적용해두니 프롬프트를 장황하게 길게 쓸 필요가 없었습니다. 그동안 저는 현재 저의 컨텍스트를 길게 작성해서 프롬프트로 알려주곤 했는데, 그게 필요가 없었습니다. 작업 환경을 미리 파일로 구조화해두니 실행 시점엔 한 문장으로 방아쇠만 당기면 되는 것이었습니다. 사용자 프롬프트는 한 문장이면 됐습니다. 이래서 사람들이 하네스를 만들고 프로젝트를 실행하는구나 싶었습니다.

하네스의 세 기둥

책은 하네스를 세 가지 요소로 나눕니다. 누가(Agent), 어떻게(Skill), 언제 누구와(Orchestrator). 이 셋은 각각 독립적으로 설계되고, 실행 시점에만 맞물립니다.

에이전트는 "누가 이 작업을 맡는가"에 답합니다. 단순한 설정이 아니라 일종의 역할 계약서입니다. 그 에이전트가 무엇을 담당하고, 어떤 기준으로 판단하며, 누구와 어떻게 소통하는지를 명시한 살아 있는 문서입니다.
스킬은 "이 작업을 어떤 절차로 하는가"에 답합니다. 반복되는 작업을 재사용 가능한 절차로 정리해둔 파일입니다. description 한 줄이 호출 여부를 결정합니다. 그래서 "무엇을 하는지"보다 "언제 이 스킬을 써야 하는지"를 명확히 적어주는 게 핵심입니다.
오케스트레이터는 "이 작업을 언제, 누구와 하는가"에 답합니다. 핵심은 지시자가 아니라 지휘자라는 점입니다. 팀원 각자가 자신의 악기를 연주하도록 맡기는 것이 결국 최고의 연주를 만듭니다.

객체지향에서 역할을 나누듯, AI에게도 역할을 분리해주는 것 — 그게 하네스의 출발점이라는 걸 배웠습니다.

그래서, 저도 하네스를 만들어보고 싶어졌습니다

개념을 배우고 나니 직접 하네스를 만들어보고 싶다는 생각이 들었습니다. 거창한 것 말고, 제가 매주 반복적으로 하는 일 중에서 하나를 골라보기로 했습니다.

① 개발 블로그 스터디 discussion 만들기

discussion 작성 에이전트
discussion 검토 에이전트
개발 블로그 스터디 discussion 스킬

작성하는 에이전트와 검토하는 에이전트를 나누는 구조입니다. 책에서 강조하는 생성-검증 패턴에 자연스럽게 들어맞아서, 가장 먼저 만들어보기 좋겠다고 생각했습니다.

마무리

책을 읽으면서, 단어만 들어봤던 '하네스'라는 개념과 조금은 가까워졌습니다. 책에서 배운 여러 패턴과 하네스를 구현하는 방법들을 제대로 이해하려면 결국 직접 해보는 수밖에 없을 것 같습니다. 그래서 제가 매주 반복하는 일과 개인 프로젝트에 하나씩 적용해보려 합니다. 실제로 하네스를 만들어 본 기록은 따로 글로 남겨보겠습니다.