<하네스 엔지니어링 with 클로드 코드> 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워크플로 #개발자동화