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

단일 에이전트 대신 ‘에이전트 팀’을 설계하라 클로드 코드로 구축하는 최초의 하네스 실전 가이드 AI 에이전트를 도구로 쓰는 단계를 넘어, 스스로 일하는 에이전트 팀을 직접 설계하고 운영하는 방법인 하네스 엔지니어링을 체계적으로 정리한 최초의 실전서다. 이 책의 저자이자, 카카오의 AI 리더 황민호(로빈 황)가 공개한 하네스 관련 오픈소스 자료는 깃허브에서 3천 개 이상의 별(star)을 받으며 이미 개발자 커뮤니티의 주목을 받은 바 있다. 하네스란 모델의 가중치를 건드리지 않고, 모델 바깥에 권한·도구·검증·관측을 설계해 에이전트가 혼자 움직이게 만드는 환경이다. 단일 에이전트의 구조적 한계부터, 에이전트 · 스킬 · 오케스트레이터라는 하네스 세 기둥의 설계 원칙, 스킬이 스킬을 만드는 메타스킬과 여섯 가지 아키텍처 패턴, 코드 리뷰·풀스택 구현·레거시 마이그레이션·디버깅 팀의 실전 사례까지 마크다운 파일을 직접 만들어 보며 익힐 수 있도록 설계되었다.

[ Part 01 하네스란 무엇인가 ] Chapter 01 왜 하네스인가 _스스로 데이터를 지운 단일 에이전트 _혼자 일하는 AI는 자기 실수를 못 본다 _모델의 환경을 바꿨을 때 일어난 일들 _병목은 능력이 아니라 구조다 _하네스 = around the model _하네스에 대한 세 가지 오해 Chapter 02 30분 Quick Start _[Step 1] 같은 프롬프트, 다른 산출물 _[Step 2] 30분 안에 2인 팀 만들기 _자주 틀리는 세 가지 [ Part 02 하네스 구성하기 ? 에이전트·스킬·오케스트레이터 ] Chapter 03 에이전트·스킬·오케스트레이터의 책임 분리 _2인 팀을 분해해보자 _한 파일에 다 넣으면 무엇이 깨지는가 _세 가지 핵심 요소 _세 가지 핵심 요소를 파일로 확인하기 _세 가지 핵심 요소는 어떻게 동작하는가 _세 가지 핵심 요소가 섞이면 생기는 문제 Chapter 04 에이전트를 정의한다는 것 _어제 잘 굴러가던 팀이 오늘 아침 사라지는 이유 _본문 7개 섹션 ? 왜 필요하고 어떻게 쓰는가 _가드레일 ? 에이전트가 할 수 없는 것을 파일로 정하기 _프론트매터 다섯 필드와 16개 공식 필드 _핵심 파일 읽기 ? copy-editor.md _책 집필 하네스의 7개 에이전트 관계도 _안티패턴 Chapter 05 스킬 설계의 기술 _스킬을 썼는데 왜 호출이 안 될까 _원리 1 ? Description이 호출을 결정한다 _원리 2 ? Progressive Disclosure 3단계 _원리 3 ? Why-First 원칙 _핵심 파일 읽기 ? book-writer/SKILL.md _구현 ? book-writer 스킬을 펼치다 _스킬 검증 ? With/Without 비교 _안티패턴 Chapter 06 오케스트레이터 _3인이 넘으면 리더가 무너진다 _리더는 이벤트 루프, 팀원은 피어 _세 가지 기본 도구 ? 팀을 데이터 전달 방식으로 보기 _TeamCreate ? 팀은 상수가 아니라 세션 객체 _TaskCreate ? 공유 작업 큐와 depends_on _SendMessage ? 리더를 거치지 않는 peer-to-peer 채널 _에이전트 파일의 팀 통신 프로토콜 섹션 _리더의 역할 _데이터 흐름 _실전 예제 ? PR 리뷰 오케스트레이터 SKILL.md _292개 에이전트 사건 _TeamDelete와 정리 ? 세션당 한 팀, shutdown 필수 _언제 팀 프리미티브를 도입할까 _관측과 경계면 ? 팀을 바깥에서 보기 _안티패턴 [ Part 03 하네스 스킬로 구성하기 ] Chapter 07 메타 하네스 스킬과 6단계 파이프라인 _여섯 번째 팀을 만들던 날 _메타스킬이란 무엇인가 _메타스킬이 여는 6단계 파이프라인 _Phase 1. 도메인 분석 ? 질문을 정제하는 단계 _Phase 2. 팀 아키텍처 설계 _Phase 3·4. 에이전트와 스킬 ? 파일이 없으면 존재하지 않는다 _Phase 5. 오케스트레이션 _Phase 6. 검증 _Phase 0·7 ? 순환 구조와 메타 하네스 루프 _안전장치 ? 메타스킬도 폭주할 수 있다 _안티패턴 Chapter 08 6가지 아키텍처 패턴 _팀에는 모양이 있다 _에이전트를 몇 명으로 쪼갤 것인가 _패턴 1. 파이프라인 ? 순서가 의미를 만든다 _패턴 2. 팬아웃·팬인 ? 같은 입력, 다른 관점 _패턴 3. 전문가 풀 ? 라우터 + 전문가 _패턴 4. 생성-검증 ? 만들고 검사하고 다시 만든다 _패턴 5. 감독자 ? 런타임 동적 분배 _패턴 6. 계층적 위임 ? 총괄 → 팀장 → 실무자 _복합 패턴은 실전의 기본값 _패턴 선택 기준 - 플로우차트와 전환 신호 _전통 분산 패턴과의 대응 _안티패턴 Chapter 09 팀 / 서브에이전트 / 하이브리드 _팀을 짤까, 그냥 각자 시킬까 _실행 모드별 트레이드오프 _실행 모드 결정 _아키텍처 패턴과 실행 모드 _구현 ? 세 템플릿 골격 _[예시] 제품 런칭 준비 하네스 _안티패턴 Chapter 10 하네스 등록과 진화 _하네스는 진화하는 생명체다 _포인터는 4줄, 시스템은 4층 _하네스 등록 ? CLAUDE.md 템플릿과 실전용 변형 _진화의 두 관문 ? Phase 0 현황 감사와 7-5 운영 루프 _피드백 반영과 변경 이력 ? drift를 방지하는 물리적 증거 _재실행과 부분 재실행 _심화 ? ADR과 Build to Delete _안티패턴 _하네스 등록과 진화 통합 체크리스트 [ Part 04 하네스 실전편 ] Chapter 11 코드 리뷰 자동화 팀 _시나리오 ? PR 리뷰 _팀 구성 _워크플로. _핵심 파일 훑어보기 _실행 결과 _응용 가이드 Chapter 12 풀스택 기능 구현 팀 _시나리오 ? 로그인 기능 추가 _팀 구성 _워크플로 _핵심 파일 훑어보기 _실행 결과 _응용 가이드 Chapter 13 레거시 마이그레이션 팀 _시나리오 ? 3,500개의 레거시 테스트 파일 _팀 구성 _워크플로 _핵심 파일 훑어보기 _응용 가이드 Chapter 14 디버깅 / RCA 팀 _시나리오 ? “로컬에선 잘 되는데요” _팀 구성 _워크플로 _핵심 파일 훑어보기 _응용 가이드 _마무리 ? 스케일별 하네스 진화 [맺음말] 스케일별 하네스 진화[hw12.1]’ [부록 A] 클로드 코드 설치·환경 설정 [hw13.1] [부록 B] 안티패턴 카탈로그 + 도구 설계 패턴 [부록 C] 트러블슈팅 ? 자주 막히는 실패 패턴 20선 [부록 D] 토큰 경제와 레퍼런스 아키텍처