하네스 엔지니어링 with 클로드 코드 - AI 에이전트 팀을 설계·운영하는 개발자의 실전 가이드, 누구나 프로처럼 실전 AI

[ 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 오케스트레이터
_리더는 이벤트 루프, 팀원은 피어
_세 가지 기본 도구 - 팀을 데이터 전달 방식으로 보기
_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 - 순환 구조와 Meta-Harness 루프
_안전장치 - 메타스킬도 폭주할 수 있다
_안티패턴

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

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

Chapter 10 하네스 등록과 진화
_하네스는 진화하는 생명체다
_포인터는 4줄, 시스템은 4층
_하네스 등록 - CLAUDE.md 템플릿과 실전용 변형
_진화의 두 관문 - Phase 0 현황 감사..

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