Claude Code 결과물이 매번 다르다면? ' 하네스 엔지니어링 with 클로드 코드' 서평

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

 

 

 

 

요즘 개인 프로젝트는 거의 Claude Code랑 같이 합니다. 간단한 기능 추가나 반복 작업은 맡겨두면 알아서 잘 처리해주는데, 프로젝트가 조금만 커지면 얘기가 달라졌습니다. 작은 게임을 하나 만들어보려고 Claude Code랑 계속 작업을 하다 보니, 어느 순간 메인 로직 파일 하나가 800줄을 넘어가 있었습니다. 코드는 거의 스파게티처럼 꼬여 있었고요. 더 황당했던 건, 분명 전에 만들어둔 함수가 있는데 다른 부분에서 똑같은 기능을 하는 함수를 또 새로 만들어놓은 걸 발견했을 때입니다. 인수나 리턴값도 상황에 맞게 유연하게 받아야 하는데, 묘하게 특정 형태로만 받도록 좁혀놓은 부분도 있었습니다.

프롬프트를 더 정교하게 쓰면 나아질까 싶어서 이것저것 시도해보다가, 우연히 집어든 책이 '하네스 엔지니어링 with 클로드 코드'였습니다.

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

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

 

 

 

 

---

 

 

 

프롬프트보다 중요한 건 '구조' - 하네스 엔지니어링이란

책에서 인상 깊었던 부분은, 결과물 품질을 가르는 게 AI 성능이 아니라 작업 구조(하네스)라는 관점이었습니다.

책에서는 단일 에이전트한테 생성과 검증을 동시에 맡기면 자기 실수를 잘 못 찾아낸다는 사례를 보여주는데, 문제 원인이 모델이 아니라 일을 시키는 방식에 있다는 설명이 꽤 설득력 있었습니다. 

 

긴 프롬프트 하나로 다 해결하려 하지 말고 역할을 나누고, 규칙을 정하고, 검증 단계를 넣으라는 조언은 요즘 AI 에이전트 개발 흐름과도 잘 맞아떨어집니다.

 

 

 

 

---

 

 

 

제 800줄짜리 파일이 왜 그렇게 됐는지 알려주는 챕터

3장을 읽다가 좀 머쓱해졌습니다. 책에서는 역할·검증 로직·조율 규칙을 한 에이전트 파일에 다 몰아넣으면 어떤 일이 생기는지를 가상의 예시로 보여주는데, 딱 제 게임 프로젝트 파일 얘기였습니다.

 

책에서 정리한 문제는 크게 두 가지였습니다. 하나는 재사용이 안 된다는 것. 한 파일에 역할이 다 섞여 있으니 비슷한 검증 로직이 필요할 때마다 복사-붙여넣기를 하게 됩니다. 다른 하나는 같은 모델이 같은 맥락으로 자기 결과물을 검토하니, 만들 때 놓친 문제를 검증할 때도 똑같이 놓친다는 것이었습니다. 이런 게 쌓이다 보면 파일 하나가 수백 줄짜리 덩어리가 되어버린다고 하더군요.

 

읽으면서 "어, 이거 내 얘기인데" 싶었습니다. 제 800줄 파일에도 캐릭터 역할 정의, 검증 로직, 다음 단계로 넘기는 흐름까지 다 같이 들어 있었거든요. 함수가 중복으로 생긴 것도, 결국 그 파일 안에서 뭐가 이미 있는지 코드 전체가 한눈에 안 들어오니까 생긴 문제였던 것 같습니다.

재밌었던 건, 책에서는 "다음 단계로 넘기는 흐름" 같은 작업(Task) 자체도 독립된 요소로 보지 않는다는 점이었습니다. 누가 할지(Agent), 어떻게 할지(Skill)와는 다르게, 작업 흐름은 그 자체로 따로 관리하는 게 아니라 언제·누구와 협업할지를 정하는 오케스트레이터의 도구로 본다는 거죠. 제 코드를 돌이켜보면, "다음 단계로 넘기는 흐름"을 독립된 시스템처럼 따로 만들려고 했던 게 오히려 더 헷갈리게 만든 부분이었던 것 같습니다.

 

 

 

 

---

 

 

생성(Author)과 검토(Reviewer)를 분리한다는 것

가장 기억에 남는 내용은 생성(Author)과 검토(Reviewer)를 분리하는 구조입니다.

생각해보면 사람도 자기가 쓴 글의 오타를 잘 못 찾습니다. AI도 마찬가지로, 하나의 에이전트가 생성과 검증을 같이 맡으면 같은 실수를 계속 반복하기 쉽습니다.

그래서 생성 에이전트와 검토 에이전트를 따로 두고 PASS·REDO를 판단하게 하는 방식은, 아이디어 자체는 단순한데 실제로는 꽤 실용적이라는 인상을 받았습니다. 사실 이 부분을 읽으면서 제가 겪었던 함수 중복 문제가 바로 떠올랐습니다. 그때 검토 역할을 하는 에이전트가 따로 있었다면, "이미 비슷한 함수가 있는데?"라고 한 번쯤 잡아줬을 수도 있겠다는 생각이 들었습니다.

책에서 반복해서 강조하는 "AI 결과물은 초안이다. 최종 판단은 사람이 한다"는 말은, AI 쓰는 개발자라면 한 번쯤 곱씹어볼 문장입니다.

 

 

---

 

 

같은 스킬, 켰을 때와 껐을 때 - With/Without 비교

 

책에서 인상적이었던 부분이 하나 더 있습니다. 스킬을 만들어놓고 "이게 진짜 효과가 있나?"를 검증하는 방법인데, **같은 프롬프트, 같은 모델로 스킬을 켰을 때와 껐을 때를 동시에 실행해서 비교**한다는 내용이었습니다.

두 결과가 똑같이 PASS거나 똑같이 FAIL이면 그 스킬은 사실 아무 효과가 없는 거고, 결과가 갈려야 비로소 스킬의 가치가 증명된다는 설명이 인상 깊었습니다. 거기다 품질만 보는 게 아니라 속도와 비용(토큰 사용량)까지 같이 비교해야 한다는 점도 새로웠습니다. 품질은 좋아졌는데 토큰을 2배 넘게 써버리면 그게 정말 "좋은 스킬"인지는 애매하다는 거죠.

돌이켜보면 저는 그동안 "이 프롬프트 넣었더니 결과가 나아진 것 같다"는 느낌으로만 판단했지, 이렇게 숫자로 비교해본 적은 없었습니다. 다음엔 같은 작업을 스킬 켜고/끄고 두 번 돌려서 토큰 사용량이라도 한번 비교해봐야겠다는 생각이 들었습니다.

 

---

 

 

읽으면서 느낀 점

이 책은 Claude Code 사용법 자체를 알려주는 책이라기보다, AI와 함께 개발할 때 필요한 작업 방식을 다루는 책에 가깝습니다.

 

그동안 프롬프트를 잘 쓰는 데만 신경 썼는데, 책을 읽으면서 프로젝트 구조나 역할 분리, 검증 과정을 미리 설계하는 게 오히려 더 중요할 수도 있겠다는 생각이 들었습니다.

 

책에 나온 하네스를 전부 그대로 따라 해보지는 못했고, 작은 개인 프로젝트에 이걸 그대로 적용하는 게 항상 효율적인지는 좀 더 써봐야 알 것 같습니다. 다만 에이전트와 스킬을 분리하고, author·reviewer 역할을 나누거나 작업 규칙을 미리 정해두는 정도는, 다음 프로젝트에서 바로 시도해볼 생각입니다.