99%가 모르는 하네스 엔지니어링 — AI 에이전트 생산성을 10배 올리는 세팅법 (바이브마피아 최수민님)

한 줄 요약

바이브마피아 최수민 님이 조쉬와 함께 하네스 엔지니어링을 실제 세팅으로 풀어 줬어요. 무엇을 만들지는 사람이 대화로 끝까지 구체화합니다. 그 뒤의 구현·테스트·PR 리뷰·머지는 스크립트와 에이전트에 통째로 맡기는 구조예요.

전체 내용 정리

하네스는 에이전트를 오래 혼자 달리게 하는 장치예요

빌더 조쉬 채널에 바이브마피아 최수민 님이 다시 나왔어요. 수민 님은 6개월 전 팟캐스트를 찍을 때만 해도 하네스 구축은 개발을 아주 빡세게 하는 사람들이나 하는 일이었다고 말합니다. 요즘은 하네스를 나도 해 봐야겠다며 궁금해하는 사람이 많아져서 언제 쓰고 어떻게 작동하게 만들고 무엇을 조심해야 하는지 참고서처럼 정리해 왔다고 해요.

수민 님의 정의는 간단해요. 하네스는 AI 에이전트를 오랫동안 자율 주행시키기 위한 장치라는 거죠. 에이전트는 컨텍스트 크기가 한정돼 있어서 그냥 두면 많은 일을 해내지 못합니다. 그래서 일을 서브에이전트 단위로 나누기도 하고 다른 에이전트 페르소나를 만들어 리뷰를 맡기기도 하는데, 이런 장치 전부를 하네스라고 부른다는 설명이에요.

흥미로운 건 하네스가 어느 단계에서 힘을 쓰느냐예요. 개발 과정을 네 단계로 나누면 하네스는 뒤의 두 단계에서 특히 강력하다고 해요. 앞 단계는 사람의 의도가 잘 반영돼야 하는 구간이라 자율 주행을 시켜 봐야 의미가 적고 할루시네이션(그럴듯한 오답)도 생기기 쉽거든요. 이미 잘 구체화된 것을 크기와 상관없이 틀림없이 구현해 내게 만드는 세팅, 수민 님은 그게 하네스라고 봅니다.

구체화가 무슨 뜻인지도 짚고 넘어갔어요. 조쉬는 자신이 CLAUDE.md나 AGENTS.md, 그다음 서브에이전트와 스킬로 세 개의 레이어를 세팅한다며 그런 문서 작업을 말하는 건지 물었는데요. 수민 님이 말한 구체화는 결이 조금 달랐습니다. 앱이나 서비스 기능을 만들 때 내 니즈가 충분히 구체적이지 않은 경우가 대부분이라서 무엇을 만들지가 완전히 명확해진 상태를 구체화가 끝난 상태로 본다는 거예요.

이걸 점검하는 효과적인 방법은 AI에게 묻는 거예요. 지금 구체화가 덜 된 포인트가 뭐냐고 물으면 AI가 짚어 줍니다. 전문 기획자나 디자이너가 아니면 설계를 구체화하면서 많은 걸 빼먹을 수밖에 없거든요. 조쉬가 결국 빡센 기획이냐고 정리하자 수민 님은 내 의도를 명확히 하는 작업이라고 받았어요.

구체화를 건너뛰고 개발부터 시작하면 어떻게 될까요? 정해진 게 없으니 에이전트가 이때는 이렇게, 저 때는 저렇게 만들기도 하고 결과가 의도와 다르게 나오기도 해요. 그걸 고치는 데 시간이 훨씬 더 듭니다. 수민 님은 앞단의 구체화를 무엇보다 중요하게 보고 잘된 구체화를 맛있게 요리까지 해 주는 게 하네스의 역할이라고 말해요.

구체화는 대화로 하고 구현은 스킬 하나로 넘겨요

수민 님이 보여 준 첫 번째 사례는 구체화된 기획을 빠짐없이 개발해 주는 구현 하네스예요. 출발점은 문서화입니다. 문서를 잘 정리해 두고 AI에게 먹여 프로젝트의 기획·디자인·아키텍처·설계 의도를 정확히 파악하게 해요. 그다음 이번 작업을 구현하려면 더 구체화해야 할 점을 사용자에게 물어보게 합니다. 개발 들어가기 직전에 한 번 더 논의하는 자리죠.

오케스트레이터는 스킬 파일로 만들었어요. 조쉬가 왜 하필 스킬이냐고 묻자 답은 실용적이었습니다. 기획·디자인·개발 구체화를 먼저 끝낸 뒤 하네스를 부르기 때문에 이미 클로드 코드(Claude Code)와 대화를 많이 나눈 상태거든요. 그 흐름에서 자연스럽게 호출하기에 스킬이 편하다는 거예요.

그럼 구체화 단계에는 왜 하네스를 따로 두지 않을까요? 수민 님은 요구 사항을 구체화하는 일이 너무 변칙적이라고 봐요. 에이전트가 논의점을 던지면 거기서 더 파고들고 싶을 때가 있는데 그러면 대화가 길어지죠. 이런 설계 단계는 정형화하기가 꽤 어렵다고 느꼈다고 해요. 게다가 하네스가 없는 일반 LLM 챗봇도 기획 구체화 정도는 문제없이 잘 도와줍니다. 그래서 일반 대화로 양질의 컨텍스트를 쌓아 두고 그걸 하나도 빠뜨리지 않고 구현하는 데 하네스를 써요.

스킬에 적힌 흐름을 차례로 보면 이래요. 우선 문서를 읽어 현재 프로젝트 상태를 파악하는데, 이때 클로드 코드가 기본 제공하는 서브에이전트 유형인 익스플로어 에이전트를 병렬로 쓰라고 명시해 뒀어요. 적어 두지 않으면 가끔 병렬로 안 돌리는데 병렬이 훨씬 빠르거든요. 다음으로 구현 관점에서 더 짚을 것을 한 번 더 짚게 합니다. 최대한 빠뜨리지 않고 구체화를 다 하고 넘어가자는 주의라서 안전장치를 많이 걸어 둔 거예요.

작업 단위는 태스크와 페이즈로 나눠요. 태스크는 작업 하나 통째이고 페이즈는 그걸 끝내기 위해 나눈 단계예요. 보통 태스크 하나에 페이즈가 열 개 정도 나오고 20개를 넘길 때도 있습니다. 계획을 쓰고 나면 에이전트가 먼저 논의를 걸어오기도 해요. 페이즈가 14개인데 안정성을 위해 테스트를 많이 넣으면 17개로 늘어나니 너무 오래 걸리지 않겠냐는 식으로요.

테스트 케이스를 정하는 단계도 따로 있어요. 테스트는 사람이 수동으로 검증해야 하는 수고를 줄이는 데 아주 효과적인 장치지만 많을수록 좋은 건 아니라는 게 수민 님 생각이에요. 미리 정해 둔 테스트 전략을 기준으로 에이전트가 이번 기능에 20개쯤 필요하다고 리스트업하면, 그중 넣을지 뺄지 애매한 세 개 정도를 사용자와 함께 결정하는 식입니다. 사람은 에이전트가 애매하다고 판단한 것의 방향만 잡아 주면 돼요.

반복 호출은 스크립트에 맡기고 메인 세션은 비워 둬요

계획이 확정되면 페이즈 파일들을 만들고 파이썬 스크립트로 실행해요. 수민 님은 이 스크립트가 핵심이라고 강조합니다. 전체 페이즈가 몇 개이고 몇 개가 남았는지, 어디서부터 시작해야 하는지가 스크립트 안에 명시돼 있거든요. 태스크를 돌리다가 멈추거나 오류로 깨지면 원복한 뒤 다시 실행할 수 있어요. 큰 작업이 중간에 잘못돼도 잘된 지점까지 기억해 두고 복구하는 기능이 들어 있는 셈이죠.

구조는 이래요. 태스크마다 하위 단계의 이름과 상태를 담은 루트 인덱스 JSON 파일이 있어요. 스크립트는 이 파일을 읽어 움직입니다. 같은 폴더에는 페이즈별 상세 지침이 들어가요. 각 페이즈는 독립된 일꾼 세션이 처리하기 때문에 그 파일만 보고도 의도를 잃지 않고 작업을 끝낼 수 있어야 하는데, 수민 님은 이걸 자기 완결적이라고 표현합니다. 스펙 문서 경로, 이전 페이즈에서 만들거나 고친 파일, 구체적인 작업 지침과 검증 방법까지 다 들어가요.

실행은 클로드 코드의 헤드리스 모드, 그러니까 -p(프린트) 모드로 해요. 이렇게 하면 스크립트 안에서 클로드 코드를 프로그램처럼 호출할 수 있거든요. 페이즈마다 서브 프로세스를 띄워 이 명령을 호출하는데, 페이즈 파일에 담긴 작업 지침이 그대로 프롬프트가 됩니다. 조쉬가 열 개 페이즈를 직렬로 도느냐고 묻자 수민 님은 일단 직렬로만 생각해 뒀다고 답했어요.

왜 서브에이전트가 아니라 스크립트일까요? 메인 세션의 컨텍스트를 지키기 위해서예요. 메인 세션은 사용자의 의도와 이 작업이 어떻게 돼야 하는지를 기억하는 데 집중하게 두고 구체적인 구현 컨텍스트는 하위 일꾼 세션에 전부 넘기고 싶은 거죠. 서브에이전트를 쓰면 첫 번째부터 100번째까지 순서대로 호출하는 책임을 메인 에이전트가 떠안게 됩니다. 어차피 순차 실행이니 그 책임을 스크립트 안에 넣어 버린 거예요.

수민 님 표현을 빌리면 에이전트는 생각하는 기계라서 생각할 필요가 없는 일은 그냥 다 덜어냈다는 거예요. 효과는 바로 나타납니다. 나중에 버그가 생겨 어떻게 대처할지 논의할 때 메인 에이전트의 컨텍스트가 깨끗해서 답을 잘 줘요. 수민 님에 따르면 "구현 작업을 끝낸 이후에도 메인 에이전트의 컨텍스트가 20%도 소모가 안 돼요."

그럼 구현이 도는 동안 사람은 뭘 할까요? 수민 님은 다른 작업의 구체화를 한다고 해요. 코드 레벨까지 구체화하는 편이라 설계에 30분쯤 쓰고 나서 구현을 시키면 두 시간쯤 돌아가는데, 그동안 다른 일을 하거나 밥을 먹고 온다고요. 다만 여러 프로젝트를 한꺼번에 병렬로 돌리는 건 애매하다고 봐요. 구현된 걸 실제로 써 보면 또 느껴지는 게 있어서 너무 많이 동시에 구현해 두면 수습하고 이해하는 데 시간이 너무 오래 걸리거든요.

PR 리뷰와 머지까지 에이전트끼리 끝내요

스크립트는 실행하면서 깃 커밋을 남기고 마지막에 풀 리퀘스트(PR)까지 만들어요. 화면에 보인 PR의 커밋들은 전부 스크립트가 자동으로 만든 거였습니다. 수민 님의 프로젝트는 오픈 소스라서 코드레빗(CodeRabbit)을 무료로 쓰는데, 코드레빗이 PR에 자동 리뷰를 달아 줘요. 에이전트는 이 리뷰를 읽고 반영할 만한 건 알아서 반영합니다.

재밌는 건 그다음이에요. 에이전트가 PR에 반영했다는 댓글을 달면 코드레빗이 확인했다고 답하며 처리하는 식으로 둘이 대화를 주고받아요. 이 에이전트는 수민 님 본인 계정이 아니라 에이전트용으로 따로 만든 깃허브 계정으로 움직입니다. 기획과 큰 설계를 충분히 잡고 들어갔으니 구현이 완전히 어그러졌을 리는 없다고 보는 거죠. 코드레빗은 가끔 다른 개발자 시각에서 사소한 구현 개선점을 짚어 주는데, 수민 님 말로는 "그 레벨은 나랑 논의하지 말고 너희끼리 알아서 해라 이거죠."

리뷰 반영이 끝나면 머지도 에이전트가 직접 해요. 조쉬가 통제를 벗어나는 건 괜찮냐고 묻자 수민 님은 자기 역할은 의도를 정확하게 넘겨 주는 데까지라고 답했습니다. 그 이후는 자기가 상관할 바가 아니라고요.

"저는 사실 지금 클로드 코드를 개발자를 고용했다고 생각하고 대화하고 있거든요."

개발자를 고용했다면 머지를 내가 하진 않잖아요. 대신 그 개발자에게 이게 왜 필요한지를 아주 자세히 설명하는 데 공을 들인다고 해요. 이상한 걸 만들지 않게요.

그럼 PR은 왜 굳이 만들까요? 꼭 PR이어야 할 이유는 없다고 해요. "PR로 만드는 이유는 인간인 제가 보기에 편해서 그래요." PR도 문서이고 코멘트 기능 덕분에 대화 내역이 보기 좋게 남거든요. 최종 검수자로서 에이전트들이 유의미한 대화를 하는지, 반영할 만한 걸 반영했는지 궁금할 때 확인하기 좋은 형식이라는 거예요.

조쉬는 최근 클로드에 나온 팀 단위 기능이나 에이전트들을 한 공간에 모아 서로 토론시키는 방식도 물었어요. 수민 님은 그 접근도 의미 있다고 보지만 자신과는 잘 맞지 않는다고 해요. 그에게는 만들어야 할 것은 만들고 안 만들어야 할 것은 안 만드는 게 가장 중요하거든요. 에이전트는 아이디어 하나를 엄청난 분량으로 증폭해 줄 수 있지만 서비스 오너는 어차피 그걸 이해해야 합니다. 증폭시켜 놓고 이해하며 깎는 것보다 구체화 단계에서 직접 대화를 주도하며 미세 조정하는 쪽이 낫다는 판단이에요.

이유가 하나 더 있어요. 제품을 만드는 사람만 아는 암묵지가 아주 많다는 거예요. 어제 잠재 고객과 인터뷰하며 느낀 뉘앙스 같은 건 아직 클로드에 옮겨지지 않았는데, 이런 게 제품 구체화의 사소한 판단에 큰 영향을 줍니다. 초기 제품이라 참고할 만한 정량 데이터도 없어서 설계의 좋고 나쁨을 가를 기준을 에이전트에 넘기기도 애매하고요. 구현 단계에서도 단순한 스크립트 하네스 호출만으로 잘 돌아가서 팀 기능은 잘 안 쓴다고 합니다.

작업의 첫 단계는 무조건 문서 업데이트예요

수민 님이 따로 강조한 원칙이 하나 있어요. 태스크를 짤 때 첫 번째 단계는 무조건 문서 업데이트라는 거예요. 새 기능을 만들면 기존 문서도 바뀌어야 하니 그 과정을 작업 시작 단계에 박아 둡니다. 문서를 전부 업데이트한 뒤에는 '독스 디프'라는 파일을 만들어요. 문서에서 바뀐 정확한 내용을 스크립트로 모아 둔 파일이에요.

실제 파일을 보면 ADR 문서에서 삭제된 내용은 없고 248번째 줄에 이런 내용이 추가됐다는 식으로 기록돼 있어요. 이후 페이즈들은 이 파일을 계속 참조합니다. 이 작업 때문에 문서가 정확히 어떻게 바뀌었는지를 매번 확인하는 거죠.

왜 이렇게까지 할까요? 스펙 기반으로 바이브 코딩을 하면 스펙이 곧 코드로 옮겨지는데, 에이전트가 작업 계획을 다소 제멋대로 해석해 스펙과 어긋나게 구현할 우려가 있거든요. 서비스가 커질수록 스펙 문서는 많아지고 각각도 길어집니다. 작업 계획에 이 문서들이 바뀌었다고 대충 언급하는 것으로는 부족해요. 추가된 줄만 넣어 주면 강조가 확실히 된다는 게 수민 님 설명이에요. 스펙 문서를 써 두고 구현하고 있다면 이 단계를 맨 앞에 두는 게 정확도를 관리하는 데 아주 중요하다고 합니다.

이런 감각은 어디서 왔을까요? 수민 님은 예전에 토스에서 PM으로 일한 경험이 꽤 도움이 됐다고 해요. 그가 본 유능한 PM들은 개발자나 작업자가 무엇을 고민해야 하는지 콤팩트하고 빠르게 알 수 있는 체계를 만드는 데 집중했거든요. 워커들이 의도와 맞지 않는 일을 하지 않고 자기 작업을 깔끔하게 끝내게 만드는 것, 이런 산업공학적이고 조직 관리적인 접근이 하네스를 만들 때 꽤 유효하다는 거예요. 쓸모없는 정보는 최대한 빼고 알아야 할 것만 주려는 노력도 같은 맥락이고요.

코드 리뷰 하네스는 세션을 포크해 의도를 남겨요

두 번째 사례는 코드 리뷰 하네스예요. 모든 팀에 코드 리뷰가 필요하고 수민 님 말대로 "리뷰가 웬만한 상황에서 가장 큰 병목이거든요." 구현은 끝났는데 리뷰를 못 받아 머지를 못 하면 블로킹 이슈가 되니 여기를 최적화하면 체감 효용이 크다는 설명입니다.

여기서도 요구 사항 구체화와 아키텍처 설계는 사람이 함께해요. 대화를 충분히 나눠 컨텍스트가 쌓였다 싶으면 세션을 포크합니다. 포크는 같은 세션을 하나 더 복제하는 거예요. 같은 기억을 가진 A 세션과 B 세션이 서로 다른 일을 할 수 있게 되죠.

포크한 세션은 두 가지 문서를 써요. 하나는 각 의사 결정을 어떤 근거로 내렸는지 담은 설계 의도 문서예요. 다른 하나는 ADR(아키텍처 결정 기록)입니다. ADR은 설계 결정을 문서로 남겨 나중에 온보딩하는 개발자가 이 조직이 어떤 기준으로 결정하는지 알게 해 줘요. 새로 들어오는 에이전트에게 보여 주면 조직 문화를 바로 알 수 있다는 점도 수민 님이 꼽은 장점이에요. 두 문서는 쓰임이 달라요. ADR은 공용 문서로 계속 관리하고 설계 의도 문서는 이 작업 한정이라 훨씬 자세히 씁니다. 에이전트가 의도를 명확하게 못 쓰는 경우가 있어서 사람이 한 번 검토해야 한다고요.

문서를 다 쓰면 포크한 세션은 버려요. 조쉬가 왜 버리냐고 묻자 문서를 쓰는 과정은 컨텍스트만 소모할 뿐 새 인사이트가 나오는 과정이 아니기 때문이라는 답이 돌아왔어요. 원래 있던 인사이트를 문서로 옮기는 것뿐이니 결과물인 문서만 남기는 거죠. ADR은 공용이라 독스 경로에, 설계 의도 문서는 작업 전용 폴더에 저장돼요.

원본 세션에서는 서브에이전트로 리뷰 평가 기준을 만들어요. 코드 컨벤션과 ADR은 계속 업데이트되니 점점 커지는데, 이번 작업을 평가하는 데 그 전부가 필요하진 않거든요. 그래서 과거 의사 결정 기록 중 이번에 참고할 것만 골라내는 서브에이전트를 둡니다. 이렇게 만든 평가 기준은 구현할 때도 리뷰할 때도 똑같이 먹여요.

수민 님은 코드 리뷰가 잘 안 되는 이유로 컨벤션이나 ADR을 아예 안 주거나, 줘도 너무 방대하고 장황해서 무엇을 봐야 할지 초점이 안 잡히는 경우를 들어요. 콤팩트한 문서를 만들어 두고 이걸 참고해 리뷰하라고 하면 품질이 훨씬 높아진다고요. 이 서브에이전트는 사실상 유사 래그(RAG, 필요한 자료를 찾아 붙여 주는 방식) 역할을 하는데, 복잡한 래그를 만들지 않아도 이 정도로 꽤 잘 해 준다는 게 수민 님 설명입니다.

이 하네스는 공개 저장소에 마피아 코드 리뷰 하네스라는 이름으로 올라가 있고 클로드 플러그인으로 설치할 수 있어요. 호출 타이밍은 구체화를 다 마치고 이후 흐름이 자동으로 진행됐으면 할 때입니다. 그러면 PR 생성까지 알아서 해 준다고 해요.

대담 끝에는 수민 님의 요즘 관심사도 나왔어요. 예전에는 코딩 교육이나 개발 교육에 집중했지만 이제는 기업 자체가 더 유능하고 빠르게 움직이게 돕는 쪽이 임팩트가 훨씬 크다고 보고 AX(AI 전환)에 도전하고 있다고 해요. 에이전트는 컨텍스트만 잘 구성되면 일을 잘하는데 대개 그 구성이 안 되는 게 문제라는 거죠. 그래서 시트나 노션에 비정형으로 남던 기록을 에이전트가 읽기 쉬운 파일 시스템과 데이터 저장소로 옮기는 데 집중하고 있어요. 데이터만 잘 있으면 래그 역할을 하는 서브에이전트 정도로도 웬만한 업무를 잘 해낸다는 게 수민 님 생각이에요.

핵심 인사이트

• 하네스는 구체화가 끝난 뒤에야 힘을 써요: 무엇을 만들지 명확하지 않은 상태에서 자율 주행을 시키면 할루시네이션과 재작업만 늘어요. 사람이 대화로 의도를 다듬는 앞 단계와 에이전트가 끝까지 구현하는 뒤 단계를 나누는 게 출발점입니다.
• 생각이 필요 없는 일은 스크립트로 빼요: 페이즈를 순서대로 호출하는 일을 메인 에이전트에 맡기지 않고 파이썬 스크립트에 넣은 덕에 구현이 끝나도 메인 컨텍스트가 20%도 안 쓰였어요. 메인 세션이 깨끗해야 버그 대응 같은 판단을 잘 내립니다.
• 컨텍스트는 추려서 줄수록 정확해져요: 문서 변경분만 모은 독스 디프, 이번 작업에 필요한 컨벤션과 ADR만 골라낸 평가 기준이 같은 원리예요. 방대한 문서를 통째로 주기보다 추가된 줄과 관련된 결정만 주는 쪽이 강조가 확실하고 리뷰 품질도 높습니다.
• 암묵지는 아직 사람에게 있어요: 고객 인터뷰에서 느낀 뉘앙스처럼 에이전트에 옮겨지지 않은 판단 기준이 많아서 수민 님은 기획 토론을 에이전트끼리 시키지 않아요. 의도를 정확히 넘기는 일은 사람이 맡고 그 뒤는 고용한 개발자에게 맡기듯 넘기는 구조예요.

오늘 당장 해볼 것

1. 다음 기능이나 자동화를 만들기 전에 클로드 코드나 평소 쓰는 챗봇에게 지금 구체화가 덜 된 포인트가 뭐냐고 먼저 물어보세요. 기획자가 아니면 빠뜨리기 쉬운 지점을 짚어 줘서 만든 뒤 고치는 시간을 줄일 수 있어요.
2. 큰 작업을 페이즈 파일 여러 개로 쪼개고 클로드 코드의 헤드리스(-p) 모드로 하나씩 순서대로 실행하는 작은 파이썬 스크립트를 만들어 보세요. 진행 상태를 JSON 인덱스에 적어 두면 중간에 깨져도 이어서 돌릴 수 있고 메인 세션의 컨텍스트도 아낄 수 있어요.
3. 스펙 문서를 쓰고 있다면 작업 첫 단계를 문서 업데이트로 고정하고 바뀐 줄만 모은 변경분 파일을 만들어 이후 단계에 넘겨 보세요. 에이전트가 계획을 제멋대로 해석해 스펙과 어긋나는 일을 줄여 줍니다.