"한빛미디어 서평단 <나는리뷰어다> 활동을 위해서 책을 협찬 받아 작성된 서평입니다."
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가 서로 협업하고 실수를 견제하는 개발팀을 설계하는 방법을 보여주는 책이다.
댓글