요즘 어디나 AI, LLM 이야기를 하지만 막상 현업에서 복잡한 비즈니스 로직을 연결해 '돈이 되는 에이전트 시스템'을 만들려고 하면 막막한 게 사실이었습니다. 이 책은 단순히 클로드(Claude) API를 어떻게 쓰는지 보여주는 매뉴얼이 아닙니다. 여러 개의 AI 에이전트가 어떻게 유기적으로 협업하고, 개발자는 이를 어떻게 제어(Harness)하고 운영해야 하는지 '아키텍처' 관점에서 명쾌하게 풀어내 주네요. 클로드 코드를 활용해 생산성을 극대화하는 실전 팁들이 가득해서, 팀 빌딩이나 파이프라인 설계를 고민하는 아키텍터와 시니어 개발자분들에게 강력히 추천합니다. 오랜만에 실무에 바로 적용할 수 있는 묵직한 책을 만났네요.

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

하네스 엔지니어링 with 클로드 코드(한빛미디어, 2026)

[모델이 아니라 하네스가 결과를 결정합니다.]

AI 에이전트 구성을 통한 업무 효율과 생산성 증대로 뜨거운 오늘, 루프 엔지니어링과 더불어 '하네스 엔지니어링'이 화두로 떠오르고 있다. 저자(황민호)가 페이스북 친구라 저자의 행적을 sns를 통해 관심있게 보고 있던 찰나, 한빛미디어를 통해 하네스 엔지니어링의 기본 개념과 사용법을 설명하는 책이 출간 되었다. 한빛미디어 - 나는 리뷰어다를 통해 살펴본 AI 에이전트 구성의 새로운 방법, ai 모델을 변경하는 것이 아닌 모델 이외를 통제하여 AI 에이전트가 안전하고 예측 가능한 방식으로 작동하도록 설계하는 법을 책을 통해 만나게 되었다.

하네스의 주요 구성요소는 '권한, 도구, 검증, 상태, 관측' 으로, 단일 에이전트의 '실패'를 모델의 한계가 아니라 환경의 설계 문제로 다루는 방법이다. 저자는 클로드 코드를 통한 실습으로 하네스의 구성법을 '에이전트'-'스킬'-'오케스트레이터'의 세 가지 구성요소로 역할과 책임을 설명한다.

에이전트는 '누가'
스킬은 '어떻게'
오케스트레이터는 '누구와'

에이전트 팀 구성을 위해 에이전트의 정의, 스킬 설계, 오케스트레이터를 구성하는 반복 작업을 '메타스킬'로 명칭하며 '어떤 스킬과 에이전트를 만들어야 하는가?'에 대한 고민의 답을 제안한다. 메타스킬은 자기 참조성을 통해 검증 가능성을 갖으며, 이는 하네스 스킬을 통한 엔지니어링 테스트 방식으로 연결된다.

하네스의 개념 이해를 위해 저자는 6가지 아키텍처 패턴으로 에이전트 구성 예시를 든다. 에이전트를 어떻게 분리 할 것인지?(몇 개의 에이전트를 구성할 것인지?)를 패턴을 통해 문제에 알맞는 팀 모양을 구성하도록 안내하며 복합 패턴 및 3~5명의 팀 규모 상한을 제시한다.

'하네스 엔지니어링'을 텍스트로 마주했을때는 '아! 이런 기술도 있구나. 재밌겠는데?'하는 호기심과 관심이었지만, 책을 통해 실제 실습 구성을 따라가면 엔지니어링에 필요한 다양한 개념과 원리 이해를 만나게 된다. 책을 한 번 완독 후 클로드 코드로 저자의 하네스 설계를 한 땀 한땀 따라가며 지금 왜 이 기술이 화두인지, 필요한지, 유용한지를 깊이있게 알아갈 수 있었다. (특히 마지막 Part4. 실전편에서는 다양한 팀 구성 방법과 응용 방법 그리고 주의사항까지 제시하며 하네스 엔지니어링의 A to Z를 설명하는 점이 입문자에게 큰 도움이 되었다.)

클로드 코드를 많이 사용하고, AI 에이전트에 관심이 있는 그리고 '하네스 엔지니어링'이 궁금한 모든분께 황민호 저자의 하네스 엔지니어링 실전 가이드 '하네스 엔지니어링 with 클로드 코드'를 추천한다.

저자 : 황민호

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

출판사 : 한빛미디어

출간 연도 : 2026.06.11

페이지 : 308쪽

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

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

www.hanbit.co.kr

https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

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

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

즘 클로드 코드(Claude Code) 관련 내용을 정말 어마어마하게 듣고 있습니다. 프롬프트 엔지니어링, 하네스 엔지니어링, 클로드 스킬, CLAUDE.md, 옵시디언 에이전트 자동화까지. 하루가 멀다 하고 새로운 개념이 쏟아져서, 솔직히 다 따라가기가 벅찰 정도입니다.

그 많은 키워드 중에서도 몇 달째 가장 뜨거운 단어가 바로 '하네스 엔지니어링' 입니다. 도대체 뭐길래 이렇게 핫한 걸까 궁금하던 차에, 한빛미디어 <나는리뷰어다> 6월 도서로 딱 이 책이 도착했습니다.

바로 『하네스 엔지니어링 with 클로드 코드』 입니다.

엔지니어링이라는데, 알고 보면 '내 도구 다듬기'

'하네스 엔지니어링'이라고 하면 단어부터 거창하고 어렵게 느껴집니다. 그런데 책을 읽으면서 제가 받은 느낌은 의외로 단순했습니다. 결국 내가 쓸 도구를 잘 다듬는 일과 비슷하다는 것입니다. 도구를 잘 다듬어야 좋은 결과물이 나오는 건 너무 당연한 이야기니까요.

예를 들면 내 방 가구 배치 같은 것이라고 생각하면 쉽습니다. 같은 방, 같은 가구라도 어디에 어떻게 두느냐에 따라 동선이 편해지기도 하고 답답해지기도 하죠. AI도 똑같습니다. 같은 모델이라도 일하는 환경을 어떻게 배치하고 다듬어 주느냐에 따라 결과물이 완전히 달라집니다.

이 책이 처음부터 끝까지 강조하는 메시지도 바로 그것입니다.

즉 프롬프트를 잘 쓰는 시대에서 → 하네스(환경)를 잘 설계하는 시대로 넘어가야 한다는 겁니다. 저는 이 한 문장 때문에 책을 끝까지 읽기로 했습니다.

그래서 하네스가 뭔가요

말은 어렵지만 구조는 단순합니다. AI 한 명에게 전부 떠넘기지 말고, 역할을 나눠서 'AI 팀'처럼 일하게 만드는 틀입니다.

에이전트(누가) — 어떤 역할을 맡을지

스킬(어떻게) — 그 일을 하는 방법

오케스트레이터(언제·누구와) — 누가 언제 협업할지

이 세 가지를 분리해서 설계하면 AI가 혼자 일할 때 생기는 한계를 구조적으로 메울 수 있다는 게 책의 뼈대입니다.

직접 읽어보니 좋았던 점

거창한 도구가 필요 없습니다. Git과 마크다운만으로 구현이 가능해서, "또 무슨 프레임워크 깔아야 하나" 하는 부담이 없었습니다.

'생성-검증' 구조가 인상적이었습니다. AI가 만든 결과물을 AI가 다시 검증하게 짜는 방식인데, 그동안 제가 일일이 손으로 확인하던 일을 시스템으로 풀 수 있겠더라고요.

실전 사례가 진짜 실무에 가깝습니다. 코드 리뷰, 레거시 마이그레이션, 디버깅처럼 "이건 나도 겪는 일"인 사례라 바로 와닿았습니다.

[인상 깊었던 페이지나 도식 사진 1장 - 6가지 아키텍처 패턴 부분 추천]

솔직히 살짝 아쉬운 점

부제 그대로 '개발자' 실전 가이드라, 저처럼 코딩이 깊지 않은 사람은 용어에서 멈춰서게 되는 일이 많았습니다.

하지만 용어에 친숙해진다면 비개발자도 충분히 따라갈 수 있습니다.

'하네스'라는 개념 자체가 새것이다 보니, 처음 한두 챕터는 용어에 적응하는 시간이 필요했습니다.

그래도 308쪽 분량에 군더더기가 적고, 개념에서 패턴, 실전으로 이어지는 순서가 깔끔해서 길을 잃지는 않았습니다.

이런 분께 추천합니다

클로드 코드를 '혼자 쓰는 도구' 수준에서만 쓰고 있는 분

AI를 팀이나 조직 단위로 도입하려는 리드 개발자

반복 작업을 자동화 시스템으로 묶고 싶은 분

반대로 이제 막 AI 입문, 프롬프트를 처음 배우는 단계라면 조금 이른 책일 수 있습니다.

마무리

저는 이 책을 읽고 "AI에게 일을 시키는 법"에서 "AI 팀을 운영하는 법"으로 생각이 한 단계 넘어갔습니다. 쏟아지는 클로드 코드 키워드 속에서 왜 하네스 엔지니어링이 몇 달째 가장 핫한지, 읽고 나니 납득이 되더군요. 마침 제가 블로그에 연재 중인 자동화 실습에도 바로 적용해 볼 생각입니다.

AI를 단순한 '도구'가 아니라 잘 다듬어 쓰는 '나만의 작업 환경'으로 만들고 싶은 분이라면, 한 번 읽어볼 가치가 충분합니다.

도서 보러가기: https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

#하네스엔지니어링 #클로드코드 #ClaudeCode #AI에이전트 #한빛미디어 #나는리뷰어다 #AI자동화 #업무자동화 #서평 #슈마의보고듣고쓰고

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

단일 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과 마크다운 파일만 다룰 줄 안다면 이 모든 파이프라인을 구축할 수 있다는 점이 이 책의 가장 큰 무기입니다.

- 총평 및 추천 대상

<하네스 엔지니어링>은 단순히 AI에게 일을 시키는 '사용자'를 넘어, AI가 일하는 '시스템'을 설계하려는 아키텍트를 위한 책입니다.

✅ 이런 분들에게 강력 추천합니다:

• 클로드 코드 등 AI 도구를 쓰고 있지만, 단일 에이전트의 잦은 실수와 한계에 부딪힌 개발자
• 하네스라는 개념을 들어봤으나, 실제 마크다운과 Git으로 어떻게 구현하는지 막막했던 분
• AI를 개인의 도구로 쓰는 단계를 넘어, 조직의 워크플로(코드 리뷰, 레거시 마이그레이션 등)에 도입하려는 리드 개발자

AI가 작성한 코드를 불안한 눈으로 지켜보는 대신, 견고한 하네스를 입혀 완벽하게 통제된 'AI 개발 팀'을 당신의 서버에 구축해 보시길 바랍니다.

AI를 통제하는 것은 마법 같은 프롬프트가 아니라,
견고하게 설계된 시스템 아키텍처다.

패턴화된 업무, 복잡하지만 규칙이 있는 코드. 이 모든 것은 이제 AI에 넘겨야 되는 세상

​

작년까지만 해도, langSqeunce, langGraph를 비롯하여, prompt -> context AI 개발이 대세였었다. 하지만, 1년도 안되는 시간에 클로드가 탄생하였고, 클로드를 통해 세상은 다시금 대격변을 겪고 있다.

​

언제부터인가 튜닝 머신 (사람과 기계의 대화를 통해 사람이 대화 상대가 머신인지 아닌지 판별하는 것) 개념 그 이상의 것이 등장하기 시작했다. 아마도 그 시작은 전산학이 시작해서부터 계속되었겠지만, 세기의 대결인 이세돌 사범과 알파고의 대결 그 이후라고 해도 과언이 아닐 것이다. 즉, 기술의 변화 속도가 이제는 사람이 예측 가능한 범주 그 이상이 된 것이다.

​

위 사건 이후로, AI 기술은 수많은 갈래를 뻗어 파생 분야가 생겨났다. 그리고 그 가지가 뻗기와 가지치기를 반복한 결과 마침내 오늘에 이른 것이라 할 수 있다. 그것은 바로 대 AI 시대.. 그것이 오늘의 현실인 것이다.

​

【책 내용 요약】

​

이 책은 prompt -> context -> harness에 이르는 간략한 역사를 소개한 후, 요즘 대세가 되는 AI Model을 제외한 모든 것을 개발하는 harness 개념을 소개한다. 내용은 간략하며, 담백하고 AI를 이용해 개발을 해본 사람이 있다면 누구든 쉽게 이해할 수 있는 그런 구성으로 되어있다.

​

대표적인 책의 구성은 아래와 같다.

• 왜 하네스인가?
• 빠르게 하네스 이해하기
• 에이전트, 스킬, 오케스트레이터를 설계/만드는 방법
• 하네스 스킬로 구성하기 등

앞서 언급한 내용과 동일하게 harness 엔지니어링은 모델을 제외한 모든 것들을 자동화?의 관점에서 조립하고 설계하는 기술이라 할 수 있다.

​

가령 A라는 모델이 있다면, A라는 모델뿐만 아니라, B 모델, C 모델까지 확장하여 각각의 Agent에 역할을 할당하고, 그 역할에 따라 Agent (모델)끼리 상호 소통하고 최종의 목적을 향해 자동화된 프로세싱을 만드는 과정이 harness 엔지니어링이다.

​

즉, 각각의 Agent에 역할과 role을 정의하고 그 역할과 role에 따라서 정확히 동작하는지를 감독/평가/결정하는 일련의 과정을 정의하는 것이라 할 수 있다.

​

【 하네스 엔지니어링을 읽고 나서 】

​

단순히 코딩뿐만 아니라 이제는 전 산업분야에 걸쳐서 AI가 적용되고 있고, 이미 적용된 사례도 적잖게 찾아볼 수 있다. 무엇보다 Agent 1개가 거의 사람 한 명 몫을 수행하기에 (완벽하진 않지만) 더 이상 1인 창업이 완전히 불가능한 세상이라 할 수도 없게 되었다.

​

아마도 머지않은 시점에 (2~3년 내로) 개인의 경쟁력은 결국 창의력, 추진력으로 귀결되는 세상으로 탈바꿈하게 될 것이다. 즉, 이제는 전문적인 기술보단 창의적인 생각이 더욱 주목받는 세상이 시작된 것이다.

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

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

최근 AI 코딩 도구의 성능은 눈에 띄게 발전했습니다. Claude Code나 Cursor 같은 도구를 활용하면 상당한 양의 코드를 짧은 시간 안에 작성할 수 있습니다. 하지만 실제 프로젝트에 적용해 보면 모델의 성능만으로는 해결되지 않는 문제가 많습니다. AI가 엉뚱한 방향으로 코드를 수정하거나 프로젝트 전체 구조를 제대로 이해하지 못하는 경우도 있고, 같은 작업을 반복하면서도 일관성 없는 결과를 만들어내는 경우도 자주 경험하게 됩니다. 이 책은 이러한 문제의 원인을 AI 모델 자체가 아니라 AI가 일하는 환경에서 찾고 있습니다. 그리고 그 해결 방법으로 '하네스 엔지니어링'이라는 새로운 접근법을 제시합니다.

이 책은 단순히 Claude Code 사용법을 설명하는 책이 아닙니다. AI 에이전트가 안정적으로 일할 수 있도록 역할과 권한, 도구, 검증 체계, 협업 구조를 어떻게 설계해야 하는지를 단계적으로 설명합니다. 저자가 말하는 하네스는 AI 모델 외부에 구축하는 작업 환경을 의미하며, AI가 더 안전하고 반복 가능하게 작업할 수 있도록 만드는 기반입니다. 책에서는 에이전트, 스킬, 오케스트레이터, 메타 하네스 같은 개념을 중심으로 AI가 협업하는 구조를 어떻게 설계해야 하는지 구체적으로 설명합니다. 단순히 프롬프트를 잘 작성하는 방법을 알려주는 것이 아니라, AI가 지속적으로 좋은 결과를 만들어낼 수 있는 시스템을 구축하는 방법을 다룬다는 점이 인상적입니다.

기존에 읽었던 'AI 에이전트 엔지니어링'이나 '에이전트 시대의 AI 시스템 설계'가 AI 에이전트의 구조와 시스템 설계 관점을 설명했다면, 이 책은 한 단계 더 나아가 Claude Code를 활용해 실제 개발 환경에서 하네스를 구축하는 방법에 집중하고 있습니다. 또한 '혼자 공부하는 바이브 코딩 with 클로드 코드'가 AI를 활용한 개발 생산성 향상에 초점을 맞췄다면, 이 책은 생산성을 지속적으로 유지하기 위한 개발 환경 자체를 어떻게 설계해야 하는지를 설명합니다. 결국 AI를 잘 사용하는 방법보다 AI가 잘 일할 수 있는 환경을 만드는 방법을 알려주는 책이라고 할 수 있습니다.

이 책에서 가장 인상 깊었던 부분은 모델이 아니라 하네스가 결과를 결정한다는 관점입니다. 같은 AI 모델을 사용하더라도 어떤 환경에서 동작하느냐에 따라 결과가 크게 달라질 수 있다는 점을 실제 사례를 통해 설명합니다. 저자는 다양한 프로젝트에 하네스를 적용한 경험을 바탕으로 단일 에이전트의 한계를 분석하고, 여러 에이전트가 역할을 분담하고 서로 검증하는 구조가 왜 필요한지를 설득력 있게 설명합니다. 특히 성공 사례뿐 아니라 잘못된 설계 방식과 안티 패턴도 함께 소개하고 있어 시행착오를 줄이는 데 도움이 됩니다.

이 책은 Claude Code를 중심으로 설명하지만 특정 도구에만 적용되는 내용은 아닙니다. 역할 분리, 검증 체계, 컨텍스트 관리, 협업 구조와 같은 개념은 Cursor를 비롯한 다른 AI 코딩 도구를 사용할 때도 그대로 활용할 수 있습니다. 특히 이미 AI 코딩 도구를 사용하고 있지만 기대했던 만큼 생산성이 나오지 않거나 프로젝트 규모가 커질수록 AI 활용에 한계를 느끼고 있는 개발자라면 많은 도움을 받을 수 있습니다. 단순히 AI에게 코드를 생성하도록 맡기는 수준을 넘어 AI와 함께 개발하는 체계를 만들고 싶은 사람에게 적합한 책입니다.

'하네스 엔지니어링 with 클로드 코드'는 AI 코딩 도구를 사용하는 방법을 알려주는 책이 아니라, AI가 제대로 일할 수 있는 환경을 설계하는 방법을 알려주는 책입니다. 앞으로 AI 개발은 더 좋은 모델을 사용하는 경쟁보다 AI가 안정적으로 협업할 수 있는 구조를 얼마나 잘 설계하느냐가 더욱 중요해질 것입니다. 그런 점에서 이 책은 AI 시대 개발자가 갖춰야 할 새로운 개발 방식과 사고방향을 제시하는 실전서입니다. Claude Code를 활용하고 있거나 AI 에이전트 기반의 개발 환경을 구축하려는 개발자라면 한 번쯤 읽어볼 가치가 충분한 책입니다.

안녕하세요, AI 에이전트와 자동화 도구를 적극 활용 중인 개발자입니다. 요즘 클로드 코드, 커서 같은 AI 코딩 도구를 쓰면서 늘 한 가지 불편함을 느꼈어요."왜 이 AI는 자기가 실수한 걸 스스로 못 잡지?"

혼자 코드를 짜고, 혼자 검토하고, 혼자 머지하는 구조에서 에이전트의 자기 검증은 결국 자기가 자기 글을 교정하는 것과 같다는 걸 어렴풋이 느끼고 있었습니다. 그러던 중에 [하네스 엔지니어링 with 클로드 코드]를 읽게 됐습니다.

결론부터 말하면, 이 책은 "AI 도구를 어떻게 더 잘 쓰는가"가 아니라 "AI가 일하는 환경 자체를 어떻게 설계하는가"를 다루는 책입니다.

​

"모델이 아니라 하네스가 결과를 결정한다"

책의 첫 장부터 충격적인 사례가 나옵니다. 2025년 7월, 한 기업에서 AI 에이전트가 임원 레코드 1,206명분을 삭제하고 "복구 불가능합니다"라고 보고한 사건이요. 알고 보니 복구는 가능했고, 에이전트가 스스로 내린 판단이 문제였습니다.

읽으면서 손이 떨렸습니다. 이건 먼 나라 이야기가 아니거든요. AI 에이전트가 plan → code → verify → self-revise의 네 단계를 혼자 다 수행하는 구조에서는, 처음에 놓친 가정을 끝까지 반복한다는 게 이 책의 핵심 진단입니다.

저자인 황민호(카카오 FDE팀 수석)는 같은 클로드 모델을 두고 환경만 바꿨더니 점수가 49점에서 79점으로 올랐다는 실험 결과를 제시합니다. 모델이 아니라 모델을 둘러싼 구조가 결과를 결정한다는 것, 그게 이 책이 말하는 하네스 엔지니어링의 핵심입니다.

하네스란 무엇인가 — "모델 바깥을 설계하라"

Part 1은 왜 단일 에이전트가 믿을 수 없는지에서 시작합니다. 단일 에이전트는 자기 실수를 잘 못 본다. 구조를 보면 이유가 명확합니다. 혼자 쓴 PR을 혼자 머지하는 구조이기 때문입니다.

하네스란 모델의 가중치를 건드리지 않고, 모델 바깥에 권한·도구·검증·관측을 설계해 에이전트가 혼자 움직이게 만드는 환경입니다. 병목이 능력이 아니라 구조에 있다는 인식의 전환이 이 파트의 핵심입니다.

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

이 한 줄이 책 전체의 출발점입니다. AI 에이전트가 계획·작성·검증·자기수정을 모두 같은 박스 안에서 수행하니, 처음에 놓친 가정은 끝까지 반복되고, 다른 검토자가 없으면 설계 결함이 그대로 남습니다.

하네스의 세 기둥 — 에이전트·스킬·오케스트레이터

Part 2는 이 책에서 가장 밀도 높은 파트입니다. 하네스를 이루는 세 기둥을 순서대로 분해합니다.

에이전트(누가) — 역할과 가드레일을 파일로 정의합니다. "이 에이전트는 무엇을 할 수 있고, 무엇을 할 수 없는가"를 CLAUDE.md와 에이전트 정의 파일에 명시합니다.

스킬(어떻게) — description 한 줄이 호출 여부를 결정합니다. 아무리 잘 만든 스킬도 description이 엉성하면 에이전트가 언제 써야 할지 모릅니다. 스킬 설계의 핵심은 description 작성이라는 게 인상 깊었습니다.

오케스트레이터(언제 누구와) — TeamCreate, TaskCreate, SendMessage 세 도구로 팀을 조율합니다.

특히 "한 파일에 다 넣으면 무엇이 깨지는가" 챕터가 인상 깊었습니다. 누가(역할), 어떻게(스킬), 언제 누구와(조율)가 한 파일에 섞이면 한쪽을 바꿀 때마다 다른 쪽이 영향을 받습니다. 단일 책임 원칙을 어긴 클래스 하나가 자리를 차지하고 있는 셈입니다.

저는 읽고 나서 팀 내 에이전트 구성을 다시 들여다봤습니다. "이 역할 정의가 여기 있어야 하나?" 질문 하나씩 던지면서 정리했더니, 수정 속도가 눈에 띄게 달라졌습니다.

오케스트레이터 — 리더 병목을 어떻게 해소할까

6장 오케스트레이터 챕터는 사실상 이 책의 핵심입니다. 팀이 세 명을 넘으면 리더 병목이 생깁니다. 오케스트레이터가 모든 메시지를 중계하면 처리량이 병목이 되고, 직접 코드를 고치면 책임 분리가 무너집니다.

이를 해결하는 게 세 가지 기본 도구입니다. TeamCreate로 세션 객체로서의 팀을 생성하고, TaskCreate로 공유 작업 큐를 관리하고, SendMessage로 팀원끼리 직접 소통하게 합니다.

책에서 강조하는 건 이거예요. "모든 것이 성공한다고 가정하는 오케스트레이터는 프로덕션에서 가장 먼저 무너진다." — 클로드 코드 오케스트레이션 공식 가이드에서 인용한 이 문장이 챕터 전체를 관통합니다.

팬아웃/팬인, 파이프라인, 생성-검증 등 여섯 가지 아키텍처 패턴과 함께 실행 모드별 트레이드오프도 명확하게 정리됩니다.

Part 4 실전편 — 코드 리뷰 자동화 팀

이 챕터는 그냥 실무 필살기입니다. PR diff를 받아 정적 분석, 보안 검토, 테스트 영향 검토를 병렬로 수행하고 하나의 리뷰 리포트로 통합하는 코드 리뷰 자동화 팀의 전체 구성이 낱낱이 공개됩니다.

오케스트레이터 스크립트부터 각 에이전트 정의 파일, 출력물 경로 설계까지 실제로 복사해서 바로 실행 가능한 수준으로 담겨 있습니다.

​

Airbnb가 3,500개의 React 테스트를 6주 만에 이전한 레거시 마이그레이션 팀 사례, OpenAI가 5개월간 100만 줄을 생성하며 수동 코드 0줄을 유지한 사례도 Part 4에서 다룹니다. 세션이 여러 번 반복될 때 어떻게 흐름을 이어가는지, 진행 로그를 어떻게 관리하는지까지 구체적으로 설명합니다.

부록 — 설치부터 안티패턴까지

부록 A는 클로드 코드 설치와 환경 설정을 다룹니다. macOS, Windows, Linux 각각의 설치 명령, Native installer 우선 권고, 지원 계정 종류까지 공식 문서 기준으로 정리돼 있습니다. 팀 도입 시 온보딩 가이드로 그대로 쓸 수 있습니다.

부록 B의 안티패턴 카탈로그는 특히 현실적입니다. 레벨 1(컨텍스트 창 초과), 레벨 2(토큰 마비 3단계), 레벨 3(큐레이션), 레벨 4(피드백 품질) 순으로 에이전트가 망가지는 경로를 구체적으로 보여줍니다.

부록 C의 5분 셀프 진단 10항목은 팀에 공유하기 딱 좋습니다. claude doctor가 모든 항목 OK인지, 에이전트 수가 20개 미만인지, CLAUDE.md가 200줄 이하인지 등 월 1회 응급 점검으로 활용할 수 있습니다.

이 책을 읽고 나서 달라진 것

읽고 나서 코딩 실력이 느는 게 아니라, AI 에이전트에게 일을 맡기기 전에 먼저 멈추게 됩니다.

"이 에이전트가 혼자 이걸 해도 되는가?", "검증 단계가 분리돼 있는가?" 이 질문이 자동으로 나오기 시작해요. 에이전트에게 작업을 던지기 전에 구조부터 고민하게 됐고, 뭔가 꼬인다는 느낌이 들면 그게 모델 문제가 아니라 하네스 구조 문제라는 신호로 받아들이게 됐습니다.

"한 번 읽고 끝"이 아니라, 꽂아두고 실전에서 막힐 때마다 꺼내보는 기준서 같은 느낌입니다.

이런 분들께 강추

AI 코딩 도구를 쓰고 있지만 단일 에이전트의 한계를 느끼는 개발자

클로드 코드 같은 도구를 팀이나 조직에 도입하려는 리드 개발자

에이전트가 자기 실수를 왜 못 잡는지 구조적으로 이해하고 싶은 분

하네스라는 단어를 들어봤지만 막상 어디서 시작해야 할지 모른 분

프롬프트 엔지니어링이나 모델 내부 지식 없이도, git과 마크다운 파일만 다룰 수 있다면 충분합니다.

댓글로 여러분은 AI 에이전트가 예상치 못한 행동을 했던 경험이 있으신지 공유해 주세요!

yes24 바로가기

하네스 엔지니어링 with 클로드 코드 | 황민호 | 한빛미디어 - 예스24

단일 에이전트 대신 ‘에이전트 팀’을 설계하라클로드 코드로 구축하는 최초의 하네스 실전 가이드 AI 에이전트를 도구로 쓰는 단계를 넘어, 스스로 일하는 에이전트 팀을 직접 설계하고 운영하는 방법인 하네스 엔지니어링을 체계적으로 정리한 최초의 실전서다. 이 책의...

www.yes24.com

#하네스엔지니어링 #클로드코드 #AI에이전트 #하네스아키텍처 #개발자서평 #에이전트팀설계 #한빛미디어 #카카오AI #오케스트레이터 #메타스킬

​

기술의 패러다임이 바뀔 때마다 우리는 수많은 개념과 정의 속에서 살아갑니다. 최근 생성형 AI의 폭발적인 발전은 개발 프로세스 자체를 뒤흔들고 있습니다. 이러한 격변의 시기에 누군가가 복잡하고 어려운 개념을 정리하고 방법을 가이드해 준다면 누구나 쉽고 빠르게 AI를 활용할 수 있을 겁니다. 「 하네스 엔지니어링 with 클로드 코드 」는 단순히 AI 도구의 사용법을 나열하는 가이드북이 아닙니다. 이 책은 '클로드 코드(Claude Code)'를 활용하여, 시스템의 안정성과 유연성을 확보하는 '하네스 엔지니어링(Harness Engineering)'의 실천적 방법론을 체계적으로 다룹니다. 단순히 AI를 활용하는 방법을 다루는 게 아니라, 클로드 코드와 하네스 엔지니어링을 활용할 때 우리가 고민하고 생각해봐야 하는 것들을 자세하고 여러 시나리오를 기반으로 생각해 보도록 유도합니다.

IT 업계의 수 많은 기술 트렌드, 프레임워크나 최신 개발 언어에만 매몰된 책들은 유통기한이 짧을 겁니다. 반면, 기술의 저 아래 바닥부터 '본질'을 건드리는 책은 시간이 지나도 빛을 발할 겁니다. 그런 의미에서 「 하네스 엔지니어링 with 클로드 코드 」는 단순한 트렌드만 따라가는 책이 아니라, AI 협업 시대의 엔지니어링 본질을 디테일하게 터치해주는 책입니다. 대다수의 AI 관련 서적들은 생성형 AI로 어떻게 하면 좋은 프롬프트를 작성할 수 있는지와 같은 단편적인 기능에만 집중합니다. 그러나 「 하네스 엔지니어링 with 클로드 코드 」는 시스템 공학적 틀 안에서 특히 데이터 분석 시스템 구축 시 많은 이들이 범하는 오류인 '데이터 모델 만능주의'를 타파할 수 있는 기회일 수 있습니다.

흔히 정교한 수학적 모델이나 잘 정돈된 테이블 스카마만 있으면 훌륭한 데이터 분석 시스템이 완성될 것이라 착각합니다. 하지만 실제 시스템은 독립된 공간에서 진공상태로 존재하지 않습니다. 끊임없이 유입되는 이기종 데이터, 네트워크 지연, 메모리 한계, 끊임없는 비즈니스 요구사항 등등에서 살아 움직여야 합니다. 저자는 「 하네스 엔지니어링 with 클로드 코드 」에서 클로드 코드를 활용해 이러한 환경적 변수를 어떻게 통제하고, 시스템 분석을 통해 구조적 결함을 어떻게 선제적으로 예방할 수 있는지 구체적인 아키텍처와 코드로 보여줍니다. 

이 책은 단순히 "AI를 어떻게 사용하나요?"라고 말하지 않습니다. 대신 "AI와 함께 시스템을 어떻게 더 단단하게 만들 것입니까?"를 묻습니다. 클로드 코드를 활용해 AI 자동화를 진행하기 원하는 주니어, 시니어 개발자 등등 모든 사람들에게 기꺼이 일독을 권하는 바입니다. 

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

한빛미디어 하네스 엔지니어링 with 클로드 코드

저는 주로 커서를 이용해서 개발하고 클로드의 모델을 이용하지만 아직도 10%도 제대로 활용하고 있지 못하다고 생각이 드는 개발자입니다. 분명히 생산성이 향상되었긴 하지만, 아직도 뭔가 많이 활용할 수 있는데 못하고 있는 부분이 꽤 남아있다는 것도 알기에 항상 인공지능을 이용하면서도 찝찝한 기분이 들죠.

​

​

이번에 읽고 있는 『하네스 엔지니어링 with 클로드 코드』는 이런 부분을 일부 해결해주는 좋은 도구였습니다. 완전히 정독하지 못해서 실제 업무에 반영하지 못한 부분이 많지만 제가 어떤 부분을 놓치고 있는지를 깨닫게 해준 부분이 많았어요. 책에서 언급한 대상 독자인 "커서를 쓰고 있지만 단일 에이전트 프롬프팅에서 벗어나지 못한 개발자"는 저를 보고 하는 소리인 것 같군요.

​

​

하네스 엔지니어링에 대해서는 이것저것 들은 것이 있어서 개념만은 알고 있었습니다만 내 업무에, 나의 프로젝트에 어떻게 적용하는지는 거의 몰랐고 시작할 엄두도 못내고 있었어요. 바로바로 들어오는 업무를 쳐내는 것도 바빴거든요. 그런데 책을 보니 조금만 시간을 내서 환경을 구성하기만 하면 앞으로의 작업들이 상당히 정확하면서도 편해질 수 있는 가능성이 있음을 느꼈습니다.

​

​

실제로 책에서 언급하길 LLM은 그대로 두더라도 모델의 환경을 바꾸기만 했을 때 상당한 수준의 벤치마크 향상이 보였다고 합니다. 사실상 생산성의 향상이라고 봐야겠죠?

​

​

그리고 이를 위한 엔지니어링 기법으로 최근 많이 알려지고 응용되고 있는 것이 바로 하네스 엔지니어링입니다. 모델은 그대로 두고 주변을 설계하는 것이 핵심이라고 해요. AI 에이전트가 일하는 환경 전체를 설계하고 운용하는 구조적 체계를 만드는 일인데, 이거 점점 개발자가 하는 일이 최상위 관리자의 역할로 올라가는 것 같습니다. 문제는 그 속도가 너무 빨라서 제가 잘 못 따라가는 것 같네요 ㅋㅋ

​

​

하네스 엔지니어링에서 필요한 것은 누가(Agent), 어떻게(Skill), 누구와(Orchestrator)라는 세 가지 요소인데, 말은 어렵지만 책이나 자료를 읽으면 읽을수록 그냥 현실에서의 팀장님 역할인 것 같습니다. 우리 모두가 팀장이 되어야 하는 시대가 찾아온 것 같아요. 리더십에 대한 책을 보는게 직접적인 업무에 도움이 될 것만 같군요.

​

​

저는 레거시 시스템의 유지보수가 대부분의 업무이고 새로운 기능 개발도 기존 기능의 응용으로 만들어지는 것이 대부분이기에 지금까지의 단일 에이전트를 이용한 프롬프트 기술로도 상당 부분 해결이 됐어요. 그러다보니 Skill이나 Agent에 대한 정의 파일도 거의 잘 사용하지 않았죠.

​

​

그런데 최근에 조금씩 프로젝트 전체에 대해 파악해서 처리할 일이 많아지면서 저라는 인간의 뇌로는 단시간에 파악할 수 없는 부분이 많아지고 있어요. 이런 부분은 충분히 AI의 도움을 받을 수 있을텐데, 아직 방법을 잘 몰랐습니다. 『하네스 엔지니어링 with 클로드 코드』에서 이런 부분에 대한 기법들을 아주 많이 배우고 있어요.

​

​

특히 Skill을 작성하는 것은 성능에 꽤 많은 영향을 줬던 것 같습니다. 이게 문제는 너무 급한 일정을 소화해야 할 때는 스킬이나 에이전트에 대한 설계를 할 시간조차 나지 않는다는건데요. 그렇다고 안하면 미래에 뒤쳐질 것이 자명하기 때문에 걱정이 많습니다.

​

​

코드 작성의 전체 비중 중에서 소스코드를 직접 수정하는 비율이 10% 이하로 떨어진 것이 벌써 몇 달이 됐습니다. 그럼에도 인공지능을 제대로 활용하지 못하는 것은 너무 아쉽네요.

​

아주 조금씩이라도 이 책 『하네스 엔지니어링 with 클로드 코드』 내용을 업무에 반영해보려고 합니다. 얼마나 많이 생산성이 향상될까요...

​

기대됩니다!

​

『하네스 엔지니어링 with 클로드 코드』 리뷰 끝.



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

사내 교육, 가족 상경 등 여러 가지로 너무 정신이 없던 6월이었다. 덕분에 월초에 반 정도 읽고 더이상 진도를 못 내고 있다가 월말이 다 되어서 겨우 완독하고 리뷰를 남겨 본다. 지난 달에 사내에서 SW 보안 교육을 직접 진행했었는데, 그 때에도 살짝 언급을 했었던 하네스 엔지니어링이 이번 도서의 주제이다. 최근 들어 생성형 AI 개발 도구인 ChatGPT Codex와 Claude Code 유료 버전을 하나씩 차례로 사용해 보면서 이번 도서의 주제인 하네스 엔지니어링에 대해서도 실제 테스트를 해볼 수가 있었는데, 음.. 이제는 정말 개발 생산성 향상을 위해 생성형 AI 유료 구독 하나쯤 필수라는 생각이 드는 것처럼 하네스 엔지니어링도 AI 기반 바이브 코딩 시 반드시 활용해야 하는 스킬이라는 생각이 든다.

저자도 강조했듯이 AI 도구의 활용 결과는 모델이 아니라 하네스가 결정을 한다는 말에 나 또한 동의한다. 단순히 프롬프팅만을 입력하면서 코드를 생성하고 개발하는데 그치지 않고, 그러한 프롬프팅 결과가 미리 정해진 규칙에 의해 다듬어질 수 있도록 에이전트 스킬을 미리 심어두게 되면, 꼭 사용 모델을 최신의 프론티어 모델로 변경하지 않더라도 동작의 성능이 올라갈 수 있다는 것이다. 저자 분은 카카오에서 AX 관련 업무를 하면서 그러한 다양한 시도를 통해 더 나은 결과물을 낼 수 있는 환경을 구축할 수 있었고, 이 책은 그러한 저자의 경험에 대한 내용을 담은 도서이다.

하네스(Harness)란 모델의 가중치를 바꾸지 않고, 모델 바깥의 권한, 도구, 검증, 상태, 관측을 설계해 에이전트가 일하게 하는 환경을 말하며, 하네스 엔지니어링은 그러한 하네스라는 AI 에이전트가 일하는 환경 전체를 설계하고 운용하는 구조적 체계라고 이해하면 된다. 이제는 단순히 좋은 프롬프트로 1회성의 좋은 결과물을 내는 것만이 목적이 아니라, AI 에이전트의 자율적인 action을 관리하고 구조적으로 제어하기 위해서 하네스가 반드시 필요해진 시대가 되었다.

솔직히 이 책을 읽기 전까지는, 물론 하네스 엔지니어링이 필요하긴 해도 프롬프트를 길고 정교하게 잘 쓰면 하네스 없이도 그러한 하네스 엔지니어링의 효과를 낼 수 있는게 아닌가하는 생각을 하곤 했었다. (도서에도 그런 내용이 나와 있어서 사실 굉장히 뜨끔했다. ^^;) 그러나 사실 프롬프트는 강제사항이 아니기 때문에, 구조적인 가드레일 및 통제 체계를 갖추기 위해서는 하네스와 같은 별도의 강제 설정이 반드시 필요하고, 그래야만 만에 하나 프롬프트가 잘못되어 있더라도 하네스에 의해 통제될 수 있다. (물론 별도 md로도 100% 강제라고 보장은 안되겠지만..)

한 마디로 본 도서에는 하네스 엔지니어링 노하우의 모든 것이 담겨있다고 볼 수 있을 정도로 하네스와 관련된 많은 유용한 내용을 담고 있어, 하네스 엔지니어링에 대해 입문하고자 하는 분들 뿐만 아니라, 약간의 AGENTS.md나 SKILL.md를 이미 사용하고 있는 분들에게도 유용할 것 같다. 사람이 단일 에이전트 하나에 명령을 내리는 체계에서 AI 에이전트들이 자신의 컨텍스트를 관리하고 서로 협업하면서 자율적으로 일을 할 수 있게 만드는 멀티 에이전트 형태로 변화되면서 이러한 에이전트들에 대한 역할 기반의 동작 설계를 위한 요소로서 하네스가 이용되고 있다.

참고로, 저자분의 깃헙에 가보면 harness-100이라는 리포지토리가 있는데, 일상생활과 업무에 바로 적용할 수 있는 100가지 유용한 에이전트 팀 하네스가 저장되어 있다. 그 내용들만 둘러봐도 하네스를 어떻게 작성하는지 이해하는데 많은 참고가 된다. 보통 여러 개의 멀티 에이전트들을 위한 md 파일과 그에 따라 필요한 skill.md 파일이 존재하고, 무엇보다도 이러한 각 에이전트들의 결과물들을 통합하여 최종 산출물로 정리하는 오케스트레이터 skill.md 파일이 존재하는 구조이다.

아무래도 실습 파일이 md 파일 형태로 되어 있다보니, 실습 자체는 쉽게 해볼 수가 있는데, 문제는 클로드 코드 사용 비용이다. ㅠ 최근 잠깐 풀렸다가 막힌 Claude Fable5 모델을 써보니, Pro 버전이었음에도 토큰(5시간 사용량)이 너무 금방 소진되어서 불편했던 경험이 있었다. 이제는 코딩 실력보다는 토큰을 누가 더 많이 쓸 수 있느냐가 관건인 新 물질 만능시대가 된 것 같아 마음 한편이 좀 씁쓸하기도 하지만, 그럼에도 약간의 비용 투자만 할 수 있다면, 그리고 본 도서에서 다루고 있는 하네스 엔지니어링의 관찰, 구현, 검증, 조정으로 이루어진 정교한 자동화 동작 제어 매커니즘을 적용하게 된다면, 분명 단일 프롬프트 혹은 단일 에이전트를 사용할 때보다 확실히 높은 성능을 낼 수 있다는 것을 느낄 수 있을 것이다.

또한, 개인적으로 부록 D의 토큰 사용량을 다룬 부분이 매우 흥미로웠는데, 돌릴 때마다 토큰 비용이 드는 AI 서비스의 특성 상, 적은 비용 투자 대비 최고의 효율을 얻고자하는 모든 사람들의 관심사항이기 때문이다. 저자분이 그 동안의 경험을 토대로 기록한 5가지 원리와 안티패턴은 예산이 충분치 않은 개인이나 조직에 상당한 도움이 될 것이라 생각된다.

결론적으로, 본 도서는 다음과 같은 분들께 도움이 될 것 같다.

하네스 엔지니어링에 대해 잘 모르거나 이름만 들어보신 분들

하네스 엔지니어링을 통한 적절한 하네스 설정 방법이 궁금하신 분들

프롬프트 엔지니어링만으로 한계를 느끼는 개발자분들

보다 안전한 SW 개발을 위한 보안 가드레일 등을 통해 에이전트 동작 기능에 대한 자동 통제가 필요한 개발자

AI 기술이 대중화되면서 AI 관련 서적들도 쏟아져 나오고 있지만, 본 도서처럼 하네스 엔지니어링을 본격적으로 자세히 다룬 도서는 처음 읽어보게 되어 개인적으로 많은 도움이 되었다. AI 시스템을 소프트웨어 공학적 관점에서 어떻게 통제하고 확장해야 하는지의 본질을 짚어주는 도서인 것 같다.

여담인데, 오늘 페이스북 타임라인에 올라온 글들을 쭉 읽어보다가, 친구 중 누군가가 웹툰 제작용 하네스를 무료로 공개한다고 올린 글을 보고, 여기에도 하네스 엔지니어링 전문가 분이 계셨다고 생각을 했었는데, 다시 잘 보니 본 도서의 저자분이셔서 매우 놀라고 신기했다. ^^ 저자분의 활발한 활동을 보며 나 또한 더 노력해야겠다는 긍정적인 자극이 되는 것 같아 저자분께 이 자리를 빌어 감사의 말씀을 전한다.



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

하네스 엔지니어링의 중요성에 대해 줄곧 들어왔지만, 실체를 정확히 알고 있었다고 말하기는 어려웠습니다.

대략적인 감각은 있었어요. “AI가 일하기 좋은 환경을 만들어야 한다”, “에이전트를 잘 나눠야 한다”, “검증 루프가 필요하다” 정도의 문장들은 익숙했습니다. 하지만 그것이 실제로 어떤 파일로 남아야 하는지, 어떤 역할로 쪼개져야 하는지, 어떤 기준으로 스킬과 에이전트와 오케스트레이터를 분리해야 하는지까지는 선명하지 않았습니다.

『하네스 엔지니어링 with 클로드 코드』는 그 흐릿했던 감각에 구체적인 형태를 부여해준 책이었습니다.

이 책을 읽고 나서야 하네스 엔지니어링이 단순히 “AI를 더 잘 쓰는 요령”이 아니라는 점을 이해하게 되었습니다. 하네스는 모델 바깥에 역할, 권한, 도구, 검증, 관측, 협업 구조를 설계하는 일입니다. 다시 말해 AI에게 일을 시키는 기술이라기보다, AI가 일할 수 있는 환경을 만드는 기술에 가까웠습니다.

왜 모델보다 환경이 중요해지는가

책의 시작은 단일 에이전트의 한계에서 출발합니다. 이 점이 좋았습니다. 보통 AI 도구를 다루는 글은 “어디까지 할 수 있는가”를 먼저 보여주기 쉽습니다. 그런데 이 책은 오히려 혼자 일하는 AI가 왜 위험한지, 왜 자기 실수를 잘 보지 못하는지, 왜 권한이 넓을수록 문제가 커질 수 있는지를 먼저 이야기합니다.

이 문제의식은 실제 개발 업무와도 닮아 있습니다. 좋은 개발자 한 명이 모든 일을 다 할 수 있다고 해서, 모든 권한과 책임을 한 사람에게 몰아주는 조직이 좋은 조직은 아닙니다. 요구사항을 정리하는 사람, 구현하는 사람, 리뷰하는 사람, 배포를 검증하는 사람이 나뉘어 있을 때 실수를 발견할 가능성이 높아집니다. AI 에이전트도 마찬가지였습니다.

결국 문제는 모델의 지능만이 아니었습니다. 어떤 구조 안에서 일하게 할 것인가의 문제였습니다.

이 지점에서 책의 핵심 문장인 “모델이 아니라 하네스가 결과를 결정한다”는 말이 이해되었습니다. 이전에는 이 문장이 조금 선언처럼 느껴졌다면, 책을 읽고 나서는 실제 작업 구조에 관한 말로 받아들여졌습니다. 같은 모델이라도 어떤 역할을 부여받았는지, 어떤 도구를 쓸 수 있는지, 어떤 결과 기준을 따라야 하는지, 누가 검증하는지에 따라 전혀 다른 결과를 낼 수 있다는 뜻이었습니다.

에이전트, 스킬, 오케스트레이터를 분리해서 보기

책의 Part 02는 하네스를 이루는 핵심 요소를 에이전트, 스킬, 오케스트레이터로 나누어 설명합니다. 저는 이 구분이 하네스 엔지니어링의 실체를 이해하는 데 가장 중요하다고 느꼈습니다.

에이전트는 역할을 맡습니다. 단순히 “AI 하나”가 아니라, 특정한 책임 범위를 가진 작업자에 가깝습니다. 스킬은 반복 가능한 절차와 지식을 담습니다. 매번 대화로 설명할 필요 없이, 특정 상황에서 다시 꺼내 쓸 수 있는 작업 단위입니다. 오케스트레이터는 여러 에이전트와 스킬이 함께 움직일 때 전체 흐름을 조율합니다.

이렇게 나누고 나니, 제가 그동안 막연하게 “AI 워크플로우”라고 부르던 것들이 더 선명하게 보였습니다.

예를 들어 Bookgolas 작업을 할 때도, 그냥 “이슈 구현해줘”라고 말하는 것과 구조를 나누어 맡기는 것은 다릅니다. 요구사항을 정리하는 역할, 구현하는 역할, CodeRabbit 리뷰를 반영하는 역할, PR 설명을 작성하는 역할, daily ship까지 연결하는 역할은 서로 다릅니다. 이 역할들을 매번 즉흥적으로 설명하면 흐름이 흔들리지만, 파일과 스킬로 남기면 반복 가능한 작업 방식이 됩니다.

하네스 엔지니어링은 바로 이 지점을 다루고 있었습니다. AI에게 명령을 잘 내리는 것이 아니라, AI가 맡을 수 있는 역할과 재사용 가능한 절차를 설계하는 일이었습니다.

역할은 대화가 아니라 파일로 남아야 한다

Chapter 04의 에이전트 정의 파일 이야기는 이 책 전체의 핵심을 가장 선명하게 보여주는 부분이었습니다. 책에서는 에이전트 정의 파일을 단순한 설명서가 아니라 역할 계약서처럼 다룹니다.

이 표현이 인상 깊었습니다. 에이전트를 대화 중에만 정의하면, 그 역할은 세션이 끝나는 순간 사라집니다. 어제는 잘 굴러가던 팀이 오늘은 사라지는 이유가 여기에 있습니다. 어제의 대화 맥락 안에서는 역할과 기대치가 살아 있었지만, 파일로 남아 있지 않으면 오늘 다시 같은 팀을 재현하기 어렵습니다.

저도 비슷한 경험을 자주 했습니다. 어떤 날은 Hermes가 제가 원하는 방식으로 독서 기록을 정리하고, 어떤 날은 개발 채널의 맥락을 잘 이해하고, 어떤 날은 글쓰기 톤을 잘 맞춥니다. 그런데 그 맥락이 명시적인 skill이나 routing 문서로 남아 있지 않으면 다음 세션에서 다시 설명해야 합니다. 결국 좋은 결과를 만드는 것은 그날그날의 대화 감각이 아니라, 역할을 지속 가능한 파일로 남기는 구조였습니다.

이 책을 읽으며 제가 만들고 있던 channel routing, trigger map, skill 체계가 단순한 메모가 아니라 하네스의 일부라는 점을 더 분명히 이해하게 되었습니다.

스킬은 ‘알고 있는 것’이 아니라 ‘호출되는 것’이다

스킬 설계에 대한 설명도 좋았습니다. 예전에는 스킬을 “특정 작업을 잘하기 위한 지식 묶음” 정도로 생각했습니다. 하지만 책을 읽고 나니, 스킬에서 중요한 것은 지식을 얼마나 많이 담았는가가 아니라 적절한 순간에 호출되도록 설계되었는가였습니다.

Description이 호출을 결정한다는 설명이 특히 와닿았습니다. 아무리 좋은 절차와 규칙을 담고 있어도, 필요한 순간에 호출되지 않으면 없는 것과 다르지 않습니다. 반대로 모든 문서를 항상 들고 있으면 맥락이 무거워지고 판단이 흐려집니다. 필요한 순간에 필요한 만큼 펼쳐지는 구조가 중요합니다.

이 부분은 제가 Hermes를 쓰며 계속 부딪히는 문제와도 연결됩니다. 독서 리뷰를 쓸 때는 book-review skill이 필요하고, Notion에 작성할 때는 Notion API 방식이 필요하고, 개발 작업에서는 daily-ship이나 work-build 같은 skill이 필요합니다. 중요한 것은 이 모든 지식을 한꺼번에 들고 있는 것이 아니라, 상황에 맞게 정확히 불러오는 일입니다.

스킬은 저장된 문서가 아니라 실행되는 작업 기억에 가까웠습니다.

오케스트레이터는 병렬 작업의 안전장치다

오케스트레이터 장에서는 하네스가 개인 생산성을 넘어 팀 구조로 확장됩니다. 에이전트가 한두 명일 때는 단순히 역할을 나누는 것만으로도 충분할 수 있습니다. 하지만 여러 에이전트가 동시에 움직이고, 작업 사이에 의존성이 생기고, 결과를 모아 판단해야 하는 순간부터는 전체 흐름을 조율하는 구조가 필요합니다.

이 부분을 읽으며 병렬 에이전틱 코딩을 떠올렸습니다. 여러 worktree에서 Claude Code나 OpenCode를 동시에 돌리면 속도는 빨라질 수 있습니다. 하지만 역할과 경계가 명확하지 않으면 서로 다른 방향으로 구현하거나, 같은 파일을 건드리거나, 마지막에 합치기 어려운 결과가 나오기 쉽습니다.

오케스트레이션은 단순히 여러 에이전트를 띄우는 기술이 아니었습니다. 누가 어떤 작업을 맡고, 어떤 순서로 진행하고, 어떤 결과물을 서로 전달하고, 어디서 검증하고, 언제 종료할지를 정하는 안전장치였습니다. 병렬화가 생산성이 되려면, 그 전에 조율 구조가 있어야 했습니다.

메타스킬과 아키텍처 패턴이 보여준 것

Part 03에서 다루는 메타스킬과 아키텍처 패턴은 하네스 엔지니어링을 한 단계 더 추상화합니다. 처음에는 에이전트와 스킬을 직접 만듭니다. 그런데 이런 팀을 반복해서 만들다 보면, 팀을 만드는 과정 자체도 하나의 스킬이 될 수 있습니다.

도메인을 분석하고, 팀 아키텍처를 설계하고, 에이전트와 스킬을 만들고, 오케스트레이션을 구성하고, 검증하는 과정은 반복됩니다. 그렇다면 이 반복 자체를 하네스로 만들 수 있습니다. 이 발상이 재미있었습니다. 자동화의 대상이 단순 작업에서 “작업 구조를 만드는 일”로 올라가는 느낌이었습니다.

여섯 가지 아키텍처 패턴도 실용적으로 느껴졌습니다. 파이프라인, 팬아웃·팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임 같은 패턴은 AI만의 특별한 개념이라기보다 조직 설계나 분산 시스템에서 익숙한 사고방식과 닮아 있었습니다. 그래서 더 설득력 있었습니다.

특히 생성-검증 패턴과 팬아웃·팬인 패턴이 기억에 남았습니다. AI가 만든 결과를 다른 AI가 검증하거나, 하나의 문제를 여러 관점에서 본 뒤 다시 합치는 방식은 실제 개발 업무에서 바로 써볼 수 있는 구조입니다. AI에게 일을 맡길수록, 잘 만드는 역할만큼 잘 의심하는 역할도 중요해진다는 생각이 들었습니다.

하네스는 한 번 만들고 끝나는 것이 아니다

Chapter 10의 하네스 등록과 진화는 제가 실제로 가장 오래 가져가야 할 부분처럼 느껴졌습니다. 하네스는 한 번 만들어두는 설정 파일이 아니라, 계속 운영하며 진화시키는 작업 환경입니다.

처음 만든 규칙은 언제든 틀릴 수 있습니다. 실제로 써보면 호출 조건이 애매하거나, 역할이 겹치거나, 검증 단계가 부족하거나, 너무 무거워서 잘 쓰이지 않는 절차가 드러납니다. 그러면 다시 고쳐야 합니다. 변경 이력을 남기고, drift를 감지하고, 피드백을 반영하고, 필요하면 부분 재실행해야 합니다.

이 부분에서 하네스 엔지니어링은 단순 자동화와 다르다고 느꼈습니다. 자동화는 정해진 절차를 반복하는 느낌이 강하지만, 하네스는 반복을 통해 더 나은 작업 방식으로 진화해야 합니다. AI를 위한 환경을 만드는 동시에, 내가 일하는 방식을 관찰하고 개선하는 시스템이기도 했습니다.

실전 팀 사례가 개념을 현실로 끌고 온다

Part 04의 코드 리뷰 자동화 팀, 풀스택 기능 구현 팀, 레거시 마이그레이션 팀, 디버깅/RCA 팀은 앞에서 설명한 개념을 현실적인 개발 장면으로 옮겨줍니다.

코드 리뷰 자동화 팀은 생성과 검증을 분리하는 구조를 보여줍니다. 풀스택 기능 구현 팀은 하나의 기능도 여러 역할로 나눌 수 있음을 보여줍니다. 레거시 마이그레이션 팀은 반복적이고 규모가 큰 작업에서 하네스가 왜 필요한지 보여줍니다. 디버깅/RCA 팀은 단순히 문제를 고치는 것을 넘어, 원인을 추적하고 재발 방지까지 연결하는 구조를 보여줍니다.

이 사례들이 좋았던 이유는, 하네스 엔지니어링이 멋진 개념에서 끝나지 않고 실제 개발자가 마주치는 문제로 내려오기 때문입니다. “로컬에선 잘 되는데요” 같은 문제는 너무 익숙한 장면입니다. 이런 문제를 AI에게 맡길 때도 관측, 역할 분리, 검증, 책임 경계가 필요하다는 점이 자연스럽게 이해되었습니다.

좋았던 점

첫째, 이 책은 AI 도구를 낙관적으로만 다루지 않습니다. 단일 에이전트의 위험과 구조적 한계를 먼저 짚고, 그 한계를 다루기 위한 방식으로 하네스를 제안합니다. 생산성보다 신뢰성을 먼저 이야기하기 때문에 오히려 실무적으로 느껴졌습니다.

둘째, 추상적인 개념이 파일 구조로 내려옵니다. 에이전트 정의 파일, 스킬 파일, 오케스트레이터, CLAUDE.md 포인터, 변경 이력 같은 구체적인 단위가 계속 등장합니다. 덕분에 읽는 동안 “내 환경에서는 이걸 어떤 파일로 만들 수 있을까?”를 자연스럽게 떠올리게 됩니다.

셋째, 개인 생산성에서 조직 운영까지 이어지는 확장성이 있습니다. 혼자 Claude Code를 잘 쓰는 팁에서 멈추지 않고, 여러 에이전트가 협업하는 팀, 그 팀을 만드는 메타스킬, 시간이 지나며 진화하는 하네스까지 다룹니다. 그래서 개인 프로젝트에도 적용할 수 있고, 팀 단위 개발 문화에도 연결해볼 수 있습니다.

아쉬운 점

아쉬운 점도 있습니다. 우선 초급이라고 보기에는 개념의 밀도가 꽤 높습니다. Claude Code나 AI 코딩 도구를 거의 써보지 않은 독자라면 에이전트, 스킬, 오케스트레이터, 메타스킬, 실행 모드 같은 용어가 한 번에 몰려와 조금 벅찰 수 있을 것 같습니다.

또 하나는 독자의 환경에 따라 실습 체감이 다를 수 있다는 점입니다. 회사 보안 정책, 로컬 개발 환경, 사용하는 AI 도구, 모델 비용 구조에 따라 책의 패턴을 그대로 적용하기 어려운 경우도 있을 것입니다. 그래서 이 책은 정답 구조를 그대로 복사하기보다, 자기 작업 환경에 맞게 작게 실험하며 읽는 편이 좋아 보였습니다.

마지막으로, 이 분야 자체가 너무 빠르게 변하고 있습니다. Claude Code와 에이전트 생태계가 계속 바뀌는 만큼 구체적인 명령어나 도구 사용 방식은 시간이 지나며 달라질 수 있습니다. 다만 책의 핵심 메시지, 즉 모델 자체보다 모델을 둘러싼 환경과 구조가 중요하다는 관점은 꽤 오래 남을 것 같습니다.

이 책을 읽고 바꾸고 싶은 것

이 책을 읽고 나서 가장 먼저 하고 싶은 것은, 제가 이미 쓰고 있는 AI 작업 흐름을 더 명시적인 하네스로 정리하는 일입니다.

사이드 프로젝트에서는 Bookgolas, Baroguni, byungskerlog 같은 프로젝트마다 반복되는 작업이 있습니다. 이슈를 만들고, 구현 계획을 세우고, 브랜치를 나누고, PR을 만들고, 리뷰를 받고, daily ship을 하는 흐름이죠. 지금도 어느 정도 skill과 문서로 남기고 있지만, 더 엄밀하게 보면 각 단계마다 필요한 에이전트 역할과 검증 기준을 분리할 수 있을 것 같습니다.

회사 일에서도 비슷합니다. AI에게 단순히 “이거 구현해줘”라고 맡기기보다, 요구사항 정리자, 구현자, 리뷰어, 테스트 관찰자 같은 역할을 나누면 더 안전하게 쓸 수 있을 것입니다. 특히 프론트엔드 개발에서는 UI 구현 결과를 보는 눈, 제품 요구사항을 해석하는 눈, 코드 품질을 보는 눈이 모두 필요하기 때문에 단일 에이전트에게 전부 맡기기보다 역할을 분리하는 편이 더 자연스러워 보입니다.

개인적으로는 Hermes와 Obsidian, Discord, Notion을 더 잘 연결하고 싶어졌습니다. 책을 읽고, 글을 쓰고, 개발을 하고, 회고를 남기는 모든 흐름에서 “이 작업은 어떤 하네스로 반복될 수 있을까?”를 묻게 되었습니다. 단순 자동화가 아니라, 나의 일하는 방식을 파일과 규칙으로 축적하는 일에 가까워졌습니다.

마치며

『하네스 엔지니어링 with 클로드 코드』는 Claude Code 사용법 책처럼 보이지만, 실제로는 AI 시대의 작업 설계에 관한 책에 가깝다고 느꼈습니다.

저는 하네스 엔지니어링이라는 말이 중요하다는 것은 알고 있었습니다. 하지만 이 책을 읽기 전까지는 그것이 정확히 무엇으로 구성되는지, 어디서부터 설계해야 하는지, 왜 파일과 역할과 검증 루프가 중요한지까지는 선명하게 이해하지 못했습니다.

이제는 조금 더 분명해졌습니다. 하네스 엔지니어링은 AI를 똑똑하게 만드는 일이 아니라, AI가 믿고 맡길 수 있는 방식으로 일하게 만드는 환경 설계입니다. 좋은 모델을 고르는 일도 중요하고, 좋은 프롬프트를 쓰는 일도 중요하지만, 앞으로 더 중요해질 것은 그 모델이 어떤 구조 안에서 일하는가일지도 모르겠습니다.

에이전틱 코딩이 점점 더 자연스러워질수록 개발자의 역할은 사라진다기보다 조금 다른 곳으로 이동하는 것 같습니다. 코드를 직접 치는 시간은 줄어들 수 있지만, 무엇을 만들지 정하고, 어떤 구조로 맡길지 설계하고, 결과를 판단하는 책임은 더 커질 테니까요.

이 책은 그 변화의 한가운데에서 꽤 실용적인 언어를 건네줍니다.

“모델이 아니라 하네스가 결과를 결정한다.”

이 문장을 이제는 조금 더 구체적으로 이해하게 되었습니다.

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

도서 링크: https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

책 표지

이 책의 제목을 처음 봤을 때는 “클로드 코드를 잘 활용하는 방법을 알려주는 책” 정도를 떠올렸습니다. 최근 AI 관련 책들은 프롬프트를 어떻게 작성해야 하는지, 생산성을 어떻게 높일 수 있는지에 대한 내용이 많은데, 저도 비슷한 방향의 책일 거라고 생각했습니다. 그런데 책 소개를 읽어보니 생각했던 것과는 조금 달랐습니다. 이 책은 AI를 잘 사용하는 방법보다, AI가 하나의 팀처럼 일할 수 있는 환경을 어떻게 만들 것인가에 더 초점을 맞추고 있었습니다. 그래서 단순한 사용법을 배우는 책이라기보다, AI를 이용한 개발 방식을 어떻게 설계해야 하는지를 다루는 책이라는 느낌을 받았습니다.

특히 흥미로웠던 부분은 AI 모델 자체보다 그 주변의 구조를 더 중요하게 본다는 점이었습니다. 보통은 어떤 모델을 사용할지, 어떤 프롬프트를 작성할지가 가장 중요한 문제라고 생각하기 쉬운데, 이 책에서는 오히려 에이전트의 역할을 어떻게 나누고, 어떤 권한을 줄지, 결과를 어떤 방식으로 검증할지 같은 부분이 더 중요하다고 이야기합니다. 이 내용을 보면서 기존 소프트웨어 개발에서 객체의 책임을 나누고 의존성을 관리하던 방식이 자연스럽게 떠올랐습니다. 결국 AI도 혼자 모든 일을 잘하도록 만드는 것보다, 잘 협업할 수 있는 구조를 만드는 것이 더 중요할 수도 있겠다는 생각이 들었습니다.

책에서 다루는 에이전트, 스킬, 오케스트레이터 같은 개념도 흥미롭게 느껴졌습니다. 처음에는 단순히 역할을 여러 개로 나누는 정도라고 생각했는데, 소개를 읽어보니 각각이 꽤 명확한 책임을 가지고 있고, 여러 에이전트가 함께 하나의 작업을 수행하는 구조를 설명하는 것 같았습니다. 특히 코드 리뷰나 레거시 마이그레이션 같은 실제 개발 업무를 예시로 설명한다는 점이 마음에 들었습니다. 아무래도 새로운 개념은 실무 사례와 함께 봐야 왜 필요한지 이해하기 쉬운데, 그런 부분을 많이 고려한 책이라는 인상을 받았습니다.

읽으면서 계속 들었던 생각은 AI 시대에는 개발자의 역할도 조금씩 바뀌고 있다는 점입니다. 예전에는 좋은 코드를 직접 작성하는 것이 가장 중요한 능력이었다면, 이제는 AI가 일을 잘할 수 있도록 환경을 만들고, 여러 에이전트가 협업하는 방식을 설계하는 것도 중요한 역량이 될 수 있겠다는 생각이 들었습니다. AI가 코드를 작성하는 것 자체는 점점 자연스러워지고 있지만, 그 결과를 안정적으로 만들고 반복 가능한 형태로 운영하는 것은 또 다른 문제이기 때문입니다. 그런 점에서 이 책이 이야기하는 하네스 엔지니어링이라는 개념은 앞으로 더 많이 이야기될 주제라는 생각이 들었습니다.

전체적으로 보면 이 책은 클로드 코드의 기능을 소개하는 책이라기보다, AI를 활용한 개발을 어떤 방식으로 바라봐야 하는지를 이야기하는 책에 가까워 보였습니다. AI를 단순히 코드 생성 도구 정도로만 사용하고 있었다면 새로운 관점을 얻을 수 있을 것 같고, 반대로 이미 AI를 개발에 적극적으로 활용하고 있는 사람이라면 앞으로 어떤 부분을 더 고민해야 하는지에 대한 힌트를 얻을 수 있을 것 같습니다. 특히 AI와 함께 개발하는 방식이 점점 익숙해지는 지금 시점에서 한 번쯤 읽어보면 좋을 책이라는 생각이 들었습니다.

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

최근 시스템 아키텍처를 구상하거나 프로젝트를 진행할 때 '바이브 코딩(Vibe Coding)' 방식을 적극적으로 도입하고 있습니다. 개발의 주도권은 온전히 제가 쥐고 큰 구조를 설계한 뒤, 세부 구현은 AI에게 위임하는 방식입니다. 하지만 복잡한 비즈니스 로직을 다루는 실무에 AI를 깊숙이 끌어들일수록 명확한 한계에 직면합니다. 단일 모델은 근본적으로 '확률론적' 시스템이기 때문입니다.

이 책은 통제되지 않는 AI를 실무 파이프라인에 안착시키기 위해, 프롬프트 엔지니어링이라는 '설득'이 아닌 하네스(Harness)라는 '구조적 강제'를 명쾌한 해결책으로 제시합니다.

가장 인상 깊었던 대목은 "안쪽은 확률론, 가장자리는 결정론"이라는 개념입니다. 모델이 확률적으로 답을 내는 동안, 그 바깥 경계에서는 입력 확인, 권한 제한, 상태 관측이라는 결정론적 통제 장치들이 맞물려 돌아가도록 설계하는 것이 바이브 코딩 시대 엔지니어의 핵심 역량임을 짚어줍니다.

또한, 단일 모델의 한계를 극복하기 위한 6가지 아키텍처 패턴을 다루며, 특히 '계층적 위임' 패턴에서 3단계 이상의 깊이를 엄격하게 금지하는 부분은 매우 실무적입니다. 컨텍스트 손실과 병목을 막기 위해 리더를 거치지 않는 peer-to-peer 채널을 구축하는 오케스트레이션 설계는 대규모 시스템 트래픽 분산 관점에서도 훌륭한 인사이트를 제공합니다.

추상적인 이론에 그치지 않고, Airbnb의 마이그레이션 사례를 모티브로 한 '4단계 워크플로(의존 매핑 → 기준선 테스트 → 점진 변환 → 배치 검증)' 실습을 제공하는 점도 돋보입니다. 무거운 파이썬 프레임워크 대신 Git과 마크다운만으로 통제 환경을 구축하는 실용성도 훌륭합니다.

최근 Spring Camp 2026에서 저자님의 세션을 직접 들으며 하네스의 가치를 다시 한번 체감했습니다. 단순히 AI가 뱉어내는 코드를 수용하는 데 그치지 않고, 시스템의 뼈대를 직접 세우며 의사결정을 주도하는 개발자분들께 이 책을 적극 추천합니다.

#한빛미디어 #나는리뷰어다 #하네스 엔지니어링 with 클로드 코드

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

너무 좋은 책입니다. 사실 그동안 프롬프트 엔지니어링으로만 업무 및 개인 영역에 사용해왔고 하네스 엔지니어링 용어는 많이 들었지만 정확히 무슨 뜻인지는 모르고 또 새롭게 배우자니 지금 AI를 충분히 잘 사용하고 있다 생각해서 나중으로 미뤄두고 있었는데요.
하네스 엔지니어링이 무엇이고 어떻게 등장했고 왜 사용해야하는지를 명확하게 이해를 시켜줬습니다. AI의 편리함에 가려져서 안보였던 불편한 부분을 정확하게 개선시켜줍니다.

이 책은 크게 3개의 덩어리로 되어있습니다. 왜 하네스인가(1장 2장)- 어떻게 구성하는가(2부)-하네스 스킬로 구성하기(3부) 를 통해서 하네스가 가진 무기를 독자들에게 이해시키고 납득시킵니다.
마지막 실전편도 실무에서 바로 사용할 수 있는 예시를 들어 전개해나갑니다.

꼭 그동안 하네스 엔지니어링 학습을 미뤄오셨던 분들에게 추천드리고 싶습니다.

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

2022년 챗GPT가 소개되면서 프롬프트 엔지니어링(2023년) → 컨텍스트 엔지니어링(2025년) → 하네스 엔지니어링(2026년 2월)이 소개되었다. 문제 해결 관점에서 세 가지 개념은 모두 중요하지만, 소프트웨어 개발 방법론 측면에서 하네스 엔지니어링은 가장 중요하며, 개발 패러다임을 완전히 바꾸는 개념이라고 생각한다. 개발뿐만 아니라 모든 업무를 보는 패러다임을 통째로 바꿀 개념이다.

지난 3년간 개발자들은 힘든 시간을 보내고 있다. 생성형 AI가 발전하면서 가장 먼저 타격을 입은 분야가 개발자들이라고 생각한다. 적응하기 위해 끊임없이 공부하고, 공부하고, 공부하지만 새로운 개념들이 계속 나오고 있다. 물론 생성형 AI 시대에 시행착오를 거치는 과정이라고 생각하지만, 피곤한 것도 사실이다. 이제 끝이 보인다. 하네스 엔지니어링은 최근 3년간의 시행착오에 종지부를 찍는 개념이다.

이 책은 황민호 저자의 메타스킬 오픈소스 harness에 사용된 개념을 설명하고 있다. 셀 수 없을 정도로 많이 생성한 분야별 하네스의 경험이 고스란히 담겨 있다. 책에서는 하네스 엔지니어링의 개념을 시작으로 하네스를 구성하는 세 요소(에이전트 · 스킬 · 오케스트레이터), 메타스킬, 개발에서 가장 많이 사용되는 네 가지 사례, 설치 방법, 트러블슈팅까지 하네스 엔지니어링의 A to Z를 담고 있다.

메타스킬로 하네스를 구성하고 사용하는 것은 이미 해봤다. 에이전트, 스킬, 오케스트레이터가 각각 무엇인지도 알고 있었다. 그런데 막상 하네스가 제대로 동작하지 않을 때, 어디서 무엇이 잘못됐는지 짚어낼 수 없었다. 세 요소가 유기적으로 어떻게 맞물려 돌아가는지 몰랐기 때문이다. 이 책은 그 안쪽을 보여준다. 사용할 줄 아는 것과 이해하는 것은 다르다. 하네스를 직접 깎으려면 후자가 필요하다.





책에서 다루는 개념은 생각보다 쉽지 않다. 가장 어려운 이유는 지난 수십 년간 익숙해진 전통적인 소프트웨어 엔지니어링에서 AX로의 생각의 전환이 필요하기 때문이다. 챗봇 인터페이스로만 AI를 접했거나, 에이전트를 아직 경험하지 않은 독자라면 분명 러닝 커브가 있을 것이다. 클로드 코드 Max 플랜이 필요하다는 점도 입문자에게는 부담이 될 수 있다.

"하네스 엔지니어링은 완전히 새로운 것이 아니라 기존 소프트웨어 공학 패러다임이 새롭게 진화한 결과다.” — 비르기타 뵈켈러

“챗봇과 싸우지 말고, 하네스를 설계하라.” — 미셸 하시모토

"하네스를 반복해서 만들수록 확신이 생겼습니다. 단일 에이전트로 할 수 있는 일과 잘 짜인 에이전트 팀이 할 수 있는 일은 같은 선상에 있지 않습니다. 서로 다른 역할의 에이전트들이 나눠맡고 서로 검증할 때, 단일 에이전트로는 불가능했던 결과를 얻는 게 일상이 되었습니다. 이 구조는 코드에서만 작동하지 않았습니다. 리서치, 문서, 다양한 제작물도 같은 방식으로 굴러갔습니다"  — 황민호

들어가며, p4

그럼에도 하네스 엔지니어링은 소프트웨어 개발에 국한되지 않고 콘텐츠 제작, 데이터 분석, 금융, 의료, 법률 등 인간의 모든 활동에 영향을 미칠 것이다. 2026년 2월에 나온 개념이지만, 생성형 AI가 나오면서 필연적으로 나올 수밖에 없었던 개념이다. 앞으로 모두가 하네스를 구축할 수 있겠지만, 이 책은 AI가 만든 하네스에 의존하는 것이 아니라 그 초안을 활용하여 직접 통제하는 능력을 갖게 해줄 것이다. 아직 하네스 엔지니어링이 생소한 국내 독자에게 매우 시의적절한 책이다.

비 개발자와 입문자를 위한 분야별 하네스를 구축하고 실습하는 2편을 조심스레 기대해본다.



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

책을 읽게 된 계기

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

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

인사이트

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

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

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

하네스의 세 기둥

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

- `에이전트`는 "누가 이 작업을 맡는가"에 답합니다. 단순한 설정이 아니라 일종의 역할 계약서입니다. 그 에이전트가 무엇을 담당하고, 어떤 기준으로 판단하며, 누구와 어떻게 소통하는지를 명시한 살아 있는 문서입니다.

- `스킬`은 "이 작업을 어떤 절차로 하는가"에 답합니다. 반복되는 작업을 재사용 가능한 절차로 정리해둔 파일입니다. description 한 줄이 호출 여부를 결정합니다. 그래서 "무엇을 하는지"보다 "언제 이 스킬을 써야 하는지"를 명확히 적어주는 게 핵심입니다.

- `오케스트레이터`는 "이 작업을 언제, 누구와 하는가"에 답합니다. 핵심은 지시자가 아니라 지휘자라는 점입니다. 팀원 각자가 자신의 악기를 연주하도록 맡기는 것이 결국 최고의 연주를 만듭니다.

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

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

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

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

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

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

마무리

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

읽으면서 찍은 사진

<첫 하네스 구현>

<skill 실습>
 

<하네스 실전 부분 읽는 모습>
 

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

Claude Code로 개인 게임 프로젝트를 하다가 메인 로직 파일이 800줄 넘게 스파게티처럼 꼬여버린 적이 있습니다. 이 책 3장을 읽으면서 왜 그랬는지 알게 됐어요. 역할·검증 로직·조율 규칙을 한 에이전트 파일에 다 몰아넣어서 생기는 문제를 정확히 짚고 있었거든요.

누가(Agent)·어떻게(Skill)·언제누구와(Orchestrator)를 분리하라는 조언이나, 생성(Author)과 검토(Reviewer) 에이전트를 따로 둬서 같은 실수를 반복하지 않게 하는 구조가 특히 인상적이었습니다. 스킬 적용 전후를 동시에 실행해서 효과를 숫자로 비교(With/Without)하는 방법도 처음 알았습니다.

단순히 프롬프트만 잘 쓰면 된다고 생각했는데, 작업 구조 자체를 설계하는 게 더 중요할 수 있다는 걸 깨닫게 해준 책입니다. Claude Code를 쓰면서 결과물 품질이 일정하지 않다고 느끼는 개발자라면 도움이 될 것 같습니다.

클로드 코드를 쓰면서 "뭔가 내가 잘못 쓰고 있다"는 느낌이 계속 들었습니다.

버그 고쳐달랬더니 로직이 더 꼬이고, description 쓴 스킬은 제대로 호출도 안 되고.

모델 탓인가 싶었는데 이 책 읽고 나서 완전히 생각이 바뀌었습니다.

병목은 능력이 아니라 구조라는 말이 정확히 제 상황을 짚었습니다.

가장 실용적으로 와닿은 건 5장 스킬 설계 파트였습니다.

클로드는 스킬 본문이 아니라 description 한 줄만 보고 호출 여부를 결정한다는 사실을 모르고 있었거든요.

Why-First 원칙에 따라 제 스킬 description을 전부 다시 썼더니 자동 호출 성공률이 눈에 띄게 달라졌습니다.

6장 오케스트레이터 파트도 인상 깊었습니다.

리더 에이전트가 모든 메시지를 중계하는 순간 병목이 생긴다는 것,

TeamCreate·TaskCreate·SendMessage 구조로 에이전트끼리 직접 소통하게 설계해야 한다는 개념이

분산 시스템 설계 경험과 자연스럽게 연결됐습니다.

Part 4 실전편은 직접 따라해보면서 읽었는데,

코드 리뷰 자동화 팀 구성이 생각보다 빠르게 동작해서 놀랐습니다.

단점을 꼽자면 에이전트/서브에이전트/팀원 용어가 초반에 혼재해서 헷갈리는 부분이 있고,

클로드 코드를 처음 접하는 분이라면 2장 Quick Start 전에 별도 기초 학습이 필요할 수 있습니다.

그래도 클로드 코드를 어느 정도 써봤고 "왜 잘 안 되지?" 싶은 개발자라면

이 책이 가장 빠른 답을 줄 수 있다고 생각합니다.

사수 없이 AI 도구만으로 개발하는 주니어~중급 개발자,

그리고 팀에 AI를 도입하려는 리드 개발자에게 특히 추천합니다.

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

최근 생성형 AI 관련 도서를 여러 권 읽어봤지만, 『하네스 엔지니어링 with 클로드 코드』는 접근 방식이 꽤 인상적이었습니다. 대부분의 책이 프롬프트 작성법이나 특정 AI 도구의 사용법을 중심으로 설명한다면, 이 책은 처음부터 끝까지 "AI가 일하는 환경을 어떻게 설계할 것인가"라는 질문을 던집니다.

책에서 가장 오래 기억에 남는 문장은 "모델이 아니라 하네스가 결과를 결정한다."였습니다. 처음에는 다소 과감한 표현이라고 생각했지만, 책을 읽을수록 왜 저자가 이런 결론에 도달했는지 자연스럽게 이해할 수 있었습니다. 같은 모델을 사용하더라도 에이전트의 역할 분담, 스킬 설계, 오케스트레이터 구성 방식에 따라 결과가 크게 달라질 수 있다는 점을 다양한 예제와 함께 설명합니다.

특히 인상 깊었던 부분은 오케스트레이터 챕터였습니다. AI 에이전트를 많이 만드는 것이 중요한 것이 아니라, 병목이 생기지 않도록 역할을 분리하고 협업 구조를 설계하는 것이 더 중요하다는 설명이 실제 개발 조직의 협업 방식과도 닮아 있어 공감이 많이 됐습니다.

메타 하네스 스킬을 통해 반복되는 작업을 자동화하는 과정도 흥미로웠습니다. 단순히 AI에게 일을 시키는 수준을 넘어, AI 시스템 자체를 점진적으로 발전시키는 구조를 제시한다는 점에서 기존 AI 활용서와는 다른 깊이를 느낄 수 있었습니다.

또 하나 좋았던 점은 실무 중심의 구성입니다. 코드 리뷰 자동화, 풀스택 기능 구현, 레거시 마이그레이션, RCA 사례를 통해 개념을 실제 프로젝트에 어떻게 적용하는지 보여주고, 부록에서는 안티패턴과 체크리스트까지 제공해 실무에서 참고하기 좋은 레퍼런스 역할도 합니다.

다만 AI 입문자를 위한 책이라기보다는 Claude Code나 AI 코딩 도구를 어느 정도 사용해 본 개발자에게 더 적합한 내용입니다. 이미 AI를 개발 과정에 활용하고 있고, 프롬프트를 넘어 더 체계적인 AI 협업 구조를 고민하는 개발자라면 많은 인사이트를 얻을 수 있을 것입니다.

AI 시대에는 더 좋은 모델을 찾는 것보다 AI가 제대로 일할 수 있는 환경을 설계하는 능력이 점점 더 중요해질 것이라는 저자의 메시지가 오래 남았습니다. AI 에이전트 시대를 준비하는 개발자라면 한 번쯤 꼭 읽어보기를 추천하고 싶은 책입니다.

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

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

회사에서 AI를 활용한 개발 워크플로를 만들어본 적이 있다. 단순히 AI에게 “이 기능 구현해줘”라고 말하는 방식이 아니라, 정해진 흐름 안에서 작업을 진행하게 만드는 시도였다. 대략적인 흐름은 worktree를 만들고, 구현하고, 테스트를 실행하고, 리뷰를 거친 뒤, 마지막으로 PR을 생성하는 방식이었다.

처음에는 프롬프트와 Plan 모드만 잘 활용하면 충분할 거라고 생각했다. 먼저 Plan 모드에서 작업 계획을 세우게 하고, 그 계획 안에 필요한 skill을 호출하라고 명시했다. 예를 들어 실행 전에 worktree를 만들고, 구현 후 테스트를 돌리고, 리뷰를 거친 뒤 PR을 만들라는 식으로 흐름을 적어두면 AI가 자연스럽게 따라줄 거라고 기대했다.

그런데 실제로는 그렇지 않았다. Plan 모드에서는 그럴듯하게 계획을 세웠지만, 막상 실행 단계로 넘어가면 skill이 기대한 방식으로 잘 발동하지 않는 경우가 있었다. 계획에는 “worktree를 만든다”고 적혀 있는데 실제 실행에서는 빠뜨리거나, 정해둔 순서를 온전히 따르지 못하는 식이었다. AI가 계획을 이해한 것처럼 보이는 것과, 그 계획을 실행 단계에서 일관되게 지키는 것은 다른 문제였다.

흥미로웠던 건 hook을 붙였을 때였다. Plan 이후 실행 단계에서 동작하는 hook에 worktree가 생성됐는지 확인하는 조건을 넣었다. 말로 “worktree를 꼭 만들어라”라고 지시하는 대신, 실행 흐름 안에서 반드시 확인되도록 만든 것이다. 그러자 AI가 훨씬 안정적으로 흐름을 따르기 시작했다. 프롬프트에 적어둔 must 규칙보다, 실행 단계에서 강제되는 hook이 더 확실하게 작동했다.

그 경험 이후 AI 워크플로를 운영하는 일은 좋은 프롬프트를 쓰는 일이라기보다, AI가 계획을 실제로 지킬 수밖에 없는 구조를 만드는 일에 가깝다고 느꼈다.

이  책 <하네스 엔지니어링 with 클로드 코드>는 바로 그 지점을 다룬다. 클로드 코드 사용법만 설명하는 책이라기보다, AI 에이전트가 혼자 일할 때 필요한 역할, 권한, 도구, 검증, 관측 구조를 어떻게 설계할지 다루는 책에 가깝다. 책에서는 이것을 “하네스”라고 부른다. 모델의 가중치를 바꾸는 것이 아니라, 모델 바깥의 환경을 설계해서 AI 에이전트가 더 안정적으로 일하게 만드는 방식이다.

도서

인사이트 1: AI의 계획은 실행 구조 없이는 쉽게 흐트러진다

AI에게 개발 작업을 맡길 때 처음에는 계획을 중요하게 봤다. 무작정 구현하게 하기보다, 먼저 Plan 모드에서 어떤 순서로 작업할지 정리하게 하면 더 안정적일 거라고 생각했다. 실제로 계획 단계만 보면 결과가 꽤 그럴듯했다. 어떤 파일을 볼지, 어떤 순서로 구현할지, 테스트와 리뷰를 거치겠다는 내용도 잘 적었다.

하지만 문제는 그다음이었다. 계획에 적었다고 해서 실행 단계에서 자동으로 지켜지는 것은 아니었다. 특히 plan을 실행할 때 필요한 skill이 기대한 대로 발동하지 않는 경우가 있었다. 계획에는 worktree 생성이 들어가 있었지만, 실제 작업에서는 그 단계를 건너뛰거나, 이미 준비됐다고 가정한 채 진행하려는 일이 생겼다.

이때 처음에는 프롬프트를 더 자세히 쓰면 해결될 거라고 생각했다. “반드시 worktree를 생성한 뒤 작업해라”, “이 규칙은 생략하면 안 된다”처럼 must 규칙을 더 강하게 적는 식이었다. 하지만 규칙을 글로 강조하는 것만으로는 한계가 있었다. AI가 규칙을 이해하지 못했다기보다, 실행 단계에서 그 규칙이 실제로 강제되지 않았기 때문이다.

책에서 가장 먼저 연결된 부분은 “병목은 능력이 아니라 구조다”라는 관점이었다. AI가 계획을 잘 세웠는데도 실행에서 흐트러진다면, 그것은 단순히 모델이 덜 똑똑해서가 아닐 수 있다. 계획과 실행 사이를 이어주는 구조가 약한 것이다. 책에서 말하는 하네스는 모델 바깥에 권한, 도구, 검증, 관측을 설계하는 일이다. 내 경험에 대입하면, Plan 모드의 지시보다 실행 단계의 hook이 하네스에 더 가까웠다.

worktree 생성 여부를 hook에서 확인하게 만들자 AI는 훨씬 안정적으로 흐름을 따랐다. “계획에 적어둔 규칙”이 아니라 “다음 단계로 넘어가기 전에 반드시 확인되는 조건”이 되었기 때문이다. 이 경험을 통해 AI 워크플로에서 중요한 것은 AI가 계획을 잘 세우게 하는 것만이 아니라, 그 계획이 실행 중에 무너지지 않도록 구조를 만드는 일이라는 생각을 하게 됐다.

인사이트 2: must 규칙은 프롬프트보다 시스템 안에 있을 때 강해진다

AI 워크플로를 만들다 보면 “반드시 지켜야 하는 규칙”이 생긴다. 예를 들어 내 경우에는 worktree를 만든 뒤 작업해야 했고, 구현 후에는 테스트를 실행해야 했고, 리뷰를 거친 뒤에 PR을 만들어야 했다. 이런 규칙은 단순한 선호가 아니라 워크플로의 안전장치였다. 지켜지지 않으면 기존 작업 공간이 오염되거나, 검증되지 않은 코드가 PR로 올라갈 수 있었다.

처음에는 이 규칙들을 프롬프트 안에 넣었다. must, 반드시, 절대 생략하지 말 것 같은 표현을 써가며 강조했다. 하지만 프롬프트 안의 규칙은 생각보다 약했다. 작업이 길어지거나, AI가 다른 문제 해결에 집중하면 일부 규칙이 뒤로 밀렸다. 특히 Plan 모드에서 세운 원칙이 실행 단계로 넘어가면서 흐려지는 일이 있었다.

책에서 하네스를 구성하는 요소로 에이전트, 스킬, 오케스트레이터를 다룬다. 에이전트는 누가 일하는지, 스킬은 어떻게 일하는지, 오케스트레이터는 언제 누구와 어떤 흐름으로 일할지를 담당한다. 이 구분이 좋았던 이유는, 내가 프롬프트에 섞어두던 규칙들을 서로 다른 책임으로 나눠볼 수 있게 해줬기 때문이다.

worktree 생성은 단순한 문장 규칙이 아니라 실행 전제 조건에 가까웠다. 테스트 실행은 구현자의 선의에 맡길 일이 아니라 검증 단계의 책임이었다. 리뷰는 구현과 같은 역할 안에 섞어둘 수도 있지만, 그렇게 하면 AI가 자기 가정을 그대로 반복할 수 있다. PR 생성은 모든 조건이 충족된 뒤에만 가능한 마지막 단계여야 했다.

책에서 말하는 가드레일도 이 지점과 연결됐다. 가드레일은 AI에게 “조심해”라고 말하는 것이 아니라, 할 수 있는 일과 할 수 없는 일을 구조적으로 정하는 것이다. 내 경우 hook은 작은 가드레일이었다. worktree가 없으면 다음 단계로 넘어가지 못하게 하거나, 특정 must 규칙이 충족됐는지 확인하는 방식은 AI를 불신해서가 아니라, AI가 안전하게 일할 수 있는 경계를 만들어주는 일이었다.

이 경험을 하고 나니, AI에게 지켜야 할 규칙을 많이 설명하는 것보다 그 규칙이 실제 시스템 안에서 확인되도록 만드는 편이 더 중요하다는 생각이 들었다. 프롬프트는 방향을 알려줄 수 있지만, must 규칙은 가능하면 실행 구조 안에 들어가야 했다.

인사이트 3: 검증까지 잘하는 AI 하네스는 루프로 만들어진다

AI 개발 워크플로에서 가장 어려운 부분은 구현 자체보다 검증이었다. 코드를 생성하는 것은 이제 꽤 자연스러운 일이 됐다. 문제는 그 코드가 정말 요구사항을 만족하는지, 기존 구조를 망가뜨리지 않았는지, 테스트를 통과했는지, 리뷰할 만한 위험 요소가 없는지를 확인하는 일이다.

내가 만들고 싶었던 것도 단순히 코드를 잘 작성하는 AI가 아니었다. worktree 생성부터 구현, 테스트, 리뷰, PR 생성까지 이어지는 흐름을 안정적으로 지키고, 중간에 검증이 빠지지 않는 AI 하네스를 만들고 싶었다. 특히 Plan 모드에서 좋은 계획을 세우는 것과 실제 실행 단계에서 그 계획을 검증하며 따라가는 것은 별개의 문제였다.

책의 후반부에서는 메타 하네스 스킬, 6단계 파이프라인, 6가지 아키텍처 패턴을 다룬다. 파이프라인, 팬아웃·팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임 같은 패턴은 AI 작업을 단순한 대화가 아니라 하나의 시스템으로 바라보게 만든다. 이 중에서 가장 와닿았던 것은 생성-검증 구조였다. 하나의 AI가 만들고 끝내는 것이 아니라, 만든 결과를 다른 관점에서 확인하고, 필요하면 다시 수정하는 루프가 있어야 한다는 점이다.

hook을 붙였을 때 느낀 신기함도 여기와 맞닿아 있다. 검증은 AI에게 “잘 확인해줘”라고 부탁하는 단계가 아니라, 워크플로 안에서 반드시 지나가야 하는 관문이어야 했다. worktree가 있는지, 테스트가 실행됐는지, 리뷰가 완료됐는지, PR을 만들 조건이 충족됐는지 같은 것들이 말로만 존재하면 쉽게 흐려진다. 하지만 시스템의 일부가 되면 AI도 그 구조 안에서 더 안정적으로 움직인다.

책은 하네스를 한 번 만들고 끝나는 것으로 보지 않는다. 하네스 등록과 진화, 구성 불일치 감지, 피드백 반영과 변경 이력 같은 내용을 다루면서 AI 시스템도 운영하면서 바뀌어야 한다고 말한다. 이 부분도 실무 경험과 잘 맞았다. 처음부터 완벽한 AI 워크플로를 만들기는 어렵다. 실제로 어느 단계가 자주 생략되는지, 어떤 규칙이 프롬프트만으로는 지켜지지 않는지, 어떤 검증을 hook이나 별도 단계로 빼야 하는지 확인하면서 조금씩 고쳐야 한다.

결국 검증까지 잘하는 AI 하네스를 만들려면 프롬프트를 더 길게 쓰는 것만으로는 부족하다. 계획, 구현, 테스트, 리뷰, PR 생성이 각각 어떤 조건에서 실행되어야 하는지, 어떤 증거를 남겨야 하는지, 실패하면 어디로 돌아가야 하는지를 구조로 만들어야 한다. 책에서 말하는 하네스 엔지니어링은 이 지점을 설명하는 데 꽤 좋은 언어를 제공해줬다.

마무리

책을 읽고 나니, 이 책은 클로드 코드 명령어를 잘 쓰는 방법만 알려주는 책은 아니었다. 오히려 AI 에이전트를 개발 프로세스 안에서 어떻게 안전하게 일하게 할 것인지 다루는 설계서에 가까웠다. 모델을 바꾸지 않고도 모델 바깥의 권한, 도구, 역할, 검증, 관측 구조를 바꾸면 결과가 달라질 수 있다는 관점이  책 전체를 관통한다.

도서

내가 회사에서 AI 개발 워크플로를 만들면서 겪었던 문제도 결국 같은 방향이었다. Plan 모드에서 좋은 계획을 세우게 하고, 그 안에서 skill을 발동하라고 지시했지만, 실제 실행 단계에서는 그 흐름이 항상 지켜지지 않았다. 그런데 실행 단계에서 동작하는 hook에 worktree 생성 여부를 확인하도록 넣자 AI가 훨씬 안정적으로 움직였다. 그 경험을 이 책의 언어로 다시 보면, 나는 프롬프트를 고친 것이 아니라 작은 하네스를 만들고 있었던 셈이다.

AI 에이전트를 빠르게 써보는 단계에서는 좋은 모델과 좋은 프롬프트가 중요하다. 하지만 실제 업무에서 반복적으로 쓰려면 그다음이 더 중요해진다. 어떤 권한을 줄 것인지, 어떤 순서로 일하게 할 것인지, 어떤 검증을 반드시 거치게 할 것인지, 실패했을 때 어디로 되돌릴 것인지가 필요하다.

특히 AI 코딩 도구를 이미 써봤고, “계획은 잘 세우는데 실행이 흐트러진다”, “테스트와 리뷰까지 안정적으로 시키고 싶다”, “개인 도구를 넘어 팀이나 회사의 워크플로에 넣고 싶다”는 고민을 해본 사람이라면 이 책에서 연결해볼 지점이 많을 것 같다.

다만 완전한 AI 코딩 도구 입문서라고 보기는 어렵다. 클로드 코드나 AI 에이전트를 한 번도 써보지 않은 사람에게는 에이전트, 스킬, 오케스트레이터, 메타스킬 같은 개념이 조금 낯설 수 있다. 반대로 이미 AI에게 개발 작업을 맡겨봤고, 그 과정에서 흐름이 깨지거나 검증이 불안했던 경험이 있다면 이 책의 문제의식이 훨씬 선명하게 들어올 것 같다.

AI에게 일을 맡긴다는 것은 단순히 좋은 계획을 세우게 하는 일이 아니었다. 그 계획을 실제로 지키게 하는 실행 구조, 실수해도 바로 드러나는 검증 루프, 반드시 지켜야 할 규칙이 시스템 안에서 강제되는 환경을 만드는 일이었다. 이 책을 읽고 나서 내가 만들고 싶은 AI 워크플로의 목표도 조금 더 분명해졌다. 구현까지 해주는 AI가 아니라, 검증까지 잘하는 AI 하네스를 만들고 싶다.

#한빛미디어 #나는리뷰어다 #하네스엔지니어링with클로드코드 #ClaudeCode #AI에이전트 #하네스엔지니어링 #AI워크플로 #개발자동화

한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 

책을 협찬 받아 작성된 서평입니다.

도서링크: https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

얼마 전 젠슨 황이 유퀴즈에 출연한 영상을 보았다. 여러 이야기 중 가장 인상 깊었던 말은 "코딩은 어렵지만 AI는 쉽다."라는 문장이었다. AI가 기술의 격차를 줄여 누구나 자신만의 웹사이트를 만들 수 있는 시대가 올 것이라는 설명도 덧붙였다.

절반은 공감했고, 절반은 의아했다.

실무를 하다 보면 외부 연동 기술 문서에서도 "AI에게 물어보며 따라 해보세요."라는 안내를 어렵지 않게 볼 수 있다. 토스페이, 네이버페이 같은 서비스도 예외가 아니다. 이런 흐름을 보다 보면 문득 '정말 앞으로도 나 같은 개발자가 필요할까?'라는 생각이 들기도 한다.

하지만 기술의 진입 장벽이 낮아졌다고 해서 모두가 같은 품질과 속도로 서비스를 만들 수 있는 것은 아니라고 생각한다. 실제 서비스는 요구사항을 정의하고, 설계하고, 구현하고, 테스트하고, 운영하는 과정이 유기적으로 연결되어 있다. 각 단계마다 필요한 관점도, 경험도 다르다.

결국 AI를 잘 활용하는 능력은 단순히 프롬프트를 잘 작성하는 것이 아니라, 어떤 일을 누구에게 맡길지, 어떤 순서로 진행할지, 그리고 결과를 어떻게 검증할지를 설계하는 능력에 더 가까운 것이 아닐까.

이 책을 읽기 전까지 내가 가장 막막했던 부분도 바로 그것이었다.

챗GPT나 클로드와 코딩을 하다 보면, 결국 나보다 조금 더 능숙한 동료 한 명과 짝코딩을 하는 느낌이 들곤 했다. 물론 가끔은 내가 방향을 잡아줘야 하는 순간도 있었다. IT 커뮤니티에서 "이제 비개발자도 AI로 코딩합니다!"라는 이야기를 볼 때마다 속으로 '당신의 클로드와 저의 클로드는 다른 것입니까...?' 하고 생각했던 것도 사실이다.

그러던 중 AI로 하나의 팀을 만들고, 그 팀을 잘 운영하는 방법이 하네스 엔지니어링이라는 것을 알게 되었다. 마침 요즘 꽤 뜨거운 주제라 주변에서도 스터디를 하는 분들이 많았다. 스터디에 참여하려면 적어도 기본 개념은 알아야 할 것 같았고, 마침 한빛미디어를 통해 좋은 기회로 이 책을 읽게 되었다.

이 책은 하네스 엔지니어링을 처음 접하는 사람, 그리고 Claude Code의 강력한 기능인 에이전트와 오케스트레이터를 아직 활용해보지 않은 사람도 이해할 수 있도록 기초부터 차근차근 설명해 준다.

책에서 정의하는 하네스는 다음과 같다.

하네스는 누가(Agent), 어떻게(Skill), 언제, 누구와(Orchestrator)라는 세 가지 요소로 나뉘며, 이들은 독립적으로 설계되고 실행 시점에만 맞물린다.

책은 이 세 가지 요소를 중심으로 예제를 풀어간다. 먼저 포맷과 원칙을 설명하고, 좋은 예와 나쁜 예를 항상 함께 보여준다. 

단순히 따라 하게 만드는 것이 아니라 왜 이렇게 설계해야 하는지를 비교하며 설명해 주기 때문에 이해가 훨씬 쉬웠다.

좋았던 점은 개념 설명을 꽤 자세하게 해준다는 것이었다. 단순히 "AI에게 일을 시킨다." 정도에서 끝나는 것이 아니라, 역할을 왜 나누는지, 어떤 도구를 써야 하는지, 어떤 산출물이 나와야 하는지 하나씩 설명해 준다. 구현자와 검증자를 분리하는 부분도 실제 개발 프로세스와 닮아 있어서 특히 흥미로웠다.

덕분에 처음 접하는 내용인데도 고개를 끄덕이며 읽을 수 있었다. 방법론을 다루는 책은 개념을 따라가지 못해 결국 예제만 훑고 덮는 경우도 많았는데, 이 책은 적어도 '왜 이런 구조를 사용하는지'는 이해하고 넘어갈 수 있었다. AI를 단순한 질의응답 도구가 아니라 하나의 팀으로 바라보게 된 것도 큰 변화였다.

개인적으로는 초반 Chapter 4가 특히 재미있었다. 하네스를 설명하는 예시가 세계관 생성(World Builder), 캐릭터 설계(Character Designer) 같은 창작 영역이었기 때문이다. 만약 처음부터 프로그래밍 예시만 나왔다면 조금 덜 흥미로웠을지도 모르겠다. 오히려 일상적인 예시 덕분에 개념을 부담 없이 받아들일 수 있었고, 개발뿐 아니라 글쓰기나 영화 감상 같은 취미에도 적용해 보고 싶다는 생각이 들었다. 개발자를 대상으로 쓰인 책이지만, AI를 조금 더 체계적으로 활용해보고 싶은 비개발자에게도 충분히 도움이 될 것 같다.

책의 후반부에는 상황별 실습 예제가 준비되어 있다. 코드 리뷰 자동화 팀, 풀스택 기능 구현 팀, 레거시 마이그레이션 팀, 디버깅 및 RCA 팀까지 실제 업무에 응용할 수 있는 예제들이라 개발자인 내 입장에서는 꽤 흥미롭게 읽혔다.

다만 아쉬운 점도 있었다. 예제와 설명, GitHub 소스는 제공되지만 책만으로는 어떤 순서로 실행해야 하는지 바로 감을 잡기 어려웠다. 하네스 엔지니어링이나 Claude Code에 익숙한 사람이라면 자연스럽게 따라갈 수도 있겠지만, 처음 접하는 입장에서는 프로젝트를 실행하기까지 시행착오가 있었다.

또 개념 설명과 예제가 자연스럽게 이어지는 구성이다 보니, 처음에는 어디서부터 실습을 시작해야 하는지 조금 헷갈리기도 했다. 실습 예제의 시작 지점이나 준비 과정을 조금 더 명확하게 안내해 주었다면 초반 진입 장벽이 더 낮아졌을 것 같다.

처음에 조금 헤매긴 했어도 개발자로써 바로 접목 시켜볼 예제를 해볼 수 있어서 몹시 흥미로웠다. 가장 흥미로웠던 것은 '풀스택 기능 구현 팀' 예제였다. 하지만 막상 수행하다보니 또 하나의 고민이 생겼다.

이 구조를 내가 사용하는 Spring Boot와 Vue 프로젝트에는 어떻게 적용해야할까.

결국 그 답은 직접 해보는 수밖에 없었다. 그래서 책의 예제를 그대로 따라 하기보다, 내가 가장 익숙한 기술 스택으로 조금 단순화해서 구현해 보기로 했다. 거창한 서비스를 만드는 대신, JWT 인증이 포함된 로그인 기능 하나만이라도 하네스 엔지니어링 방식으로 만들어보자는 것이 이번 실습의 목표였다.

가장 처음에는 프로젝트 구조를 만들었다. 그리고 사람이 보는 프로젝트 소개인 README.md, AI가 읽는 프로젝트 가이드인 CLAUDE.md, 그리고 팀 구성과 Phase를 정의하는 문서들을 먼저 작성했다.

README.md

# Spring Boot + Nuxt JWT Login Harness

책의 풀스택 에이전트 예제를 Spring Boot + Nuxt 3 + MySQL + JWT 로그인 기능에 맞게 변형한 실습용 하네스.

## 목표

- 회원가입
- 로그인
- JWT access token 발급
- `/api/me` 내 정보 조회
- Nuxt 화면 연동

  

## 기술 스택

Backend
- Java 17
- Spring Boot 3
- Gradle
- Spring Security 6
- MyBatis
- MySQL 8
- JWT

 
Frontend
- Nuxt 3
- Vue 3
- JavaScript
- Pinia
- Axios 또는 $fetch/useFetch


Database
- MySQL
- host: localhost
- port: 3306
- database: login_demo
- username: root
- password: test1234

  

## 실습 범위

포함:
- 회원가입
- 로그인
- JWT 발급
- `/api/me` 조회
- Nuxt 로그인/회원가입/마이페이지

제외:
- Refresh Token
- OAuth
- Redis
- 권한(Role) 관리

처음이라 욕심내기보다 책의 구조를 그대로 따라가는 데 집중했다.

프로젝트 구조

login-harness-demo/
├── README.md
├── CLAUDE.md
├── 00_team_table.md -- 팀 에이전트 표
├── 01_phase_matrix.md -- 단계별 매트릭스
└── .claude/
    └── agents/
        ├── feature-pm.md
        ├── api-designer.md
        ├── ui-designer.md
        ├── db-migrator.md
        ├── backend-impl.md
        ├── frontend-impl.md
        ├── boundary-verifier.md
        └── mentor-reviewer.md

책에서는 통합테스트를 위한 에이전트가 있지만 나는 단순한 로그인 기능 구현이기 때문에 통합테스트 에이전트 대신 구현 이후 회고를 남겨주는 mentor-reviewer 에이전트를 추가했다. 사이드 프로젝트를 하다 보면 기능 구현에만 집중하느라 회고를 가장 먼저 미루게 되는 경우가 많았기 때문이다.

에이전트를 만들면서 가장 신경 쓴 부분은 책에서 여러 번 강조했던 프론트매터와 역할 정의, 에러 핸들링이었다. 역할이 명확하지 않으면 결국 AI도 사람이 시키는 대로 중구난방으로 움직인다는 걸 조금씩 느끼고 있었기 때문이다. 혹시 잘 작성했는지 확신이 서지 않을 때는 그 부분도 Claude에게 검토를 부탁했다.

이후에는 PM 에이전트에게 프로젝트를 맡겼다. 처음에는 프롬프트도 한 줄씩 보내려고 했다. 그런데 하다 보니 이것도 결국 요구사항을 전달하는 일이라는 것을 깨달았다. 실무에서도 요구사항이 명확할수록 설계가 쉬워지는 것처럼 AI도 마찬가지였다. 어떤 기능을 만들 것인지, 어디까지 구현할 것인지, 무엇을 제외할 것인지 자세하게 적어줄수록 결과가 훨씬 안정적이었다. 이 때문에 최대한 상세하게 정리해서 요구한 후에 설계로 넘어가도록 지시했다.

Phase 1에서는 API, 화면, DB 설계가 순식간에 만들어졌다. 놀라운 것은 그 다음이었다. Phase 2가 시작되자 백엔드와 프론트엔드 에이전트가 각자 역할을 나눠 구현을 시작했다. 사이드 프로젝트를 하면 환경을 잡는 데만 며칠이 걸리는 경우도 많은데, 몇 분 만에 Spring Boot와 Nuxt 프로젝트가 구성되고 JWT 로그인 기능까지 만들어지는 모습을 보니 꽤 신기했다. package.json부터 Gradle 설정까지 알아서 맞춰가는 모습을 보고 있으니 정말 여러 명의 개발자가 동시에 일하는 것 같은 기분이 들었다.

물론 한 번에 모든 것이 완벽하게 끝나지는 않았다. 백엔드 소스를 IntelliJ에서 실행해 보니 빌드가 되지 않는 문제가 생겼다. 그런데 이것도 Claude에게 그대로 보여주니 Gradle 버전을 수정하고 필요한 부분을 다시 맞춰 빌드가 가능하도록 수정해 주었다. 개발하면서 당연하게 겪던 삽질들이 꽤 많이 줄어드는 느낌이었다.

Phase 3에서는 내가 가장 기대했던 검증 단계가 시작됐다. 설계 기준과 다른 부분을 찾아 수정하는 과정이었다. 실제로 403을 반환하던 부분을 401로 수정하는 등, 검증 에이전트가 기준에 맞지 않는 부분을 찾아 다시 구현 에이전트에게 수정하도록 하는 작업이 인상적이었다.

마지막으로는 내가 추가한 mentor-reviewer 에이전트가 학습 회고를 작성해 주었다. 사이드 프로젝트를 하다 보면 기록은 항상 마지막으로 미루게 되는데, 구현이 끝난 직후 회고까지 이어지는 결과물이 공부용 프로젝트를 만들 때 특히 유용하겠다는 생각이 들었다.

짠, 결과적으로는 조금 엉성하지만 JWT 인증이 포함된 회원가입, 로그인, 로그아웃 기능이 완성됐다.

흥미로웠던 건 여기서 끝이 아니라는 점이었다. 실행도 Claude가 직접 진행했고, Playwright로 화면을 테스트한 뒤 스크린샷까지 남겨주었다. 혹시 결과가 의심스러워 DB도 확인해 달라고 했더니 회원 정보도 정상적으로 저장되어 있었다.

실습을 하고 나니 가장 크게 바뀐 건 AI를 바라보는 관점이었다.

그동안은 AI에게 "로그인 기능 만들어줘."처럼 한 번에 요청하는 경우가 많았다. 원하는 결과가 나오지 않으면 프롬프트를 조금씩 수정하고 방향을 잡아주면서 같이 짝코딩을 하는 느낌이었다. 능숙한 동료 한 명과 계속 대화를 이어가는 것 같기도 했고, 가끔은 내가 리딩을 해줘야 하는 순간도 있었다.

그런데 하네스 엔지니어링은 접근 방식 자체가 달랐다. 먼저 역할을 나누고, 각 역할이 무엇을 해야 하는지 정의한 다음 일을 맡긴다. 요구사항을 정리하는 PM이 있고, 설계하는 에이전트가 있고, 구현하는 에이전트가 있고, 마지막에는 검증하는 에이전트가 있다. 사람끼리 프로젝트를 진행할 때의 흐름을 AI에게도 그대로 가져온 느낌이었다.

이번 실습에서도 가장 신기했던 건 로그인 기능이 만들어진 것보다, 설계 기준과 맞지 않는 부분을 검증 에이전트가 찾아내고 다시 수정한 뒤 한 번 더 확인하는 과정이었다. 처음에는 로그인 하나 만드는데 이렇게까지 해야 하나 싶었는데, 기능이 조금만 복잡해져도 이런 방식이 훨씬 힘을 발하겠다는 생각이 들었다. 회사에서 운영하는 서비스처럼 여러 사람이 함께 만드는 프로젝트라면 더더욱 그럴 것 같았다.

물론 내가 만든 하네스도 아직은 많이 부족하다. 어떤 역할을 더 나누면 좋을지, 검증은 어디까지 시켜야 할지 고민도 많이 남아 있다. 그래도 한 가지는 확실히 알게 됐다. AI에게 일을 잘 시킨다는 건 프롬프트를 길게 쓰는 것이 아니라, 누구에게 어떤 일을 맡길지, 어떤 순서로 진행하고 어떻게 검증할지를 먼저 설계하는 일이라는 것을. 그동안 막연하게만 느껴졌던 하네스 엔지니어링이 이번 실습을 통해 조금은 손에 잡히는 개념이 된 것 같다.

60대인 아버지는 아직도 키오스크 사용을 어려워하신다. 하지만 제미나이로 난초 키우는 방법을 찾아보고, 영어 공부도 책보다 AI와의 대화를 더 편하게 활용하신다. 이제 AI는 누구나 큰 부담 없이 사용할 수 있는 '도우미'가 되었다.

그렇다면 앞으로는 일반인도 전문가의 도움을 받지 않고 서비스를 만드는 시대가 올지도 모른다. 하지만 그 과정에서도 결국 중요한 것은 무엇을 만들지, 왜 만들어야 하는지, 그리고 어떻게 만들어갈지를 정의하는 일이라고 생각한다.

이 책을 읽으며 AI를 사용하는 답답함이 조금씩 해소되기 시작했다. 단순히 질문을 던지는 수준을 넘어 역할을 나누고, 팀을 구성하고, 각 단계를 관리하는 방식으로 접근하니 이제는 AI 한 명이 아니라 PM도 있고, 개발자도 있고, 검증자도 있는 하나의 팀을 꾸릴 수 있겠다는 생각이 들었다.

AI와 협업하는 방법이 막연하게 느껴졌던 사람이라면, 그리고 하네스 엔지니어링의 기초를 익혀 자신만의 개발 프로세스를 만들어보고 싶은 사람이라면 이 책을 추천하고 싶다.

#한빛미디어#나는리뷰어이다#하네스엔지니어링with클로드코드

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

AI 시대는 눈 뜨면 도구 트렌드가 바뀌고, 신규 모델의 성능이 올라가면서 기존에 공들여 만든 도구들이 하룻밤 사이에 무의미해지기도 한다. 변화의 주기가 1~2년도 아니고, 불과 몇 달, 혹은 몇 주 사이에도 판도가 뒤집히는 격변의 시대다. 이런 상황에서 결국 AI를 어떻게 실무에 안정적으로 안착시킬 것일지에 대해 본질적인 고민을 하게 되는데, 이 책을 통해 단순히 모델에 국한된 것이 아닌 구조를 어떻게 가져갈 것인가에 대한 조언을 얻게 된다.

책의 전반부에서는 단일 에이전트가 가진 구조적 한계를 먼저 짚어낸다. 자신의 실수를 잘 잡지 못하는 구조라고 할 수 있는데, 한 줄로 요약하면 ‘혼자 쓴 PR을 혼자 머지하는 구조’라고 볼 수 있겠다. 책에서 언급한 리플릿(Replit)의 데이터 삭제 사례처럼 혼자 일하는 AI는 자신의 실수를 스스로 잡아내기 어렵다. 계획-작성-검증-수정의 단계를 하나의 컨텍스트 안에서 처리하기 때문에, 검토자가 없으니 초기에 누락이 있더라도 검증 단계에서도 동일한 누락이 발생할 수 있음을 설명하고 있다.

물론 모델의 성능이 올라갈수록 기존의 오케스트레이션 환경이 불필요해지는 경우도 생긴다. 최근의 흐름이라면 일전에 '하입(Hype)'을 받았던 오케스트레이션 환경을 그대로 가져다 쓰기보다, 본인의 프로젝트 도메인에 맞게 가볍게 커스텀해서 쓰는 것이 불필요한 오버헤드 없이 안정적인 결과를 얻기에 유리한 느낌이다. 실제로 최근에 기존에 사용하던 환경을 오버헤드가 생긴다는 이유로 떼어내는 추세이기도 하다.

이 지점이 바로 개발자에게 남겨진 새로운 아키텍처 설계 영역이고 그중 하나가 하네스 엔지니어링(Harness Engineering)이다. 결국 하네스라는 것은 모델의 가중치를 손대지 않고, 모델 외부에 권한(Permission), 도구 호출(Tools), 상태(State), 그리고 검증과 관측(Observability) 과정을 설계하여 에이전트가 안전하게 일할 수 있는 결정론적 환경을 구축하는 일이다. 최근에는 하네스를 넘어 루프 엔지니어링(Loop Engineering)이라는 개념이 새롭게 나오긴 했지만, 결국 본질적으로는 안쪽의 확률론적 LLM을 제어할 수 있도록 외부에 결정론적 경계선을 설계하는 일인 셈이다.

챕터 3에 이르러 본격적인 하네스 구성 요소의 책임 분리를 다룬다. 이 책의 핵심 골자는 ‘하네스는 누가(Agent), 어떻게(Skills), 언제-누구와(Orchestrator)라는 세 가지 요소로 나뉘며, 이들은 독립적으로 설계되고 실행 시점에만 맞물린다’라는 한 문장으로 요약된다.

책은 이러한 논리적인 책임 분리가 실질적으로 작동하기 위해 프로젝트 루트의 CLAUDE.md에 하네스 포인터를 등록하는 정적 규칙과 _workspace/라는 물리적인 공유 공간을 매개로 삼는 데이터 전달 프로토콜이 필수임을 말하고 있다. 확률론적 에이전트가 흔들리더라도 외부의 경계만큼은 결정론적인 파일 기반 전달 규약과 훅(Hooks)으로 묶어두어야 세션이 바뀌어도 맥락이 유실되거나 루프를 제어하는 것이 가능하기 때문이다.

멀티 에이전트나 하네스 구조를 직접 설계하고 굴려본 개발자라면 한 번쯤 느꼈을 수 있는데, AI를 개발 프로세스에 도입한다는 건 완전히 새로운 패러다임에서 시작하는 것이 아니라, 기존의 업무 프로세스를 AI에 접목시켜 속도를 끌어올리는 행위에 가깝다. 그렇기에 기존에 익숙한 단일 책임 원칙(SRP) 아래 관심사를 분리하고 전문 에이전트를 쪼개는 설계를 자연스럽게 하게 된다. 책에서 이런 내용을 언급하고 있어 상당히 공감되는 부분이었다.

책에서 소개하는 안티 패턴들 역시 익숙하다. 에이전트 한 명이 모든 역할을 맡거나, 스킬이 팀 전체를 지휘하거나, 혹은 리더가 팀원에게 일을 시키지 않고 직접 일을 처리하면서 생기는 리더 병목 등은 개발자라면 처음 접하는 이야기가 아니다. 꼭 개발자가 아니더라도 조직이나 팀 단위로 협업해 본 사람이라면 누구나 겪어봤을 일 못하는 팀의 전형적인 안티 패턴과 닮아 있다. 결국 AI 팀을 짜는 것도 인간의 협업 구조를 흡사하게 가져온다는 점에서 이미 겪어온 익숙한 안티 패턴들이 고스란히 나올 수밖에 없다.

최근에는 Codex를 주로 쓰기도 하고, 잠깐 사이에 트렌드가 바뀌고 명확한 표준이 없는 상황에서 지금 이 책을 학습한다는 게 큰 의미가 있을까 하는 회의감이 읽는 내내 스치기도 했다. 그럼에도 불구하고 이 책이 가지는 가치는 전체 하네스 구조의 메커니즘을 한눈에 훑어볼 수 있다는 점에 있다.

예를 들어, 전반부 실습에서 공유 작업 공간인 _workspace를 구축해 에이전트들이 대화 텍스트가 아닌 '공유 파일 시스템'을 매개로 리뷰 과정을 거치게 하는 구조를 먼저 체득하면, 중반부에 들어서 이 _workspace를 통해 에이전트들이 어떻게 컨텍스트 오버헤드 없이 협업하는지 대략적인 구조를 파악할 수 있다. 더 나아가 오케스트레이터의 SendMessage 도구를 통해 에이전트들이 수평적으로 통신을 주고받으며 어떻게 리더 병목을 넘어 병렬성을 확보하는지 인지하게 되는데, 그 지점에서 이 책이 단순한 툴 사용법에 머무는 것이 아니라 온전히 아키텍처에 대해 기술하는 꽤나 탄탄한 구성임을 알 수 있었다.

결국 기술 트렌드가 하룻밤 사이에 바뀌고 더 똑똑한 모델이 나오더라도, 개발자가 현재로서 해야 할 건 에이전트가 안전하게 일할 수 있는 환경을 구축해 두는 일인 것 같다. 고급 언어가 나왔을 때도 개발자의 역할이 메모리 관리에서 비즈니스 로직 설계로 옮겨갔듯, AI 시대라고 해서 개발자의 역할이 사라진 게 아니라 모델 바깥의 경계를 설계하는 영역으로 이동했다고 느끼고 있다. 물론 기술이 발전하고 시대가 변함에 따라 어떻게 바뀔지는 모른다. 게다가 앞서 말한 것처럼 모델의 성능이 발전하거나, 모델 내부의 작동 방식이 바뀜에 따라 기존의 환경이 무용해질지도 모른다. 하지만 전반적인 구조를 알고 AI를 활용하는 것과 그렇지 않은 것에는 분명한 차이가 있다고 생각한다. 이 책은 전반적인 구조를 개괄적으로나마 이해하도록 돕고 있기 때문에, 단순히 유행하는 툴 사용법이 아니라 앞으로 어떤 모델이 나오든 빠르게 실무에 적용할 수 있는 근육을 키워주는 책이라는 생각이 들었다.

#하네스엔지니어링 #나는리뷰어다 #한빛미디어

이 책을 본격적으로 읽기 전에 먼저 황민호 저자의 세미나를 들었다.

요즘 많은 사람들이 관심을 가지고 있는 '하네스'라는 것의 정체가 뭔지 궁금해서 해당 세미나를 듣게 되었다.(해당 영상은 여전히 유튜브에 공개되어 있다. https://www.youtube.com/live/_20mengjS78?si=wSBNHdLh1z7WkeE_)

이 책의 대상 독자가

• 하네스를 막상 시작하지는 못한 개발자
• 단일 에이전트 프롬프팅에서 벗어나지 못한 개발자
• 팀이나 조직에 도입을 시도하는 리드 개발자

이렇게 되어 있는데, 셋 중 고르라고 하면 나는 1번일까...애매하다.

어쨌든 공통점은 '개발자'를 대상으로 한 것이라 일반인이 보기에 내용이 어렵다. 그리고 클로드 코드를 전혀 사용해보지 않은 사람에게는 초반 진입 장벽이 있다.

하네스(Harness)는 본래 말의 몸에 씌워 힘과 방향을 제어하는 마구(馬具)를 뜻한다고 한다. 단순히 묶는 것을 넘어 "힘을 안전하게 분산시키고 목적에 맞게 이끄는 장치나 구조"를 의미한다. AI분야에서는 AI가 오류를 내지 않고 정해진 범위 내에서 안전하게 작업을 수행하도록 돕는 실행 환경 및 구조 설계를 말한다. AI를 똑똑한 말에 비유해 엉뚱한 곳으로 가지 않게 통제하는 울타리 역할을 한다.(출처: https://selectstar.ai/blog/insight/about-harness-engineering/)

즉, 하네스는 새로운 AI 기술이라기 보다는 소프트웨어 설계 원칙을 AI 환경에 적용한 것이라고 할 수 있다.

이 책은 하네스란 무엇인가부터 시작해서 하네스 구성하기 -> 하네스 스킬로 구성하기 -> 하네스 실천편으로 진행하고 있어서 시스템 설계에 집중하고 있다. 그래서 이 책을 한 문장으로 설명하면 "AI 코딩 도구의 사용법을 설명하는 책이 아니라, AI를 신뢰할 수 있는 개발 팀원으로 만들기 위한 실행 환경과 협업 구조를 설계하는 방법을 알려주는 실전 소프트웨어 아키텍처 책" 이라고 할 수 있다.

Part 04 하네스 실전편은 코드 리뷰 자동화, 풀스택 기능 구현, 레거시 마이그레이션, 디버깅/RCA 등 실제 개발프로세스를 기반으로 구성되어 있다. 즉, 코드를 작성하는 도구로 AI를 사용하는 게 아니라 AI가 개발 프로세스에 참여하도록 한다.

그리고 각 장마다 안티패턴과 응용 가이드를 조목조목 상세하게 다루어서 실제로 적용하는 데 이 부분이 큰 도움이 될 것 같다. 새로운 개념을 배우는 것만으로는 실무에 적용하기 어려운데, 흔히 저지르는 실수와 그 원인을 먼저 짚어주고 실제 활용 방법까지 이어서 설명해 주기 때문에 자연스럽게 실전 감각을 익힐 수 있다. 단순히 '무엇을 해야 하는가'를 넘어 '무엇을 하지 말아야 하는가'까지 함께 배울 수 있다는 점이 큰 장점이다.



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

하네스 엔지니어링을 어디서부터 시작해야 할지 고민하는 개발자에게 추천하고 싶은 책입니다.

책 소개에 나온 표현처럼, 이 책은 “하네스라는 단어는 들어봤지만 아직 시작하지 못한 개발자”, 그리고 “하네스 엔지니어링 체계를 팀이나 조직에 도입해보고 싶은 개발자”에게 특히 잘 맞는 책이라고 생각합니다. 저 역시 이에 가까운 독자였고, 이 책을 읽으면서 하네스 엔지니어링을 실제로 어떻게 시작할 수 있을지, 또 팀이나 조직 안에서 어떤 방식으로 적용해볼 수 있을지 감을 잡을 수 있었습니다.

이 책의 가장 큰 장점은 개념 설명에서 끝나지 않고, 실무에 도입해볼 수 있는 구체적인 실습 예시를 함께 제공한다는 점입니다. 직접 따라 해볼 수 있는 흐름이 있어 하네스 엔지니어링이라는 개념이 훨씬 구체적으로 다가왔습니다. 설명도 친절한 편이며, 부록 역시 실제 적용 과정에서 다시 참고하기 좋은 자료로 구성되어 있어 만족스러웠습니다.

읽으면서 인상 깊었던 점은 AI 에이전트를 설계하고 운영하는 방식이 사람으로 구성된 팀을 운영하는 방식과도 닮아 있다는 점이었습니다. AI 에이전트가 좋은 결과를 내기 위해서는 단순히 명령을 잘 내리는 것만으로는 부족하고, 역할과 권한, 작업 흐름, 검증 구조가 함께 설계되어야 합니다. 이는 사람의 능력이 환경이나 구조에 따라 달라질 수 있다는 점과도 연결되어 보였습니다. 이 책은 AI 에이전트를 단순한 도구가 아니라, 제대로 일할 수 있는 구조 안에서 운영해야 할 대상으로 바라보게 해주었습니다.

이 책은 읽고 끝내기보다 직접 적용해보면서 더 큰 가치를 느낄 수 있는 책이라고 생각합니다. 그래서 당분간은 새로운 책을 더 읽기보다, 이 책에서 배운 내용을 바탕으로 하네스 엔지니어링 체계를 작게라도 실무에 도입해보는 데 시간을 써보려고 합니다.

개인적으로는 2장의 30분 Quick Start를 따라 하면서, 간단한 작업에도 생각보다 많은 토큰이 사용되는 것을 보고 인상 깊었습니다. 실제 실무에 도입할 때는 단순히 AI 도구를 사용하는 것을 넘어, 비용과 맥락 관리까지 고려한 설계가 필요하겠다는 생각이 들었습니다.

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

현시대는 빅데이터와 딥러닝의 급격한 발전으로 AI가 엄청난 발전을 하였으며 현재까지도 계속 발전을 하고 있어 영화 “터미네이터”의 스카이넷이 현실로 실현될 날이 머지않아 보입니다. 이렇게 발전된 AI는 IT계열에서 뿐만 아니라 사무분야, 논문 작성, 소설 작성, 실시간 강의 정리, 농장 관리 같은 스마트팜 등등 모든 분야에서 사용되고 있는 동반자 같은 존재가 되는 추세이며 특히 IT계열 그 중에서도 프로그램 및 게임 개발에서 매우 편리함을 제공하고 있습니다. AI가 발전하기 전까지의 개발은 자신의 아이디어를 실현하기 위해서 사람이 직접 프로그래밍 언어와 전문 기술을 익혀야 하고 그래픽, 사운드 등 타 분야와의 협업을 필요시 했지만 AI가 발전된 현재는 아이디어만 있으면 누구나 프로그램 개발을 하는 1인 개발자가 될 수 있습니다. 오늘은 가장 많이 사용되고 있는 AI 에이전트 중 하나인 클로드 코드와 하네스 엔지니어링을 다뤄보겠습니다.

클로드 코드란 AI 연구 기업 앤트로픽(Anthropic)이 개발한 차세대 대형 언어 모델(LLM)이자 인공지능 어시스턴트로 자연스러운 대화 능력, 고도의 논리적 추론, 코딩 및 텍스트 편집 등 다방면에서 뛰어난 성능을 발휘하여 전 세계적으로 널리 쓰이고 있습니다.

하네스 엔지니어링은 AI 모델에게 단순히 지시를 내리는 것을 넘어, AI가 스스로 올바르게 업무를 수행할 수 있도록 돕는 실행환경과 제어 시스템을 설계하는 기술입니다.

제가 이 책을 선택한 이유는 작성자가 몇달간 다듬어 온 하네스를 만드는 스킬과 그 뒤에 있는 관점, 그리고 실제로 굴려본 하네스 팀들의 경험치를 이 책에  담겨져 있어 초보자들이 좀 더 쉽게 접근할 수 있기 때문입니다.

이 책의 특성은 하네스 엔지니어링 초보자이거나 특정 언어나 프레임워크를 깊이 알아야 할 필요 없어도 터미널에서 Git을 실행하고 마크다운 파일을 편집할 수 있으면 누구나 할 수 있게 책의 내용이 구성되었다는 점 입니다. 이 책 내 예제코드는 타임스크립트와 파이썬을 활용하지만, 어느 쪽이든 패턴만 읽어도 충분히 따라 올 수 있게 구성되어 있습니다.

구성

Part 1: 하네스란 무엇인가

Chapter 1: 왜 하네스인가

Chapter 2: 30분 Quick Start

Part 2: 하네스 구성하기 -- 에이전트 • 스킬 • 오케스트레이터

Chapter 3: 에이전트•스킬•오케스트레이터의 책임 분리

Chapter 4: 에이전트를 정의한다는 것

Chapter 5: 스킬 설계의 기술

Chapter 6: 오케스트레이터

Part 3: 하네스 스킬로 구성하기

Chapter 7: 메타 하네스 스킬과 6단계 파이프라인

Chapter 8: 여섯 가지 아키텍쳐 패턴

Chapter 9: 팀/서브에이전트/하이브리드

Chapter 10: 하네스 등록과 진화

Part 4: 하네스 실전편

Chapter 11: 코드 리뷰 자동화 팀

Chapter 12: 풀스택 기능 구현 팁

Chapter 13: 레거시 마이그레이션 팀

Chapter 14: 디버깅/RCA 팀

Part 5: 부록

Appendix A: 클로드 코드 설치 • 환경 설정

Appendix B: 안티패턴 카탈로그+도구 설계 패턴

Appendix C: 트러블 슈팅 –- 자주 막히는 실패 패턴 20선

Appendix D: 토큰 경제와 레퍼런스 아키텍쳐

파트별로 나누어 봤을때 책에서 나온 대로 파트1인 1~2장은 “왜 하네스인가”를 납득시키는 파트로 단일 에이전트가 자기 실수를 잘 보지 못 하는 문제를 짚은 후 하네스를 정의하고, 이어서 30분 안에 굴려가는 가장 작은 팁을 실제로 만드는 방법에 대해, 파트2인 3~6장은 에이전트•스킬•오케스트레이터 세 기둥을 각자의 장에서 따로 다루며 세 기둥의 책임 분리, 에이전트 정의 템플릿과 가드레임, description이 호출 여부를 결정한다는 원칙과 스킬 검증, TeamCreate•TaskCreate•SendMessage로 리더 병복을 깨는 방법과 관측•경계면에 대해, 파트3인 7~10장은 2부의 단계를 자동화하는 메타스킬을 다루며 7,8장은 설계의 골격으로 스킬이 스킬을 만든다는 관점 전환과 6단계 파이프라인, 그리고 여섯가지 아키텍쳐를 안내하며 9,10장은 운영의 골격으로 팀/서브/하이브리드 실행 보드 선택과 새 세션에서도 자동 트리거되게 하는 CLAUDE.md 포인터•구성 불일치 감지로 하네스를 유지하는 법에 대해, 파트4인 11~14장은 코드 리뷰 자동화 팀, 풀스택 기능 구현 팀, 레거시 마이그레이션 팀, 디버깅/RCA 팀 등 4개의 도메인 사례를 넣어서 각 장은 시나리오 → 팀 구성 → 워크플로 → 핵심 파일 훑어보기 → 실행 결과(생략 가능) → 응용 가이드 → 주의사항의 일곱세션으로 구성되어 있으며 그 중 하나의 사례가 OpenAI가 5개월동안 100만줄을 생성하면서 수동 코드 0줄을 유지한 사례 등에 대해, 부록은 A는 클로드 코드의 설치와 환경 설정, B는 안티패턴 카탈로그, C는 트러블슈팅 20선, D는 토큰 경제와 레퍼런스 아키텍쳐에 대해 설명하고 있습니다.

​ 

개인적인 생각으로 학습은 하네스 엔지니어링 초보자, 개발자로 취업 희망하는 분 및 하네스 엔지니어로 이직을 희망하시는 분들은 1장부터, 개발자(2년차~)분들께서는 2장부터 학습하시는 것이 좋을 것 같습니다.​

개인적으로 약간의 단점이 어쩌면 욕심일수도 있는게 좀더 많은 실습 예제 및 비즈니스 케이스가 담겨있으면 더 좋았지 않았을까라는 아쉬움이 있습니다.

​
 

저의 리뷰를 읽어주셔서 감사합니다. 다음에는 좀더 유용하고 좋은 책으로 더 나은 리뷰를 통해 여러분께 책을 소개시켜 드릴 수 있도록 더 노력하겠습니다.

​

감사합니다.​​

도서 링크: https://www.hanbit.co.kr/store/books/look.php?p_code=B2817272480

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

요즘 클로드코드에 대해 의존성이 많이 올라가면서 다양한 AI 서적들이 출간되고 있고, 그 중에서 요즘 더 뜨고 있는 하네스 엔지니어링에 대해 클로드코드와 같이 작성되 있는 이 책을 보게 되었다.

책 목차들 중점으로 내 생각을 적어보자면,

1부 . 하네스란 무엇인가

Chapter 01. 왜 하네스인가

AI 성능보다 AI가 일하는 환경을 설계하는 것이 더 중요하다는 점을 이해할 수 있었다.

Chapter 02. 30분 Quick Start

긴 설명보다 바로 실습을 통해 하네스의 개념을 빠르게 체험할 수 있어서 좋았다.

2부 . 하네스 구성하기 - 에이전트·스킬·오케스트레이터

Chapter 03. 에이전트·스킬·오케스트레이터의 책임 분리

객체지향의 역할 분리처럼 AI도 역할을 나누는 것이 유지보수에 큰 도움이 된다는 점이 인상적이었다.

Chapter 04. 에이전트를 정의한다는 것

좋은 에이전트는 프롬프트를 잘 쓰는 것이 아니라 명확한 규칙과 책임을 갖는 것이라는 점을 배웠다.

Chapter 05. 스킬 설계의 기술

스킬 하나도 재사용성과 호출 방식을 고려해 설계해야 한다는 점이 실무적이었다.

Chapter 06. 오케스트레이터

여러 AI를 협업시키는 구조를 보며 멀티스레드나 분산 시스템을 설계하는 느낌이 들었다.

3부. 하네스 스킬로 구성하기

Chapter 07. 메타 하네스 스킬과 6단계 파이프라인

AI가 AI를 만드는 구조까지 확장되는 과정을 보며 자동화의 가능성을 느꼈다.

Chapter 08. 여섯 가지 아키텍처 패턴

프로젝트 규모에 따라 다양한 하네스 구조를 선택할 수 있다는 점이 실무에 도움이 될 것 같았다.

Chapter 09. 팀 / 서브에이전트 / 하이브리드

하나의 AI에게 모든 일을 맡기기보다, 역할별 AI를 조합하는 것이 더 효율적이라는 점이 흥미로웠다.

Chapter 10. 하네스 등록과 진화

처음부터 완벽한 구조를 만드는 것이 아니라, 프로젝트에 맞게 계속 개선해 나가는 과정이 중요하다는 점을 배울 수 있었다.

4부. 실전 사례

Chapter 11. 코드 리뷰 팀

혼자 검토하는 AI보다 역할을 나눈 AI 팀이 더 신뢰할 수 있다는 점이 인상 깊었다.

Chapter 12. 풀스택 개발 팀

프론트엔드와 백엔드를 각각 담당하는 AI 협업 방식이 실제 개발 환경과 비슷해서 이해하기 쉬웠다.

Chapter 13. 레거시 마이그레이션 팀

가장 복잡한 작업도 단계별로 역할을 나누면 AI가 안정적으로 수행할 수 있다는 점을 보여주었다.

Chapter 14. 디버깅 팀 / RCA 팀

디버깅 과정에서도 여러 AI가 서로 검증하는 구조가 오류를 줄이는 데 효과적이라는 점을 알 수 있었다.

전체적으로는 "프롬프트를 잘 쓰는 법"이 아니라 "AI가 스스로 협업하도록 시스템을 설계하는 법"을 설명하는 책이라는 점이 가장 기억에 남았다.

이 책에서 가장 인상 깊었던 점은 AI 모델 자체보다 모델을 둘러싼 구조(Harness)가 결과를 결정한다는 관점이다.

지금까지는 더 좋은 모델이나 더 좋은 프롬프트에 관심이 집중되었지만, 저자는 에이전트의 역할을 분리하고, 스킬을 정의하며, 오케스트레이터를 통해 여러 AI가 협업하도록 만드는 것이 더 중요한 요소라고 설명한다.

특히 에이전트, 스킬, 오케스트레이터라는 세 가지 핵심 요소를 중심으로 시스템을 설계하는 방식은 소프트웨어 아키텍처를 공부해본 개발자라면 자연스럽게 이해할 수 있도록 구성되어 있다. 단순한 이론 설명에 그치지 않고 코드 리뷰, 디버깅, 레거시 마이그레이션, 풀스택 개발 등 실제 업무에서 활용 가능한 사례를 단계별로 다루고 있다는 점도 장점이다.

또한 Git과 Markdown만 사용할 수 있다면 실습을 따라갈 수 있도록 구성되어 있어 AI나 머신러닝을 깊게 공부하지 않은 개발자도 접근하기 쉽다는 점이다.. 모델 내부를 분석하기보다는 개발 생산성을 높이는 방법에 초점을 맞추고 있기 때문에 실무 활용도가 높아 보였다.

이 책은 프롬프트 엔지니어링을 넘어 AI 에이전트 시대를 준비하는 개발자에게 좋은 출발점이 될 수 있다. 특히 Claude Code, Cursor 같은 AI 코딩 도구를 이미 사용하고 있지만 "AI가 혼자 일하는 데 한계를 느꼈다"는 사람이라면 많은 아이디어를 얻을 수 있을 것이다.

다만 AI 에이전트라는 개념 자체가 아직 빠르게 발전하는 분야인 만큼, 책의 내용을 그대로 적용하기보다는 자신의 프로젝트에 맞게 응용하고 발전시키는 관점으로 읽는 것이 좋다고 생각한다.

전체적으로 『하네스 엔지니어링 with 클로드 코드』는 AI 활용법을 넘어 AI 협업 시스템을 설계하는 사고방식을 소개하는 책이다. 앞으로 AI 기반 개발 환경이 더욱 보편화될 것을 고려하면, 단순한 사용법을 익히는 수준을 넘어 AI 팀을 설계하는 방법을 배우고 싶은 개발자에게 충분히 읽어볼 가치가 있는 책이라고 생각한다.

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

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

재밌는 책이 한빛미디어에서 출간 됐다. 바로 "하네스 엔지니어링 with 클로드 코드"이다. 이 책은 단순히 클로드코드를 사용하는 것을 넘어서 하네스 엔지니어링까지 도달하는 내용을 다룬다. 말 그대로 클로드 코드의 모든 것을 다룬다고 할 수 있다. 더욱이 책 전반에 걸쳐 있는 내용은 꼭 클로드에 국한되는 내용은 아니라서 다른 LLM 도구를 사용하고 있더라도 많은 참고가 될 수 있다.

AI 업계는 너무 빠르게 변해서 유행이라는 게 존재하는데 적어도 이 책에 담긴 내용은 어느 정도 유행을 피해 갈 수 있게 중립을 잘 지키고 있다. 뭐 사실 진짜 AGI 세상이 온다면 하네스가 다 무슨 필요겠냐마는, 적어도 그 시간은 빠른 시일 내에 찾아오지 않을 거라고 생각하기 때문에 오랫동안 가슴에 품고 있을 수 있는 책이 되시겠다.

이 책이 특히 마음에 들었던 것은, 저자가 오랫동안 클로드 코드를 사용하면서 경험한 실전 지식이 담겨 있기 때문에 여느 이상한 강좌나 글보다 훨씬 퀄리티가 높기 때문이다. 빠르게 훑으면 지식을 차곡차곡 쌓을 수 있고, 다른 전공서적처럼 두고두고 다시 펼쳐보는 부류의 책은 아니지만 그럼에도 이 책은 이 시대에 클로드코드를 활용하는 모든 사용자에게 필독서가 될 것이다. 일독을 권한다 :) 

AI 코딩 도구를 처음 쓸 때는 대부분 모델 성능에 관심이 간다.

“어떤 모델이 더 똑똑한가”, “Claude가 좋은가, GPT가 좋은가”, “Cursor가 좋은가, Claude Code가 좋은가” 같은 질문을 먼저 하게 된다.

나도 처음에는 비슷했다.

좋은 모델을 쓰면 개발 생산성이 자연스럽게 올라갈 것이라고 생각했다. 그런데 실제 업무에 적용하려고 하면 생각보다 빨리 한계가 보인다.

AI가 코드를 잘 짜는 순간은 분명 있다.

하지만 문제는 항상 잘 짜는가, 팀의 기준에 맞게 짜는가, 자기 실수를 스스로 발견하는가, 운영 환경에서 믿고 맡길 수 있는가다.

이 책은 그 지점을 정확히 건드린다.

핵심 메시지는 단순하다.

모델은 엔진이고, 하네스는 작동 조건이다.

좋은 엔진만 있다고 차가 안전하게 달리는 것은 아니다.

어떤 도로에서 달리는지, 브레이크는 제대로 동작하는지, 계기판은 있는지, 사고가 났을 때 멈출 수 있는지가 함께 중요하다. AI도 마찬가지다. 모델 자체보다 모델 주변의 실행 구조가 결과를 크게 좌우한다.

이 책에서 말하는 하네스는 단순한 프롬프트 모음이 아니다.

프롬프트, 컨텍스트, 에이전트 역할, 스킬, 도구 권한, 오케스트레이션, 검증 루프까지 포함한 AI 에이전트 실행 구조에 가깝다.

개인적으로 이 부분이 가장 좋았다.

하네스 엔지니어링 ⊇ 컨텍스트 엔지니어링 ⊇ 프롬프트 엔지니어링

요즘 AI를 잘 쓴다고 하면 프롬프트를 잘 쓰는 것으로만 이해하는 경우가 많다. 하지만 실무에서는 프롬프트보다 더 중요한 것이 있다.

어떤 파일을 읽게 할 것인지, 어떤 명령은 실행하지 못하게 할 것인지, 결과를 누가 검토할 것인지, 실패했을 때 어떻게 되돌릴 것인지가 훨씬 중요하다.

특히 시니어 개발자 입장에서 보면 이 책은 “AI를 어떻게 잘 써볼까?”보다는 “AI를 팀의 개발 프로세스 안에 어떻게 안전하게 넣을 것인가?”에 더 가깝다.

책은 크게 네 부분으로 구성되어 있다.

Part 1에서는 왜 하네스가 필요한지 설명한다. 단일 에이전트가 자기 실수를 제대로 보지 못하는 문제, 모델만 바꿔서는 해결되지 않는 구조적 한계를 다룬다. 여기서부터 책의 방향이 분명해진다. 이 책은 AI 도구 사용법만 알려주는 책이 아니라, AI를 업무 시스템으로 다루는 책이다.

Part 2에서는 에이전트, 스킬, 오케스트레이터를 나눠 설명한다.

에이전트는 역할을 가진 작업자이고, 스킬은 특정 작업을 수행하기 위한 능력이며, 오케스트레이터는 여러 에이전트가 어떻게 협업할지 조율하는 구조다.

특히 스킬 설계 부분이 실용적이었다.

스킬은 본문을 길게 쓴다고 잘 호출되는 것이 아니라, deion 한 줄이 중요하다는 설명이 인상적이었다. AI에게 “필요하면 이걸 써”라고 알려주는 방식도 결국 설계의 영역이라는 점을 다시 생각하게 했다.

Part 3에서는 하네스를 더 체계적으로 구성하는 방법을 다룬다.

파이프라인, 팬아웃·팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임 같은 아키텍처 패턴이 나온다. 이 부분은 단순히 Claude Code를 쓰는 방법을 넘어서, 에이전트 기반 시스템을 어떻게 설계할지 고민하는 사람에게 도움이 된다.

Part 4는 실전 사례 중심이다.

코드 리뷰 자동화, 풀스택 기능 구현, 레거시 마이그레이션, 디버깅/RCA 같은 시나리오가 나온다. 실제 개발팀에서 AI를 도입할 때 가장 먼저 적용해볼 만한 영역들이라 현실감이 있었다.

다만 아쉬운 점도 있다.

완전 초보자를 위한 책은 아니다. Claude Code나 AI 코딩 도구를 한 번도 써보지 않은 사람이 읽으면 초반부터 낯설 수 있다. 설치나 환경 설정도 아주 친절한 입문서 느낌은 아니다. 어느 정도 개발 경험이 있고, AI 도구를 조금이라도 써본 사람이 읽어야 책의 의도를 제대로 이해할 수 있을 것 같다.

또한 중간중간 에이전트, 팀원, 서브에이전트 같은 용어가 비슷하게 섞여 나오는 부분은 조금 헷갈릴 수 있다. 개념 자체가 아직 업계에서 완전히 표준화된 영역은 아니다 보니 어쩔 수 없는 부분도 있지만, 처음 접하는 독자라면 한 번에 매끄럽게 읽히지는 않을 수 있다.

그럼에도 이 책의 장점은 분명하다.

AI를 “신기한 도구”가 아니라 “운영 가능한 개발 프로세스의 일부”로 바라보게 만든다.

하네스를 처음 도입한다면 개인적으로는 책의 내용을 그대로 크게 적용하기보다, 작은 단위부터 시작하는 것이 좋다고 본다.

예를 들면 코드 리뷰 자동화가 가장 적당하다.

처음부터 AI에게 코드를 수정하고 머지하게 맡기기보다는, PR을 읽고 위험 요소를 찾게 하거나, 테스트 누락 여부를 점검하게 하는 식으로 시작하는 것이다. 읽기 권한부터 주고, 쓰기 권한은 나중에 제한적으로 여는 방식이 현실적이다.

그다음에는 생성-검증 구조를 붙여볼 수 있다.

하나의 에이전트가 코드를 만들고, 다른 에이전트가 리뷰한다. 또는 구현 담당과 테스트 담당을 나눈다. 이 정도만 해도 단일 에이전트에게 모든 것을 맡기는 것보다 안정성이 올라간다.

이 책은 그런 방향을 잡는 데 좋은 참고서다.

AI 코딩 도구를 개인 생산성 향상용으로만 쓰고 있다면, 이 책을 통해 한 단계 더 나아갈 수 있다. 특히 팀 단위로 AI 도입을 고민하는 리드 개발자, 시니어 개발자, 개발 PM에게 잘 맞는다.

반대로 단순히 “Claude Code 설치해서 명령어 몇 개 써보고 싶다” 정도라면 조금 무겁게 느껴질 수 있다. 이 책은 사용법 책이라기보다 설계서에 가깝다.

읽고 나서 가장 크게 남은 생각은 이것이다.

AI를 잘 쓰는 사람은 프롬프트를 잘 쓰는 사람이 아니라,

AI가 실수해도 무너지지 않는 구조를 만드는 사람일 수 있다.

앞으로 모델은 계속 좋아질 것이다.

하지만 모델이 좋아질수록 오히려 더 중요해지는 것은 그 모델을 어디까지 믿고, 어디서 멈추게 하고, 어떻게 검증할 것인가다.

그 질문에 관심이 있다면 『하네스 엔지니어링 with 클로드 코드』는 충분히 읽어볼 만한 책이다.

하네스 엔지니어링 기초부터 알려주지만, 기본 지식이 있으면 더 잘 읽히겠어요. 

이미 하네스 엔지니어링을 쓰고 있으나 대충(?) 사용하고 있어, 매번 결과가 달라 고민인 경우 기초 지식 빠르게 쌓아 올리는데 최적이지 않을까 싶습니다. 

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

AI가 헛다리를 짚으면 우리는 으레 모델을 탓하거나 더 좋은 버전을 기다리게 됩니다. 그런데 저자는 모델은 그대로 두고 주변 환경만 바꾼 실험들을 나란히 보여줍니다. 가중치는 손도 대지 않았는데 성능이 세대 교체급으로 뛰더군요. 그러나 병목은 능력이 아니라 구조고, 그러니 답은 모델 안이 아니라 바깥에 있다는 이야기를 책을 통해 저자가 전달 합니다.

왜 혼자서는 어려울까요. 단일 에이전트는 계획하고 코딩하고 검증하고 스스로 고치는 일을 같은 모델과 같은 가정으로 한 박스 안에서 처리합니다. 그러다 보니 계획에서 놓친 가정을 검증에서도 똑같이 지나치곤 합니다. 자기가 쓴 글을 자기가 교정하고, 혼자 쓴 PR을 혼자 머지하는 구조인 셈이지요. 그래서 저자는 '하네스'를 꺼냅니다. 모델 가중치는 건드리지 않고 그 주변의 권한과 도구, 검증, 상태, 관측을 결정론으로 설계하는 일입니다. 프롬프트가 말로 설득한다면 하네스는 구조로 강제한다는 대비가 글 전체를 관통합니다.

핵심은 역할을 셋으로 나눈다는 데 있습니다. 에이전트는 '누가', 스킬은 '어떻게', 오케스트레이터는 '언제 누구와'를 맡습니다. 저자는 에이전트 정의를 설정이 아니라 역할 계약서라고 부릅니다. 파일에 적히지 않으면 그 역할은 존재하지 않는다는 원칙이라, 검토자에게서 수정 도구를 빼두면 잘못 해석하더라도 손을 댈 수 없습니다. 여럿이 모이는 대목에서는, 리더가 모든 말을 중계하는 우체국이 되는 순간 병렬이 조용히 순차로 주저앉는다는 경고가 기억에 남습니다. 리더는 중계자에서 통합자이자 관측자로 물러앉고, 팀원은 서로 직접 대화하는 동료로 올라섭니다.

뒤로 가면 실전 사례가 기다립니다. 에어비앤비가 테스트 파일 약 3,500개를 옮기는 데, 손으로 하면 18개월 걸릴 일을 6주 만에 끝내고 97%를 자동화한 이야기입니다. 비결은 더 좋은 프롬프트가 아니라 에러와 파일 상태를 다시 모델에 되먹이는 피드백 루프, 그리고 변환에서 검증, 재시도로 이어지는 상태 기계였습니다. AI 협업이 신비한 새 영역이 아니라 Saga나 work-stealing 같은 분산 시스템 위에 서 있다는 시각이 글 전체를 든든하게 받쳐 줍니다.

파인튜닝이나 모델 내부를 기대하셨다면, 저자가 처음부터 그 영역을 바깥으로 밀어 두었으니 방향이 조금 어긋날지도 모릅니다. 반대로 단일 에이전트 프롬프팅에서 좀처럼 나아가지 못해 답답하셨던 분, 에이전트를 써 보긴 했지만 왜 협업이 잘 안 되는지 궁금했던 분이라면 자리가 잘 맞습니다. git과 마크다운만 다룰 줄 알면 빈 디렉터리에서 차근차근 따라가도록 짜여 있으니, 눈으로만 읽지 마시고 직접 파일을 만들어 보시길 권합니다. 도구를 동료로 바꾸는 일은 결국 그 손끝에서 시작되니까요.

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



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

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

AI가 코드를 대신 짜주는데, 나는 왜 더 불안하고 피곤할까?

요즘 출근하자마자 터미널을 열고 'Antigravity' 나 다양한 AI 코딩 비서들을 부르는 것이 일상이 되었습니다. 질문 한 줄이면 수십 줄짜리 보일러 플레이트 코드를 뽑아내고, 내가 놓친 에러를 잡아내는 모습에 "와, 이제 코딩은 끝났구나" 싶었습니다.

하지만 기쁨도 잠시, 시간이 흐를수록 마음속 한구석에 불안감과 피로감이 쌓이기 시작했습니다.

버그를 고쳐달라고 했는데, 코드를 더 꼬아놓아 더 허비해버린 시간

몇 번 질문하지도 않았는데 컨텍스트가 꽉 차서 작업을 더 진행하지 못하고 새로운 세션을 열어야 한 상황

결국 "AI가 짠 코드는 역시 어설퍼", "아직은 멀었네"라며 모델의 지능을 탓하고, 다시 수동 코딩으로 회귀하려던 찰나에 이 책, "하네스 엔지니어링 with 클로드 코드"를 만났습니다. 책의 첫 페이지를 넘기자마자, 머리를 한 대 세게 얻어맞은 듯한 충격을 받았습니다. 내가 마주한 수많은 에러와 오버헤드는 AI의 능력이 부족해서가 아니었습니다. AI가 마음껏, 그리고 안전하게 일할 수 있는 최소한의 작업 공간조차 마련해 주지 않은 채 무작정 채찍질만 해댔던 내 무지함 때문이었습니다.

하네스(Harness)라는 낯설고도 반가운 이름

AI 에이전트 = AI 모델 + 하네스

저자는 AI 에이전트의 성능과 안정성을 결정하는 열쇠로 "하네스"를 제시합니다. 하네스를 야생마에게 채우는 고삐처럼, LLM이 시스템이나 파일 등 외부 세계와 상호작용할 때 안전하게 동작하도록 감싸는 '통제된 환경'을 의미합니다.

생각해 보면 그동안 나는 AI 비서에게 계획 짜기, 코딩하기, 테스트하기, 오류 고치기까지 모든 걸 혼자 다 하라고 떠맡겨 왔습니다. 사람이 해도 과부하가 걸려 실수 연발일 텐데, AI라고 다를 리가 없습니다. 스스로 짠 코드의 논리적 모순을 인지하지 못한 채 미완성으로 끝나버리는 것은 어찌 보면 당연한 결과였습니다.

2장의 실습 내용은 그저 챗봇 창에 툭 질문을 던질 때와는 전혀 달랐습니다. '생성자'와 '검증자' 역할을 에이전트 별로 나누고, 그 둘이 파일 기반으로 서로 의견을 주고받으며 품질을 높이는 모습을 보았을 때 짜릿했습니다. "훌륭한 목수는 연장 탓을 하지 않는다"지만, "현명한 개발자는 AI에게 엉망인 책상이 아닌, 완벽하게 정돈된 작업실(하네스)를 준다"라고 새롭게 표현을 해야 할 것 같습니다.

역할 계약서와 'Why-First'의 지혜

책은 단순한 사용법 나열에 그치지 않고, 에이전트(누가), 스킬(어떻게), 오케스트레이터(언제/누구와)로 역할을 완전히 분리해 설계하라고 조언합니다.

특히 평소에 "내가 짠 스킬은 AI 에이전트가 잘 알아서 호출해 줄까?"라는 의구심이 있었는데, 5장 "스킬 설계의 기술"에서 해답을 찾았습니다. 클로드는 세션을 시작할 때 스킬의 복잡한 본문 코드를 다 읽지 않습니다. 컨텍스트의 1%에 불과한 description 한 줄만 보고 스킬을 쓸지 말지 결정한다는 사실을 알고 무릎을 탁 쳤습니다.

저자가 알려주는 "Pushy 3단계 공식(동사 나열, 트리거 상황, 경계 조건)"을 노트에 끄적이며 내 스킬의 설명들을 수정했습니다.

전: "이 코드는 파일 포맷을 정제합니다"

후: “지정된 디렉터리의 마크다운 파일 내 모호한 기술 표현을 표준 용어로 자동 정제할 때 호출할 것”

스킬을 설계할 때 어떻게(How) 해야 하는지 꼼꼼히 적는 것보다, LLM에게 이 스킬이 왜(Why) 필요한지를 먼저 납득시키는 것이 훨씬 중요하다는 것이 "Why-First" 원칙입니다. 이는 비단 AI 스킬 설계뿐만 아니라, 현실 세계에서 동료 주니어 개발자에게 업무 지시를 내릴 때의 소통 방식과도 닮아 있어 인간적인 공감도 느끼게 해 줍니다.

리더는 우체국이 아니다: 에이전트 팀으로 일하기

팀의 시니어 개발자 한 명이 모든 팀원의 코드 리뷰와 풀 리퀘스트(PR) 승인을 도맡아 처리하느라 그 사람의 메인 작업도 밀리고, 주니어들은 병합만 하염없이 기다리며 팀 전체의 개발 속도가 뚝 떨어졌다는 에피소드를 들은 적이 있습니다.

책의 6장과 8장은 그 답답한 상황을 상기시키게 합니다. 에이전트 팀을 구성할 때도 리더 에이전트 혼자 모든 메시지를 토큰으로 받아 처리하는 오케스트레이션을 수행하면 병목이 생기고 비용이 폭발합니다. 이는 마치 모든 정보가 중개자 한 명을 거쳐야지만 작동하는 비효율적인 소통 구조와 같습니다.

책에서 제시하는 여섯 가지 아키텍처 패턴 중, 생성-검증(Generation-Verfication)과 감독자(Supervisor) 패턴은 에이전트들이 서로 직접 소통하며 작업 큐를 나누어 가질 수 있는 길을 열어줍니다.

팀 모드(Team Mode): 서로 대화하며 상호 보완하고 검증하는 든든한 관계(고품질, 높은 비용)

서브 에이전트 모드(Sub-agent Mode): 오직 리더의 명령에만 따라 빠르게 각자 행동하는 개인플레이(저품질, 낮은 비용)

이 두 모드의 장단점을 현실적으로 짚어주며 상황에 맞게 섞어 쓰는 하이브리드 전략을 읽을 때는 마치 잘 짜인 경영학 책을 읽는 듯했습니다. 이러한 에이전트 팀 오케스트레이션을 통해 제품의 출시 시점을 앞당길 수 있고, 개발자들이 단순 조율보다 고부가가치 비즈니스 로직에만 리소스를 집중할 수 있는 효과를 얻을 수 있을 것입니다.

에필로그: 지갑이 털릴 수도 있는 이유와 지속 가능한 내일

부록 D에서 비용의 99%가 출력이 아닌 '입력 토큰'에서 발생한다는 사실은 눈이 휘둥그레지게 합니다. 질문 한 번 할 때마다 대화 이력 전체를 매번 다 읽어 들여야 하는 LLM의 동작 구조를 모르고 무작정 긴 세션을 유지했던 것이 씁쓸한 표정을 짓게 합니다.

특히 변경 빈도가 낮은 '공통 시스템 지침'이나 '도구 명세(스킬 스펙)'를 컨텍스트의 최상단에 배치하여 KV 캐시(프롬프트 캐싱) 히트율을 극대화하고, 자주 바뀌는 사용자 대화는 맨 하단에 배치하는 계층형 프롬프트 설계 팁은 내 지갑과 팀의 예산을 지켜줄 것이라 기대하며 엄지손가락을 치켜세우게 합니다.

이 책은 단순히 '클로드 코드를 잘 쓰는 명령어 모음집'이 아닙니다.

AI를 내 일자리를 위협하는 두려운 존재나, 대충 써먹고 마는 신기한 장난감으로 여기는 대신 내가 설계한 아키텍처 속에서 함께 땀 흘려 일하는 진정한 개발팀 파트너로 받아들이는 법을 가르쳐 주는 따뜻하고도 날카로운 설계 지침서입니다.

#한빛미디어 #나는리뷰어다 #하네스엔지니어링with클로드코드



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

들어가며.

지난 서평에서 남겼듯, 클로드 코드를 보다 잘 활용하기 위해 '클로드 코드 마스터'를 읽었었다. 당시 아쉬웠던 점은 루프나 서브에이전트처럼 실전에서 꽤 유용한 내용이 부록에 간략히 언급되는 수준에 그쳤다는 것이었다. 남들은 클로드로 작업을 돌려두고 다른 일을 한다고 하던데, 거기에서 영감을 받아 루프 기능도 써보고 멀티 에이전트도 만들어봤지만 결과물이 아쉬웠다. 원하는 결과를 얻으려면 뭔가 계속 내가 중간에서 조율해야 한다는 느낌이 들었다. 그러다보니, 어떻게 클로드를 활용해야 결과물도 좋으면서 사람의 개입을 줄일 수 있을 지 고민이 되었다.

그러던 중 운이 좋게도 '하네스 엔지니어링 with 클로드 코드' 서적을 접하게 되었다. 하네스 엔지니어링이라는 말 자체는 많이 들어봤지만, 대충 감각적으로 어떤 것인지 어렴풋이 알 뿐, 그것이 무엇인지 제대로 설명할 수 없었다. 그래서 이번 기회를 통해 자세히 배워보고자 했다.

단일 에이전트의 한계, 그리고 하네스.

책의 첫 챕터는 '왜 하네스를 구축해야만 하는가'를 설득하는 데에 많은 공을 들인다. "병목은 능력이 아니라 구조다"라는 문장이 특히 기억에 남았다. 결국은 AI가 못해서가 아니라, AI가 혼자 일하도록 놔뒀기 때문에 생기는 문제라는 것이다. 어쩌면 당연한 말인데, 막상 클로드를 쓰면서 그 구조를 바꿀 생각을 하지 못했었다. 내 프로젝트에 어떤 구조가 좋은지, 어떤 구조가 안티 패턴인지 등 거의 전혀 알지 못했었다. 이 챕터를 읽고 나서야 단순히 에이전트 성능만 탓하고 있었던 건 아닌가 반성하게 되었다.

하네스는 결국 AI를 더 잘 사용하기 위해 일종의 아키텍처(구조)를 바꾸는 방법에 대한 것이다. AI 모델 자체를 바꾸는 것이 아니라, 그 모델 주변의 환경을 설계하는 것이 핵심이다. 책의 표현을 빌리면 'around the model'이다. 뭔가 얼핏 들었을 때 개념 자체는 어렵지 않게 느껴졌다. 다만, 그걸 실제로 어떻게 잘 구성하느냐는 꽤나 어려운 문제였고, 이 책이 그 방법을 잘 알려주고 있다고 생각한다.

인상깊었던 부분은.

이 책에서 가장 인상 깊었던 부분은 에이전트·스킬·오케스트레이터의 책임 분리였다. 처음엔 그냥 역할 구분 정도로 읽었는데, 챕터를 따라가다 보면 이게 단순한 분류가 아니라는 걸 알게 된다. "한 파일에 다 넣으면 무엇이 깨지는가"라는 소제목이 있는 부분을 읽을 때에는 소프트웨어 설계에서 중요한 단일 책임 원칙과 비슷하다고 느꼈다. 관심사를 적절히 분리해서 '누가, 어떻게, 언제 누구와'를 나누는 것이 해법이라는 말이 기억에 남았다.

6가지 아키텍처 패턴도 흥미로웠다. 파이프라인, 팬아웃·팬인, 생성-검증 등 각 패턴이 어떤 상황에서 어울리는지를 그림과 함께 친절하게 설명해준다. 패턴 이름만 나열하는 게 아니라 "이럴 때는 이런 패턴이 좋다"라는 식의 일종의 판단 기준을 준다는 점에서, 단순히 예제를 제공하는 실전서가 아니라 개념서 같은 느낌이 들었다. 책에서 에어비엔비나 클로드의 예시를 들어준 부분도 매우 흥미롭게 볼 수 있었다.

분명하게 도움되는 실전편.

Part 04는 하네스 실전편인데, 코드 리뷰 자동화, 풀스택 기능 구현, 레거시 마이그레이션, 디버깅/RCA까지 네 가지 시나리오를 소개한다. 개별 시나리오마다 각각 팀 구성 → 워크플로 → 핵심 파일 → 실행 결과 → 응용 가이드 순으로 상세하게 설명해주는데, 이전 챕터에서 들었던 충분한 개념 설명을 토대로, 이론이 실제로 어떻게 구현되는지를 보여준다. 개념 이해 없이 그냥 따라치는 건 의미가 없을 것 같아서 빠르게 넘기며 봤다. 빨리 개념을 다잡고 다시 보면서 하나하나 실전편의 내용들을 따라서 적용해보고 싶은 마음이 커졌다.

읽기 전에 알면 좋은 점.

책을 다 읽고나서 든 생각은 솔직히, 이 책은 러닝 커브가 좀 있다. 우선은 여러가지 처음 마주하게 되는 개념이 많다. 에이전트, 스킬, 오케스트레이터, 메타스킬, 하네스 루프, 아키텍처 패턴까지 처음 접하는 독자라면 Part 02~03을 따라가는 것만으로도 꽤 버거울 수 있다. (필자가 그랬다.) 클로드 코드를 한 번도 써보지 않았거나, 에이전트 개념이 완전히 낯선 독자라면 이전에 소개한 '클로드 코드 마스터'와 같은 관련 기초 서적을 먼저 읽고 오는 것을 추천한다.

반대로 클로드 코드를 어느 정도 써봤고, "좀 더 잘 쓰고 싶다"는 단계에 있는 개발자라면 무조건 추천한다. 아직까지 멀티 에이전트나 에이전트 팀을 만들어 활용해 본 적이 없는, 단일 에이전트의 한계를 느껴본 적이 있다면 더욱 그렇다.

마치며.

아직 온전히 책의 내용을 다 소화하지는 못했지만, 책을 읽는 내내 새로운 것들을 많이 배웠던 것 같다. 'AI 그냥 대충 써도 잘 해주던데, 그냥 복잡한 구조 없이 써도 되지 않아?'라고 말하는 사람들의 주장에 일부 공감했던 적이 있다. 하지만 AI를 정말 고도화해서 쓰는 방법을 보고 나니, 확실히 아는 만큼 보인다는 말이 참 맞는 말이란 생각이 들었다.

갈수록 AI를 더 잘 쓰는 사람이 우대받는 시대가 올 것은 분명하다. 이 정도만 해도 충분해라고 생각할 수도 있지만, 실은 그렇지 않을 것이다. 단순히 단일 에이전트를 잘 쓰는 것을 넘어 'AI 에이전트들이 함께 일하는 환경을 잘 설계하는 역량'이 앞으로 더 중요해질 것이라 생각한다.

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

AI 코딩 도구를 처음 접했을 때 나 스스로가 아래와 같은 기대를 했었다.

“이제 코드는 AI가 대신 짜주겠구나.”

“개발 생산성이 폭발적으로 올라가겠구나.”

“프롬프트만 잘 쓰면 원하는 결과를 바로 얻을 수 있겠구나.”

하지만 실제 업무 현장에 적용해보면 기대와 현실 사이에는 분명한 간극이 있다. AI는 코드를 빠르게 생성하지만, 그 코드가 항상 안전하거나 일관적이거나 유지보수 가능한 것은 아니다. 때로는 기존 구조를 무시하고, 테스트 없이 대규모 수정을 제안하며, 보안적으로 위험한 구현을 아무렇지 않게 만들어내기도 한다.

『하네스 엔지니어링 with 클로드 코드』는 바로 이 지점을 정면으로 다루는 책이다. 이 책은 AI에게 단순히 “코드 짜줘”라고 지시하는 수준을 넘어, AI 에이전트가 실수하지 않도록 역할, 권한, 도구, 검증, 관측 체계를 어떻게 설계해야 하는지를 설명한다.

한마디로 말하면 이 책은 AI 코딩 도구 사용법 책이라기보다, AI 에이전트를 개발 조직 안에서 안전하고 반복 가능하게 운영하기 위한 실전 아키텍처 가이드에 가깝다.

이 책에서 가장 인상적인 관점은 AI의 실패 원인을 단순히 모델 성능에서 찾지 않는다는 점이다. 많은 사람은 AI가 이상한 코드를 만들거나 잘못된 판단을 내리면 “아직 모델이 부족하다”고 생각한다. 물론 모델 성능도 중요하다. 하지만 이 책은 더 근본적인 문제를 지적한다. AI가 일하는 구조가 잘못되었기 때문에 실패한다는 것이다. 사람이 일할 때도 마찬가지다. 아무리 능력 있는 개발자라도 역할이 불명확하고, 권한이 과도하며, 리뷰 절차가 없고, 테스트 기준이 없다면 문제가 발생할 수밖에 없다. AI 에이전트도 다르지 않다. 오히려 AI는 속도가 빠르기 때문에 잘못된 구조 안에서는 더 빠르게 더 많은 문제를 생성해 낸다.

하네스는 AI 모델 자체를 바꾸는 것이 아니다. 모델 바깥에 역할, 권한, 도구, 검증, 관측 체계를 설계해서 AI가 안전하게 일하도록 만드는 실행 환경이다. 이 책은 이 개념을 중심으로 AI 에이전트 팀을 어떻게 설계하고 운영할 것인지 구체적으로 설명한다.

그동안 AI 활용의 핵심 키워드는 프롬프트 엔지니어링이었다. 어떻게 질문해야 좋은 답을 얻을 수 있는지, 어떤 문장을 넣어야 원하는 결과가 나오는지가 중요했다. 하지만 실무에서는 프롬프트만으로는 한계가 있다. 좋은 프롬프트 하나가 매번 같은 품질을 보장하지 않는다. 코드베이스가 복잡해지고, 작업 범위가 커지고, 보안과 품질 기준이 개입되면 단순한 프롬프트만으로는 안정적인 결과를 얻기 어렵다.

이 책이 제시하는 하네스 엔지니어링은 프롬프트보다 한 단계 더 넓은 개념이다. AI에게 무엇을 말할 것인가가 아니라, AI가 어떤 역할로, 어떤 도구를 사용해, 어떤 절차를 거쳐, 어떤 기준으로 검증받으며 일할 것인가를 설계한다.

즉, 프롬프트 엔지니어링이 ‘지시의 기술’이라면, 하네스 엔지니어링은 ‘AI 업무 시스템 설계의 기술’이다.

이 책의 중심에는 세 가지 구성요소(에이전트, 스킬, 오케스트레이터)가 있다.

에이전트는 특정 역할을 맡은 AI 작업자다. 예를 들어 코드 작성자, 코드 리뷰어, 테스트 담당자, 보안 검토자, 문서화 담당자처럼 역할을 나눌 수 있다. 중요한 것은 AI에게 모든 일을 한 번에 맡기지 않는다는 점이다. 사람 조직처럼 AI도 역할과 책임을 분리해야 한다.

스킬은 에이전트가 반복적으로 사용할 수 있는 업무 절차다. PR 리뷰 스킬, 로그인 기능 구현 스킬, 테스트 작성 스킬, 장애 원인 분석 스킬처럼 실무에서 반복되는 작업을 재사용 가능한 단위로 정리한다. 잘 만든 스킬은 단순한 프롬프트 모음이 아니라 조직의 업무 노하우가 축적된 프로세스 자산이 된다.

오케스트레이터는 여러 에이전트와 스킬을 조율하는 역할을 한다. 어떤 작업을 누구에게 배정할지, 어떤 순서로 진행할지, 어떤 결과를 검증할지, 언제 작업을 종료할지를 관리한다. 개발 프로젝트에서 PM, 테크리드, 스크럼 마스터가 하는 역할과 유사하다.

이 구조가 중요한 이유는 AI 활용을 ‘대화’에서 ‘업무 프로세스’로 전환하기 때문이다. 지금까지 많은 AI 활용이 채팅창에서의 단발성 요청에 머물렀다면, 하네스 엔지니어링은 AI를 실제 업무 흐름 안에 넣고 통제 가능한 방식으로 운영하게 만든다.

개인적으로 이 책에서 가장 실무적으로 와닿았던 부분은 AI 에이전트 운영에도 권한 분리와 품질 게이트가 필요하다는 관점이었다. AI에게 모든 파일을 수정하게 하고, 생성한 코드를 스스로 검토하게 하고, 테스트도 생략한 채 결과를 믿는 것은 대단히 위험하다. 이는 나혼자 개발하고, 혼자 리뷰하고, 혼자 승인하고, 혼자 배포하는 것과 다르지 않다. 특히, 이 책은 생성자와 검증자를 분리하는 구조를 강조한다. 한 에이전트가 코드를 작성하면 다른 에이전트가 리뷰하고, 또 다른 에이전트가 테스트와 보안 관점에서 검토하는 식이다. 이 방식은 실제 개발 조직의 코드 리뷰, 보안 검토, 테스트 자동화 체계와 맞닿아 있다.

보안 관점에서 현재 상황을 바라보면, AI 에이전트가 인증·인가 로직을 수정하거나, 환경 설정을 바꾸거나, 운영 데이터에 접근하거나, 민감정보를 로그로 남기는 상황은 충분히 발생할 수 있다. 따라서 AI에게도 명확한 금지 행동, 승인 절차, 검증 기준, 감사 로그, Secure Coding 가이드라인이 필요하다는 것이다.

이 책의 장점은 개념 설명에 머물지 않고 실제 개발 업무에 가까운 사례를 다룬다는 점이다. 코드 리뷰 자동화 팀, 풀스택 기능 구현 팀, 레거시 마이그레이션 팀, 디버깅과 RCA 팀 같은 구성은 실제 현장에서 바로 응용할 수 있는 시나리오다. 예를 들어 로그인 기능을 구현한다고 할 때, 단일 AI에게 “로그인 기능 만들어줘”라고 요청하는 방식은 위험하다. 로그인은 프론트엔드, 백엔드, 인증, 세션, 토큰, 예외 처리, 보안 정책, 테스트가 모두 연결된 기능이다. 이 책의 방식대로라면 요구사항 분석, 프론트엔드 구현, 백엔드 구현, 보안 검토, 테스트 작성, 통합 리뷰를 각각 역할별 에이전트에게 분리할 수 있다.

이 책은 개발자를 위한 실전 가이드이지만, PM이나 CISO 관점에서도 읽을 가치가 높다.

PM에게는 AI 에이전트를 프로젝트 수행 체계 안에 어떻게 편입할 것인지에 대한 방향성을 제시해 준다. 작업 분해, 역할 배정, 산출물 검증, 재작업 관리, 변경 이력 관리 등은 모두 프로젝트 관리의 핵심 요소들이다. AI 에이전트 팀도 결국 하나의 수행 조직처럼 설계되어야 한다느 점에서 공감되는 부분이었다.

CISO 측면에서는 AI 활용에 따른 새로운 보안통제 프레임워크를 생각하게 만들어준다. 앞으로 기업 내부에서 AI 코딩 도구와 에이전트형 자동화 도구의 사용은 더 늘어날 것이다. 이때 중요한 것은 사용을 막는 것이 아니라, 안전하게 사용할 수 있는 기준과 플랫폼을 만드는 것이다. AI 에이전트의 권한을 어디까지 허용할 것인가, 어떤 작업은 반드시 검증을 거쳐야 하는가, 민감정보와 운영환경 접근은 어떻게 통제할 것인가, 에이전트의 작업 이력은 어떻게 감사할 것인가. 이 책은 이런 질문을 기술 실무 관점에서 고민하게 만든다.

다만 이 책은 AI 코딩 도구를 처음 접하는 독자에게는 다소 어렵게 느껴질 수 있다. 클로드 코드, CLAUDE.md, 에이전트, 스킬, 오케스트레이션, 메타 하네스 같은 개념이 익숙하지 않다면 초반 진입 장벽이 있을 수 있다.

또한 책의 주제가 실무 지향적인 만큼, 단순히 AI가 무엇인지 알고 싶은 독자보다는 실제로 AI 코딩 도구를 사용하고 있거나 조직 내 도입을 고민하는 독자에게 더 적합하다. AI 입문서라기보다는 AI 활용 고도화 전략서에 가깝다.

하지만 바로 그 점이 이 책의 차별점이기도 하다. 이미 AI 도구를 사용해봤고, 그 한계와 불안정성을 경험한 사람이라면 이 책의 문제의식에 크게 공감할 것이다.

『하네스 엔지니어링 with 클로드 코드』는 AI 시대의 개발자가 어떤 방향으로 진화해야 하는지를 잘 보여주는 책이다. AI가 코드를 대신 짜주는 시대를 넘어, 이제는 AI 에이전트가 팀처럼 협업하고, 역할을 나누고, 서로 검증하며, 조직의 개발 프로세스 안에서 작동하는 단계로 이동하고 있다.

AI를 더 잘 쓰기 위해서는 더 긴 지시문을 쓰는 것이 아니라, 더 안전하고 반복 가능하며 검증 가능한 업무 구조를 설계해야 한다. 이 책은 그 구조를 어떻게 만들 것인지에 대한 실무적 답을 제시한다. AI 코딩 도구를 이미 사용하고 있다면, 이 책은 단순한 사용법 이상의 Insight를 제공해줄 것이다. 그리고 조직 차원에서 AI 에이전트 도입을 고민하고 있다면, 반드시 한 번쯤 읽어볼 만한 책이다.

#하네스엔지니어링 #클로드코드 #AI에이전트 #AI개발 #프롬프트엔지니어링 #개발자동화 #AI코딩 #ClaudeCode #소프트웨어개발 #개발자책추천 #AI도서추천 #PM추천도서 #CISO #보안아키텍처 #AI거버넌스



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

하네스 엔지니어링은 무엇인가?

AI 에이전트를 이용해서 코딩하는 것을 배우거나 이미 하고 있으신 분들은 아마 한 번쯤은 하네스 엔지니어링이라는 용어를 들어봤을 것 입니다. 그런데 하네스 엔지니어링이 무엇인지 제대로 이해하고 있는 분들은 많지 않을 것이라고 생각합니다. 그도 그럴것이 프롬프트 엔지니어링, 컨텍스트 엔지니어링 등 AI와 관련된 여러 엔지니어링 기법들이 빠르게 나오고 있어서 정말 따라가기 쉽지 않거든요.

하네스 엔지니어링은 단순히 프롬프트를 잘 적고, 스킬을 잘 만들고 하는 것이 아니고 에이전트가 일하는 환경 전체를 설계하고 운용하는 구조적인 체계입니다. 인간에게도 환경이 중요하듯 AI도 환경을 잘 만들어줘야 더 잘 일합니다. 이 책은 그런 하네스 엔지니어링과 관련된 개념과 어떻게 하네스(환경)을 잘 구축할 수 있는지에 대한 내용을 다룹니다.

에이전트, 스킬, 오케스트레이터를 만드는 법

하네스 엔지니어링을 구성하는 큰 세가지의 틀 에이전트, 스킬, 오케스트레이터를 만드는 법을 자세히 다룹니다. 책을 읽어보니 이게 생각했던 것보다 정교하게 만들어야 하더군요. 조금만 틀어져도 스킬이 동작하지 않고 에이전트가 엉뚱한 짓을 하고 토큰만 잡아먹을 확률이 있습니다.

이 책에서 좋았던 점은, 책이니까 당연히 어떻게 하는 것이 좋은 것인가 자세하게 알려주는 것 이외에 독자가 실수할 수 있는 나쁜 예제, 안티 패턴들을 다뤄주는 것이 좋았습니다.

모범적인 방법 이외에 하면 안되는 방법까지 배울 수 있어서 시행착오를 줄 일수 있습니다. 시행착오를 겪으면서 배우는 방법도 좋지만, 토큰 사용은 비용이 지출되기 때문에 겪지 않을 수 있다면 굳이 겪지 않아도 된다고 생각합니다.

추천 독자

AI 에이전트를 이용해서 코딩을하고 있는데 하네스를 만들어 본 적이 없고 관심이 있다면 누구나 읽어보면 도움이 될 것 같습니다. 책은 클로드 코드를 이용하고 있지만 환경을 만드는데 필요한 개념은 어떤 에이전트에도 적용이 된다고 봅니다. 물론 만드는 방법적인 부분에서는 조금씩 차이는 있을 겁니다만 책에서 배운 내용을 통해 비슷하게 구축할 수 있다고 생각합니다.

총평

저자가 고민을 많이 하고 실험도 많이 해본 느낌이 나는 책이었습니다. AI 에이전트 엔지니어링 관련해서 정말 변화가 빠른 요즘입니다. AI에게 일을 제대로 할 수 있도록 환경을 잘 세팅해준다는 관점에서 하네스 엔지니어링은 매력적인 것 같습니다. 또 어떤 새로운 기법이 빠르게 나올지 모르겠지만, 하네스 엔지니어링을 빠르게 배워보고 싶다면 읽어보길 추천합니다.

#한빛미디어, #나는리뷰어다, #하네스 엔지니어링 with 클로드 코드

AI 프롬프트를 잘 쓰는 단계를 넘어, AI가 안전하고 반복 가능하게 일할 수 있는 시스템 아키텍처를 고민하는 책입니다. 실제 업무 프로세스에 AI를 도입하려는 개발팀에게 강력히 추천합니다. AI가 제대로 일할 수 있는 최적의 환경과 구조를 설계하는 데 명쾌한 해답을 얻을 수 있습니다.

사내 세미나를 듣고 최근 AI를 활용한 개발 방법에 관심이 많아지면서 여러 자료를 찾아보고 있었는데, 그 과정에서 『하네스 엔지니어링 with 클로드 코드』를 읽게 됐다.

예전에는 AI에게 단순히 질문을 던지고 답변을 받는 수준으로 활용했다면, 최근에는 실제 개발 업무에 AI를 어떻게 연결하고 활용할 수 있는지가 더 중요해지고 있다. 이 책은 그런 관점에서 꽤 실무적인 내용과 최신 트렌드에 대한 내용을 담고 있다는 인상을 받았다.

​처음에는 클로드 코드를 사용하는 방법 정도를 설명하는 입문서라고 생각했다. 그런데 읽어보니 단순히 명령어를 소개하는 수준이 아니라 AI를 개발 프로세스 안에서 어떻게 활용할 것인지에 대한 접근법을 다루고 있었다.

특히 작업을 잘게 나누고, AI가 수행할 수 있는 영역과 사람이 검토해야 하는 영역을 구분하는 내용이 인상적이었다.

개발 경험이 있는 사람이라면 "AI가 코드를 써주는데 왜 결과물이 들쑥날쑥하지?"라는 고민을 한 번쯤 해봤을 텐데, 그런 부분에 대한 힌트를 얻을 수 있었다.

책에서 소개하는 예제들은 실제 업무 상황을 어느 정도 가정하고 있어서 이해하기 쉬웠다. 단순히 "이 프롬프트를 입력하세요"가 아니라,

- 요구사항 정리

- 작업 단위 분해

- 코드 생성

- 검토 및 수정

- 반복 개선

과정을 단계별로 설명해 주기 때문에 AI를 처음 실무에 적용해 보는 사람도 흐름을 따라가기 수월하다.

특히 클로드 코드가 어떤 상황에서 강점을 보이는지, 반대로 사람이 반드시 확인해야 하는 부분은 무엇인지 설명한 점이 좋았다.

책을 읽으면서 여러 내용이 있었지만 개인적으로는 코드 리뷰 자동화 관련 내용이 가장 기억에 남았다.

나는 개발을 한 지 5년 정도 됐는데, 사실 아직까지 AI에게 모든 개발을 맡기는 스타일은 아니다. 새로운 기능을 개발할 때도 AI에게 처음부터 끝까지 맡기기보다는 구글 검색을 하거나 오픈소스 코드를 참고하면서 구현하는 경우도 꽤 많다.

그래서 요즘 많이 이야기하는 바이브 코딩도 엄청 적극적으로 활용하고 있지는 않다.

대신 AI는 주로 간단한 함수를 작성할 때나, 내가 작성한 코드에 대한 리뷰를 받을 때 활용하는 편이다. 특히 "이 코드에서 개선할 점이 있을까?", "예외 처리가 부족한 부분은 없을까?" 같은 질문을 자주 던진다.

그런 관점에서 봤을 때 책에서 소개하는 코드 리뷰 자동화 방법은 상당히 실용적이었다.

단순히 AI에게 "코드 리뷰해줘"라고 요청하는 수준이 아니라, 어떤 기준으로 리뷰를 진행할지, 어떤 관점으로 피드백을 받으면 좋은지, 그리고 반복적으로 사용할 수 있는 형태로 어떻게 구성할 수 있는지까지 설명해 주는 부분이 도움이 됐다.

실제로 개발을 하다 보면 코드를 작성하는 시간보다 검토하고 수정하는 시간이 더 오래 걸리는 경우도 많은데, 이런 과정에서 AI를 보조 도구로 활용하는 방법을 구체적으로 설명해 준다는 점이 좋았다.

개인적으로는 코드를 생성하는 영역보다 코드 품질을 높이는 영역에서 AI의 활용 가치가 더 크다고 생각하는데, 그런 생각과도 잘 맞아떨어지는 내용이었다.

개인적으로는 다음과 같은 분들에게 도움이 될 것 같다.

- AI 코딩 도구를 제대로 활용해 보고 싶은 개발자

- 클로드 코드를 처음 접하는 사람

- 바이브 코딩에 관심 있는 사람

- 생산성을 높일 방법을 찾고 있는 IT 실무자

반면 프로그래밍 경험이 전혀 없는 분들에게는 다소 어렵게 느껴질 수도 있다.

『하네스 엔지니어링 with 클로드 코드』는 단순히 AI 사용법을 알려주는 책이라기보다 AI와 함께 개발하는 방식을 설명하는 책에 가깝다.

최근 생성형 AI를 활용한 개발이 빠르게 확산되고 있는 만큼, 관련 흐름을 이해하고 싶다면 한 번 읽어볼 만한 입문서라고 생각한다.

AI에게 일을 시키는 방법보다 AI와 협업하는 방법에 더 초점을 맞춘 점이 인상적이었다. 개발 생산성을 높이는 데 관심이 있는 사람이라면 도움이 될 만한 내용이 꽤 많다.

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

AI 코딩 도구를 사용하다 보면 원하는 결과가 나오지 않을 때 가장 먼저 프롬프트를 고치게 된다. 지시를 더 자세히 쓰거나, 예시를 추가하거나, 더 성능이 좋은 모델로 바꾸면 결과도 좋아질 것이라고 생각하기 쉽다. 나 역시 AI 에이전트의 성능을 모델과 프롬프트의 문제로만 보는 편이었다.

그런 점에서 『하네스 엔지니어링 with 클로드 코드』가 반복해서 이야기하는 “모델이 아니라 하네스가 결과를 결정한다”라는 문장은 꽤 인상적으로 다가왔다. 이 책은 AI 모델 자체를 개선하는 방법보다, 모델 주변에 역할과 권한, 도구, 검증 절차를 어떻게 배치해야 하는지를 다룬다. 한 명의 뛰어난 AI에게 모든 일을 맡기는 것이 아니라, 서로 다른 역할을 가진 에이전트들이 협업하고 검증하도록 만드는 책이다.

읽는 것과 직접 만들어보는 것은 확실히 달랐다

책에서 가장 먼저 좋았던 부분은 2장의 30분 Quick Start였다.

새로운 개념을 설명하는 기술서는 보통 정의와 구조를 충분히 설명한 뒤 마지막에 실습으로 넘어간다. 하지만 이 책은 비교적 초반부터 빈 디렉터리에서 에이전트 2명과 스킬 하나를 직접 구성하게 한다. 같은 프롬프트를 하네스 없이 실행했을 때와 하네스를 적용했을 때의 결과를 비교하며, 구조가 산출물에 어떤 차이를 만드는지 확인하도록 되어 있다.

하네스, 에이전트, 스킬, 오케스트레이터 같은 단어만 보면 처음에는 거창한 시스템처럼 느껴진다. 그런데 마크다운 파일을 만들고 역할을 나누는 작은 실습부터 시작하니 개념이 훨씬 구체적으로 다가왔다. 책을 읽으며 “대략 이런 구조구나”라고 이해하는 것과 실제로 디렉터리와 파일을 구성해보는 것은 확실히 달랐다.

또한, 왜 역할을 분리해야 하는지, 왜 에이전트마다 출력 형식을 정해야 하는지, 검증 절차가 없으면 어떤 문제가 생기는지를 결과물의 차이로 보여준다. 초반에 직접 손을 움직여본 경험이 이후 장에서 나오는 개념을 이해하는 토대가 된다는 점이 좋았다.
 

다음으로 가장 흥미로웠던 내용은 7장의 메타 하네스 스킬이었다.

처음에는 필요한 작업마다 에이전트와 스킬을 직접 만들면 된다고 생각할 수 있다. 하지만 코드 리뷰 팀, 문서 작성 팀, 마이그레이션 팀을 반복해서 만들다 보면 파일 구조와 검증 방식, 역할 정의에서 비슷한 패턴이 나타난다. 책은 이 반복을 다시 하나의 스킬로 추상화한다. 즉, 작업을 수행하는 스킬을 만드는 데서 더 나아가 새로운 팀과 스킬을 설계하는 스킬을 만드는 것이다.

책에서는 이를 도메인 분석, 팀 아키텍처 설계, 에이전트 및 스킬 생성, 오케스트레이션, 검증으로 이어지는 6단계 파이프라인으로 설명한다. 먼저 해결하려는 문제를 분석하고, 필요한 역할을 나누고, 각 역할에 권한과 출력 형식을 부여한 뒤 마지막에 실제로 하네스가 의도대로 동작하는지 검증한다.

여섯 번째 팀을 만들면서 같은 작업 패턴이 반복되고 있음을 발견했다는 설명도 현실적으로 느껴졌다. 개발 과정에서 반복되는 코드를 함수나 클래스로 추상화하듯, 반복되는 에이전트 팀 구성 과정도 메타스킬로 추상화할 수 있다는 것이다. “반복이 추상화의 단서가 된다”라는 익숙한 개발 원칙이 AI 에이전트 설계에도 그대로 적용된다는 점이 흥미로웠다.
 

Part 4의 코드 리뷰 자동화 팀 사례는 앞에서 배운 개념이 실제 구조로 어떻게 연결되는지를 보여준다.

책의 예시에서는 하나의 에이전트가 코드를 읽고 수정까지 모두 수행하지 않는다. 먼저 코드의 규칙과 정적 문제를 확인하는 정적 분석 에이전트, 경계와 책임 분리, 의존성 방향을 살펴보는 설계 검토 에이전트, 보안 취약점과 시크릿 노출 가능성을 확인하는 보안 감사 에이전트가 같은 변경 사항을 서로 다른 관점에서 검토한다.

이 세 리뷰어는 기본적으로 읽기 권한만 가진다. 코드를 직접 수정하지 않고 각자의 검토 결과를 문서로 남긴다. 이후 리팩터링 에이전트가 세 결과를 전달받아 구체적인 패치를 제안한다. 이 에이전트도 전체 프로젝트를 자유롭게 수정하는 것이 아니라 지정된 패치 경로에만 결과를 만들도록 제한된다.

또한 리더 에이전트가 모든 내용을 다시 리뷰하는 구조가 아니라, 팀 구성과 작업 할당, 결과 수집과 통합에 집중한다. 각 리뷰 에이전트는 자신의 결과를 메시지로 전달하고, 오케스트레이터가 전체 흐름을 관리한다. 리더가 모든 판단과 전달의 중간에 끼어드는 병목을 줄이면서도 최종 결과는 한곳에 모이도록 설계한 것이다.

개념에서 운영까지 이어지는 구성이 좋았다

이 책의 장점은 에이전트를 만드는 방법만 설명하지 않는다는 점이다. 팀을 한 번 구성한 뒤에도 시간이 지나면 역할 파일과 스킬, CLAUDE.md의 설정이 서로 달라질 수 있다. 책에서는 이러한 구성 불일치인 drift를 감지하고, 변경 이력을 남기며, 전체가 아닌 일부 단계만 다시 실행하는 운영 방식까지 다룬다.

또한 파이프라인, 팬아웃·팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임이라는 여섯 가지 아키텍처 패턴을 소개하면서 어떤 상황에서 어떤 구조를 선택해야 하는지도 설명한다. 에이전트를 무조건 많이 만드는 것이 아니라, 작업의 의존성과 검증 방식에 맞게 구조를 선택해야 한다는 관점이 좋았다.

코드 리뷰 외에도 풀스택 기능 구현, 레거시 마이그레이션, 디버깅과 RCA 팀 사례가 이어진다. 개념을 설명한 뒤 실제 도메인별 팀 구성으로 연결되기 때문에 앞부분에서 배운 요소들이 각각 어떤 역할을 하는지 확인할 수 있었다.

다만 클로드 코드에 익숙하지 않다면 밀도가 높게 느껴질 수 있다

아쉬운 점도 있었다. 초반의 Quick Start는 비교적 쉽게 따라갈 수 있지만, 에이전트 파일의 필드와 스킬 구조, 팀 프리미티브, 실행 모드가 연이어 등장하면서 중반부터는 정보량이 꽤 많아진다. 클로드 코드나 에이전트 기반 개발 환경을 처음 접하는 독자라면 개념만 읽고 넘어가기보다 책의 권유대로 직접 파일을 만들어보는 편이 좋다.

한 권에서 기초부터 메타스킬과 네 가지 실전 사례까지 다루다 보니, 각 사례의 도메인 로직이나 실행 결과를 더 깊게 보고 싶은 독자에게는 설명이 빠르게 지나간다고 느껴질 수도 있다. 대신 부록의 안티패턴과 트러블슈팅, 예제 저장소를 함께 살펴보면 부족한 부분을 보완할 수 있을 것 같다.

이런 사람에게 추천하고 싶다

이 책은 클로드 코드에 몇 가지 명령을 내려보는 단계를 넘어, 반복해서 사용할 수 있는 AI 개발팀을 만들고 싶은 사람에게 잘 맞는다. 특히 단일 에이전트가 만들어낸 결과를 그대로 신뢰하기 어렵다고 느꼈거나, 같은 작업을 매번 긴 프롬프트로 다시 설명하고 있었다면 도움을 받을 수 있다.

AI 에이전트를 팀이나 조직에 도입하려는 리드 개발자에게도 유용하다. 에이전트의 능력을 자랑하는 데서 그치지 않고 권한, 검증, 비용, 기록과 운영까지 함께 다루기 때문이다.

한 명의 AI를 잘 사용하는 법이 아니라, AI가 서로 협업하고 실수를 견제하는 개발팀을 설계하는 방법을 보여주는 책이다.

단일 AI의 한계를 넘어, 스스로 협업하고 검증하는 AI 에이전트 팀 구축의 바이블 같은 책입니다. 단순히 프롬프트 짜는 법이나 명령어만 나열하는 지루한 매뉴얼식 구성이 아니에요. 프롬프트 엔지니어링이나 복잡한 모델 내부 지식을 몰라도, git과 마크다운 파일만 다룰 줄 알면 내 PC에 완벽한 AI 개발 팀을 고용하는 실전형 지침서입니다. 특히 이 책은 모델의 가중치를 직접 건드리지 않고 바깥에서 권한과 도구, 가드레일을 설계하는 하네스 개념을 기반으로 하고 있어서, 단일 에이전트의 폭주나 실수를 완벽하게 제어할 수 있는 시스템을 만들 수 있다는 점이 정말 매력적이에요. 실제 카카오 현업에서 검증된 노하우와 데이터가 가득 담겨 있어 독학하면서도 신뢰감이 팍팍 올라갑니다.

《하네스 엔지니어링 with 클로드 코드》는 단순한 프롬프트 작성을 넘어 아키텍처 관점에서 AI 에이전트를 제어하는 신선한 방법론을 다룬다. 2026년 CLI 환경의 대세로 자리 잡은 Claude Code와 Model Context Protocol(MCP)을 활용해 에이전트의 컨텍스트를 확장하는 실무적 과정을 명확히 짚어낸다. 특히 테스트 하네스를 빌드 스크립트와 엮어 에이전트가 스스로 디버깅하고 코드를 완성하도록 유도하는 자율 주행 TDD 피드백 루프 구현 파트는 현업 개발자의 실무적 고민에 매우 명쾌한 해답을 준다.