AI 에이전트에게 '팀'을 붙여줬더니, 실수가 사라지기 시작했다「하네스 엔지니어링 with 클로드 코드

smokes***

2026-06-29

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

스스로 일하는 에이전트 팀을 설계하고 운영하는 방법인 하네스 엔지니어링을 체계적으로 정리한 최초의 실전서

저자 : 황민호
출간 : 2026-06-11

상세보기

안녕하세요, AI 에이전트와 자동화 도구를 적극 활용 중인 개발자입니다. 요즘 클로드 코드, 커서 같은 AI 코딩 도구를 쓰면서 늘 한 가지 불편함을 느꼈어요."왜 이 AI는 자기가 실수한 걸 스스로 못 잡지?"

혼자 코드를 짜고, 혼자 검토하고, 혼자 머지하는 구조에서 에이전트의 자기 검증은 결국 자기가 자기 글을 교정하는 것과 같다는 걸 어렴풋이 느끼고 있었습니다. 그러던 중에 [하네스 엔지니어링 with 클로드 코드]를 읽게 됐습니다.

결론부터 말하면, 이 책은 "AI 도구를 어떻게 더 잘 쓰는가"가 아니라 "AI가 일하는 환경 자체를 어떻게 설계하는가"를 다루는 책입니다.

"모델이 아니라 하네스가 결과를 결정한다"

책의 첫 장부터 충격적인 사례가 나옵니다. 2025년 7월, 한 기업에서 AI 에이전트가 임원 레코드 1,206명분을 삭제하고 "복구 불가능합니다"라고 보고한 사건이요. 알고 보니 복구는 가능했고, 에이전트가 스스로 내린 판단이 문제였습니다.

읽으면서 손이 떨렸습니다. 이건 먼 나라 이야기가 아니거든요. AI 에이전트가 plan → code → verify → self-revise의 네 단계를 혼자 다 수행하는 구조에서는, 처음에 놓친 가정을 끝까지 반복한다는 게 이 책의 핵심 진단입니다.

저자인 황민호(카카오 FDE팀 수석)는 같은 클로드 모델을 두고 환경만 바꿨더니 점수가 49점에서 79점으로 올랐다는 실험 결과를 제시합니다. 모델이 아니라 모델을 둘러싼 구조가 결과를 결정한다는 것, 그게 이 책이 말하는 하네스 엔지니어링의 핵심입니다.

하네스란 무엇인가 — "모델 바깥을 설계하라"

Part 1은 왜 단일 에이전트가 믿을 수 없는지에서 시작합니다. 단일 에이전트는 자기 실수를 잘 못 본다. 구조를 보면 이유가 명확합니다. 혼자 쓴 PR을 혼자 머지하는 구조이기 때문입니다.

하네스란 모델의 가중치를 건드리지 않고, 모델 바깥에 권한·도구·검증·관측을 설계해 에이전트가 혼자 움직이게 만드는 환경입니다. 병목이 능력이 아니라 구조에 있다는 인식의 전환이 이 파트의 핵심입니다.

"단일 에이전트는 자신의 실수를 잘 보지 못한다."

이 한 줄이 책 전체의 출발점입니다. AI 에이전트가 계획·작성·검증·자기수정을 모두 같은 박스 안에서 수행하니, 처음에 놓친 가정은 끝까지 반복되고, 다른 검토자가 없으면 설계 결함이 그대로 남습니다.

하네스의 세 기둥 — 에이전트·스킬·오케스트레이터

Part 2는 이 책에서 가장 밀도 높은 파트입니다. 하네스를 이루는 세 기둥을 순서대로 분해합니다.

에이전트(누가) — 역할과 가드레일을 파일로 정의합니다. "이 에이전트는 무엇을 할 수 있고, 무엇을 할 수 없는가"를 CLAUDE.md와 에이전트 정의 파일에 명시합니다.

스킬(어떻게) — description 한 줄이 호출 여부를 결정합니다. 아무리 잘 만든 스킬도 description이 엉성하면 에이전트가 언제 써야 할지 모릅니다. 스킬 설계의 핵심은 description 작성이라는 게 인상 깊었습니다.

오케스트레이터(언제 누구와) — TeamCreate, TaskCreate, SendMessage 세 도구로 팀을 조율합니다.

특히 "한 파일에 다 넣으면 무엇이 깨지는가" 챕터가 인상 깊었습니다. 누가(역할), 어떻게(스킬), 언제 누구와(조율)가 한 파일에 섞이면 한쪽을 바꿀 때마다 다른 쪽이 영향을 받습니다. 단일 책임 원칙을 어긴 클래스 하나가 자리를 차지하고 있는 셈입니다.

저는 읽고 나서 팀 내 에이전트 구성을 다시 들여다봤습니다. "이 역할 정의가 여기 있어야 하나?" 질문 하나씩 던지면서 정리했더니, 수정 속도가 눈에 띄게 달라졌습니다.

오케스트레이터 — 리더 병목을 어떻게 해소할까

6장 오케스트레이터 챕터는 사실상 이 책의 핵심입니다. 팀이 세 명을 넘으면 리더 병목이 생깁니다. 오케스트레이터가 모든 메시지를 중계하면 처리량이 병목이 되고, 직접 코드를 고치면 책임 분리가 무너집니다.

이를 해결하는 게 세 가지 기본 도구입니다. TeamCreate로 세션 객체로서의 팀을 생성하고, TaskCreate로 공유 작업 큐를 관리하고, SendMessage로 팀원끼리 직접 소통하게 합니다.

책에서 강조하는 건 이거예요. "모든 것이 성공한다고 가정하는 오케스트레이터는 프로덕션에서 가장 먼저 무너진다." — 클로드 코드 오케스트레이션 공식 가이드에서 인용한 이 문장이 챕터 전체를 관통합니다.

팬아웃/팬인, 파이프라인, 생성-검증 등 여섯 가지 아키텍처 패턴과 함께 실행 모드별 트레이드오프도 명확하게 정리됩니다.

Part 4 실전편 — 코드 리뷰 자동화 팀

이 챕터는 그냥 실무 필살기입니다. PR diff를 받아 정적 분석, 보안 검토, 테스트 영향 검토를 병렬로 수행하고 하나의 리뷰 리포트로 통합하는 코드 리뷰 자동화 팀의 전체 구성이 낱낱이 공개됩니다.

오케스트레이터 스크립트부터 각 에이전트 정의 파일, 출력물 경로 설계까지 실제로 복사해서 바로 실행 가능한 수준으로 담겨 있습니다.

Airbnb가 3,500개의 React 테스트를 6주 만에 이전한 레거시 마이그레이션 팀 사례, OpenAI가 5개월간 100만 줄을 생성하며 수동 코드 0줄을 유지한 사례도 Part 4에서 다룹니다. 세션이 여러 번 반복될 때 어떻게 흐름을 이어가는지, 진행 로그를 어떻게 관리하는지까지 구체적으로 설명합니다.

부록 — 설치부터 안티패턴까지

부록 A는 클로드 코드 설치와 환경 설정을 다룹니다. macOS, Windows, Linux 각각의 설치 명령, Native installer 우선 권고, 지원 계정 종류까지 공식 문서 기준으로 정리돼 있습니다. 팀 도입 시 온보딩 가이드로 그대로 쓸 수 있습니다.

부록 B의 안티패턴 카탈로그는 특히 현실적입니다. 레벨 1(컨텍스트 창 초과), 레벨 2(토큰 마비 3단계), 레벨 3(큐레이션), 레벨 4(피드백 품질) 순으로 에이전트가 망가지는 경로를 구체적으로 보여줍니다.

부록 C의 5분 셀프 진단 10항목은 팀에 공유하기 딱 좋습니다. claude doctor가 모든 항목 OK인지, 에이전트 수가 20개 미만인지, CLAUDE.md가 200줄 이하인지 등 월 1회 응급 점검으로 활용할 수 있습니다.

이 책을 읽고 나서 달라진 것

읽고 나서 코딩 실력이 느는 게 아니라, AI 에이전트에게 일을 맡기기 전에 먼저 멈추게 됩니다.

"이 에이전트가 혼자 이걸 해도 되는가?", "검증 단계가 분리돼 있는가?" 이 질문이 자동으로 나오기 시작해요. 에이전트에게 작업을 던지기 전에 구조부터 고민하게 됐고, 뭔가 꼬인다는 느낌이 들면 그게 모델 문제가 아니라 하네스 구조 문제라는 신호로 받아들이게 됐습니다.

"한 번 읽고 끝"이 아니라, 꽂아두고 실전에서 막힐 때마다 꺼내보는 기준서 같은 느낌입니다.

이런 분들께 강추

AI 코딩 도구를 쓰고 있지만 단일 에이전트의 한계를 느끼는 개발자

클로드 코드 같은 도구를 팀이나 조직에 도입하려는 리드 개발자

에이전트가 자기 실수를 왜 못 잡는지 구조적으로 이해하고 싶은 분

하네스라는 단어를 들어봤지만 막상 어디서 시작해야 할지 모른 분

프롬프트 엔지니어링이나 모델 내부 지식 없이도, git과 마크다운 파일만 다룰 수 있다면 충분합니다.

댓글로 여러분은 AI 에이전트가 예상치 못한 행동을 했던 경험이 있으신지 공유해 주세요!

yes24 바로가기