홈앤서비스 SK BROADBAND

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

[ 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 팀
_시나리오 - “로컬에선 잘 되는데요”
_팀 구성
_워크플로
_핵심 파일 훑어보기
_응용 가이드
_마무리 - 스케일별 하네스 진화

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