하네스 엔지니어링 with 클로드 코드 : AI 에이전트 팀을 설계 운영하는 개발자의 실전 가이드

황민호

저자:황민호
현재카카오에서AI개발생산성관련업무를담당하고있는개발자입니다.실무에서AI에이전트하네스를설계·운영하며,같은모델이환경에따라전혀다른결과를내는과정을직접관측해왔습니다.깃허브에서오픈소스활동을활발히이어가며하네스관련메타스킬,에이전트템플릿,스킬템플릿을공개하고갱신하고있습니다.이책에수록된템플릿다수도해당저장소에서비롯된것들입니다.
'AI에이전트가일하는환경을어떻게설계해야개인과조직모두의생산성이무너지지않고쌓이는가'를핵심화두로삼고있습니다.모델성능이매번새로운기록을세우는시대에도,최종결과를결정하는것은모델자체가아니라그것을감싸는하네스라는신념을갖고있습니다.

[Part01하네스란무엇인가]

Chapter01왜하네스인가
_스스로데이터를지운단일에이전트
_혼자일하는AI는자기실수를못본다
_모델의환경을바꿨을때일어난일들
_병목은능력이아니라구조다
_하네스=aroundthemodel
_하네스에대한세가지오해

Chapter0230분QuickStart
_[Step1]같은프롬프트,다른산출물
_[Step2]30분안에2인팀만들기
_자주틀리는세가지

[Part02하네스구성하기-에이전트·스킬·오케스트레이터]

Chapter03에이전트·스킬·오케스트레이터의책임분리
_2인팀을분해해보자
_한파일에다넣으면무엇이깨지는가
_세기둥,세질문
_세기둥은어떻게맞물리는가
_세기둥이섞이면생기는문제

Chapter04에이전트를정의한다는것
_어제잘굴러가던팀이오늘아침사라지는이유
_본문7개섹션-왜필요하고어떻게쓰는가
_가드레일-에이전트가할수없는것을파일로정하기
_프론트매터다섯필드와16개공식필드
_실전파일전체읽기-copy-editor.md
_책집필하네스의7가지에이전트관계도
_안티패턴

Chapter05스킬설계의기술
_스킬을썼는데왜호출이안될까
_원리1-Description이호출을결정한다
_원리2-ProgressiveDisclosure3단계
_원리3-Why-First원칙
_실물파일읽기-book-writer/SKILL.md
_구현-book-writer스킬을펼치다
_스킬검증-With/Without비교
_안티패턴

Chapter06오케스트레이터
_리더는이벤트루프,팀원은피어
_세가지기본도구-팀을데이터전달방식으로보기
_TeamCreate-팀은상수가아니라세션객체
_TaskCreate-공유작업큐와depends_on
_SendMessage-리더를거치지않는peer-to-peer채널
_에이전트파일의팀통신프로토콜섹션
_리더의역할
_데이터흐름
_실전예제-PR리뷰오케스트레이터SKILL.md
_292개에이전트사건
_TeamDelete와정리-세션당한팀,shutdown필수
_언제팀프리미티브를도입할까
_관측과경계면-팀을바깥에서보기
_안티패턴

[Part03하네스스킬로구성하기]

Chapter07메타하네스스킬과6단계파이프라인
_여섯번째팀을만들던날
_메타스킬이란무엇인가
_메타스킬이여는6단계파이프라인
_Phase1.도메인분석-질문을정제하는단계
_Phase2.팀아키텍처설계
_Phase3·4.에이전트와스킬-파일이없으면존재하지않는다
_Phase5.오케스트레이션
_Phase6.검증
_Phase0·7-순환구조와Meta-Harness루프
_안전장치-메타스킬도폭주할수있다
_안티패턴

Chapter086가지아키텍처패턴
_팀에는모양이있다
_에이전트를몇명으로쪼갤것인가
_패턴1.파이프라인-순서가의미를만든다
_패턴2.팬아웃·팬인-같은입력,다른관점
_패턴3.전문가풀-라우터+전문가
_패턴4.생성-검증-만들고검사하고다시만든다
_패턴5.감독자-런타임동적분배
_패턴6.계층적위임-총괄→팀장→실무자
_복합패턴은실전의기본값
_패턴선택기준-플로우차트와전환신호
_전통분산패턴과의대응
_안티패턴

Chapter09팀/서브에이전트/하이브리드
_팀을짤까,그냥각자시킬까
_실행모드별트레이드오프
_실행모드결정
_아키텍처패턴과실행모드
_구현-세템플릿골격
_[예시]제품런칭준비하네스
_안티패턴

Chapter10하네스등록과진화
_하네스는진화하는생명체다
_포인터는4줄,시스템은4층
_하네스등록-CLAUDE.md템플릿과실전용변형
_진화의두관문-Phase0현황감사와7-5운영루프
_피드백반영과변경이력-drift를방지하는물리적증거
_재실행과부분재실행
_심화-ADR과BuildtoDelete
_안티패턴
_하네스등록과진화통합체크리스트

[Part04하네스실전편]

Chapter11코드리뷰자동화팀
_시나리오-PR리뷰
_팀구성
_워크플로
_핵심파일훑어보기
_실행결과

Chapter12풀스택기능구현팀
_시나리오-로그인기능추가
_팀구성
_워크플로
_핵심파일훑어보기
_실행결과
_응용가이드

Chapter13레거시마이그레이션팀
_시나리오-3,500개의레거시테스트파일
_팀구성
_워크플로
_핵심파일훑어보기
_응용가이드

Chapter14디버깅/RCA팀
_시나리오-"로컬에선잘되는데요"
_팀구성
_워크플로
_핵심파일훑어보기
_응용가이드

[맺음말]스케일별하네스진화
[부록A]설치·환경설정
[부록B]안티패턴카탈로그+도구설계패턴
[부록C]트러블슈팅-자주막히는실패패턴20선
[부록D]토큰경제와레퍼런스아키텍처

"모델이아니라하네스가결과를결정한다"
카카오AI리더가직접검증한AI에이전트팀설계바이블

클로드코드,커서같은AI코딩도구가일상이된지금,실무개발자들이겪는가장큰문제는따로있다.단일에이전트는자기실수를잘보지못한다는것이다.2025년7월한기업에서벌어진프로덕션데이터삭제사고(에이전트가임원레코드를지우고"복구불가"라고거짓보고했던사건)는우리에게도먼이야기가아니다.혼자쓴PR을혼자머지하는구조가AI에이전트의기본값이기때문이다.이책은그구조적한계를정면으로다루며,해법으로하네스엔지니어링을제시한다.
저자황민호는카카오에서AI개발생산성을담당하며수십개도메인에하네스를직접적용해온개발자다.그가직접수행한A/B실험에서같은클로드모델이'.claude/'구성차이만으로49.5점에서79.3점으로뛰어올랐다."모델이아니라하네스가결과를결정한다"라는이책의핵심명제가단순한선언이아니라실제데이터임을보여주는기록이다.

Part1|하네스란무엇인가
단일AI에이전트는왜믿을수없는지그이유부터짚어보고,하네스의정의와핵심원리를정리한다.이어서30분안에굴러가는가장작은에이전트팀을빈디렉토리에서직접만들어본다.

Part2|하네스구성하기-에이전트·스킬·오케스트레이터
하네스를이루는세기둥을자세하게다룬다.에이전트는역할과가드레일을어떻게정의하는지,스킬은description한줄로호출여부를어떻게결정하는지,오케스트레이터는TeamCreate·TaskCreate·SendMessage로리더병목을어떻게해소하는지순서대로익힌다.개념설명에그치지않고이파트를끝내면직접팀을구성할수있는수준이된다.

Part3|하네스스킬로구성하기
Part2에서수행한팀구성과정을자동화하는메타스킬을다룬다.스킬이스킬을만든다는관점전환과6단계파이프라인,파이프라인·허브앤스포크·프로듀서-리뷰어등여섯가지아키텍처패턴을실제선택기준과함께펼친다.팀·서브에이전트·하이브리드실행모드선택,세션이바뀌어도자동트리거되는CLAUDE.md포인터설정,구성불일치(drift)감지까지,설계에서운영까지한흐름으로이어진다.

Part4|하네스실전편
코드리뷰자동화,풀스택기능구현,레거시마이그레이션,디버깅/RCA라는네개의실전팀을시나리오→팀구성→워크플로→핵심파일전문→실행결과→변형가이드→안티패턴순서로낱낱이공개한다.Airbnb가3,500개의React테스트를6주만에이전한사례,OpenAI가5개월간100만줄을생성하며수동코드0줄을유지한사례도여기에담겼다.이파트를읽고나면각자의도메인에맞는하네스를처음부터설계하는데필요한판단기준을파악하게될것이다.

이책의대상독자
하네스라는단어를들어봤지만막상시작하지못한개발자
클로드코드같은AI도구를쓰고있지만단일에이전트의한계에서벗어나지못한개발자
AI를혼자잘쓰는단계를지나팀이나조직에도입을시도하는리드개발자