한빛미디어



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

하네스 엔지니어링 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클로드코드