바이브 코딩의 한계를 넘어! 완벽한 통제를 위한 하네스 엔지니어링

초기 AI 코딩 방식인 '바이브 코딩'은 단순히 프롬프트에 의존하기 때문에 맥락 유실, 품질의 비결정성, 기존 코드 파괴라는 치명적인 한계를 지니고 있습니다. 이 책은 이러한 문제를 해결하기 위해 AI 모델을 완벽하게 통제하는 '하네스 엔지니어링(Harness Engineering)' 패러다임을 제시하며, 개발자의 역할을 단순 코더에서 여러 AI 에이전트를 지휘하는 '오케스트레이터'로 격상시킵니다. 1장부터 7장에 걸쳐 클로드 코드의 기본 사용법부터 스킬 시스템, 서브에이전트 오케스트레이션, 그리고 외부 도구 및 세계와 연결하는 MCP 통합까지 상세히 다루어, 당장 실무에 적용할 수 있는 나만의 가상 개발팀 구축의 기반을 탄탄하게 다져 줍니다.

[목 차]

__추천인의 글

__저자와의 인터뷰

__이 책의 구성

PART 1 클로드 코드 마스터

CHAPTER 01 클로드 코드 시작하기

1 -1 클로드 코드와 에이전틱 코딩

__앤트로픽과 에이전틱 AI의 부상

__에이전틱 코딩이란

__에이전틱 루프: 클로드 코드의 동작 원리

__터미널에서 시작하는 AI 코딩

__컨텍스트 윈도우와 20만 토큰 컨텍스트의 의미

__컨텍스트 윈도우 관리 전략

__다섯 가지 접근 영역과 핵심 기능

__엔터프라이즈 환경에서의 클로드 코드

1 -2 클로드 코드 설치

__운영체제별 설치 방법

__인증 설정

__버전 관리와 업데이트 전략

1 -3 클로드 코드 CLI 기초

__대화형 모드와 비대화형 모드

__다양한 실행 플래그

__시스템 상태 진단과 문제 해결

__체크포인트와 되감기 시스템

1 -4 프로젝트로 특징 이해하기

__프로젝트 컨텍스트의 이해

__간단한 프로그램 작성

__파일 읽기와 쓰기 패턴

__깃 통합

__효과적인 작업 관리

__마무리

CHAPTER 02 워크플로와 설정

2 -1 기본 작업 방식

__탐색-계획-구현-커밋 워크플로

__탐색과 분석

__점진적 개발 전략

__깃 통합 워크플로

__비대화형 모드에서의 세션 재개

__파이프와 클로드

2 -2 설정 관리

__settings.json 설정과 우선순위

__기본 설정 옵션

__프로젝트별 설정 전략

__환경 변수 관리

__팀 표준 설정 구축

__민감한 파일 보호

__도구별 설정

__클로드 코드의 다섯 가지 확장 도구 비교

2 -3 IAM 권한 관리

__IAM 개념

__파일 및 명령 권한 설정

__도구별 권한 체계

__안전한 실행 환경 구축

__권한 문제 해결

__보안 유의 사항

__권한 설정 실무 예시

__데이터 사용 정책

__데이터 보존 기간

__원격 분석과 비활성화 옵션

2 -4 모델 구성과 API 최적화

__모델 별칭 시스템 이해하기

__모델 설정 방법의 우선순위

__환경 변수를 통한 모델 별칭 커스터마이징

__프롬프트 캐싱 이해와 최적화

__모델 선택 전략

CHAPTER 03 에이전트 스킬

3 -1 클로드 스킬의 개념과 구조

__컨텍스트 윈도우는 공용 자산이다

__스킬의 유형

__SKILL.md 파일 구조

__세 단계 점진적 작동 방식

__스킬 컨텍스트 비용

__도구 접근 권한 제한

3 -2 스킬 사용과 개발

__스킬 목록과 스킬 조합

__커스텀 스킬 개발

__스킬에서 환각 방지 지침 작성

__코드 실행 통합

__테스트와 검증 방법

3 -3 스킬 고급 사용과 최적화

__동적 스킬 로딩 패턴

__스킬 성능 최적화

__스킬 버전 관리

__팀 스킬 개발

__디버깅 기법

__재사용 가능한 스킬 패턴

__스킬 문서화 유의 사항

__스킬의 격리 실행: context : fork 메커니즘

CHAPTER 04 서브에이전트

4 -1 서브에이전트의 개념과 아키텍처

__에이전트 위임 패턴: 오케스트레이터-워커

__단일 책임 원칙과 서브에이전트

__컨텍스트 엔지니어링 원칙

__에이전트 체인과 병렬 실행

__언제 서브에이전트를 사용하는가

4 -2 서브에이전트 사용하기

__사용 가능한 서브에이전트 목록

__에이전트 호출 문법

__에이전트 결과 통합

__작업 재개 기능 활용

__에러 처리 및 복구

__서브에이전트 성능 측정

4 -3 커스텀 서브에이전트 개발과 스킬 주입

__서브에이전트 정의 파일 구조

__YAML 프론트매터 완전 가이드

__프롬프트 작성 가이드

__에이전트 테스트와 최적화

__스킬 주입 예제

4 -4 에이전트 팀

__에이전트 팀의 핵심 개념

__팀 생성과 생애 주기 관리

__컨텍스트와 권한

__메시지 전달 시스템

__태스크 조정 시스템

__파일 소유권 전략

__서브에이전트와 에이전트 팀

4 -5 CLI 기반 동적 에이전트 활용

__- -agent 플래그: 기존 에이전트 직접 실행

__에이전트 해석 과정

__CLI 에이전트와 에이전트 팀의 관계

CHAPTER 05 출력 인터페이스

5 -1 출력 스타일 커스터마이징

__출력 스타일의 핵심 개념

__내장 출력 스타일 살펴보기

__출력 스타일 변경 방법

__커스텀 출력 스타일 생성하기

__관련 기능과의 비교

__팀 표준 출력 스타일 구축

__스타일 검증과 다국어 출력

__출력 스타일에서 환각 방지 지침

5 -2 상태 표시줄

__상태 표시줄 설정 방법

__상태 표시줄 스크립트 작동 원리

__Bash로 작성한 여러 가지 상태 표시줄 스크립트

__파이썬과 Node.js로 작성한 상태 표시줄 스크립트

__헬퍼 함수를 활용한 모듈화와 ANSI 코드

__성능 최적화 전략

__문제 해결

5 -3 대화형 모드 활용

__고급 제어 기능

__단축키 빠른 참조

CHAPTER 06 메모리와 대화 세션 관리

6 -1 메모리 시스템 이해하기

__네 가지 계층적 메모리

__자동 메모리

__CLAUDE.md 가져오기와 조건부 로딩

__메모리 시스템을 자유자재로

__메모리 최적화와 장기 작업 관리

__모듈형 룰 시스템

__사용자 수준 룰과 고급 기능

6 -2 체크포인팅과 복구 시스템

__/rewind 화면과 되감기 사용법

__체크포인팅의 제한 사항과 대응 전략

__체크포인팅과 깃

__다중 체크포인트와 스마트 복구

__실험 주도 개발을 위한 체크포인팅 워크플로

6 -3 세션 관리 전략

__컨텍스트 윈도우 최적화와 세션 복구

__다중 세션 관리

__세션 데이터 보관

__협업에서의 세션 관리

__장기 프로젝트에서의 세션 전략

CHAPTER 07 자동화

7 -1 비대화형 모드와 스크립트 자동화

__주요 플래그

__프로그래밍 활용

__비대화형 모드 사용 시 고려사항

7 -2 훅 시스템

__훅 이벤트

__종료 코드와 결정 제어 체계

__훅 구성 파일과 우선순위

__매처 패턴 이해하기

__프롬프트 기반 훅과 에이전트 기반 훅

__비동기 훅

__프론트매터 훅과 에이전트 범위 훅

__실용적인 훅 예제

__훅 실행의 특성과 디버깅

__체크포인팅 보완을 위한 훅 활용

__HTTP 훅

7 -3 MCP 통합으로 외부 세계와의 연결 확장

__MCP 전송 방식

__주요 MCP 서버 활용 사례

__MCP 서버 설정과 구현 방법

__훅과 MCP의 연동 전략

__유의 사항

7 -4 플러그인 시스템 이해하기

__플러그인 구조

__컴포넌트 유형

__플러그인과 프로젝트 설정의 관계

__플러그인 설치 범위

__LSP 서버 지원

__앤트로픽 공식 마켓플레이스

__플러그인 설치, 활성화, 비활성화, 제거

__팀 플러그인 워크플로와 자동 설치

__실전 플러그인, 코드 품질 도구

__로컬 테스트 환경 설정과 개발 워크플로

__플러그인 캐싱

__플러그인 배포와 마켓플레이스 게시

PART 2 MoAI -ADK와 실전 에이전틱 코딩

CHAPTER 08 클로드 코드와 MoAI -ADK

8 -1 하네스 엔지니어링과 MoAI -ADK

__에이전트 하네스, MoAI -ADK

__하네스 엔지니어링

__MoAI -ADK가 해결하는 문제

__MoAI -ADK 실행 엔진

8 -2 설치와 초기 설정

__설치 방법

__프로젝트 초기화와 설정

__환경 진단

__업데이트

8 -3 아키텍처

__4계층 구조

__MoAI의 지침, CLAUDE.md

__Rules 시스템

__settings.json: 네 단계 스코프 시스템

__.mcp.json: MCP 서버 구성

__응답 스타일 시스템

8 -4 개발 방법론, TDD와 DDD

__SPEC과 EARS 형식

__DDD

__이진 방법론

8 -5 TRUST -5 품질 프레임워크

__다섯 가지 원칙

__LSP 품질 게이트

__Loop Engine : 자율 품질 루프

__TRUST -5와 LSP 매핑

__품질 리포트 생성

8 -6 에이전트 생태계

__Manager 에이전트 그룹

__Expert 에이전트 그룹

__Builder 에이전트 그룹

__에이전트 선택 의사결정 트리

__에이전트 정의 파일 구조

CHAPTER 09 MoAI -ADK 워크플로

__/moai project: 프로젝트 문서 생성

__신규 프로젝트 시작하기

__기존 프로젝트에 도입하기

9 -1 plan -run -sync 핵심 워크플로

__/moai plan : 명세서 생성

__/moai run : TDD/DDD 구현

__/moai sync : 코드, SPEC, 프로젝트 문서 동기화

__/moai : 자율 자동화 모드

__단계 전환 조건

9 -2 서브에이전트 심층 활용

__Agent 도구의 기본 사용법

__에이전트 호출 패턴

__병렬 실행 전략

__에이전트 간 통신과 컨텍스트 격리

__에이전트 재개

__실전 오케스트레이션 예시

9 -3 에이전트 팀, 팀 기반 병렬 개발

__에이전트 팀 활성화

__실행 모드와 팀 모드의 조합

__디스플레이 모드와 환경 요구 사항

__팀 생성과 구성

__팀 커뮤니케이션

__plan 단계 팀 워크플로

__run 단계 팀 워크플로

__서브에이전트와 에이전트 팀 비교

9 -4 스킬 생태계와 점진적 공개

__스킬 분류 체계

__YAML 프론트매터 스키마

__점진적 공개와 토큰

__트리거 시스템: 자동 로딩의 방식

__슬래시 명령어 연동

__스킬과 에이전트 연동

9 -5 빌더 에이전트와 스킬 만들기

__builder -agent : 커스텀 에이전트 생성

__builder -skill : 커스텀 스킬 생성

__도구 권한 설계 원칙

__실전: 보안 검사 에이전트 만들기

9 -6 훅 시스템과 MCP 통합

__MoAI -ADK의 훅 이벤트 체계

__MCP 통합

__훅과 MCP의 시너지

9 -7 깃 작업 트리: 병렬 SPEC 개발

__MoAI -ADK의 작업 트리 통합

__작업 트리 하위 명령어

__병렬 SPEC 개발 패턴

__작업 트리 복구와 정리

9 -8 슬래시 명령어와 CLI 유틸리티

__슬래시 명령어

__CLI 유틸리티 명령어

__moai statusline: 상태 표시줄 설정

CHAPTER 10 에이전틱 코딩 실습: 스네이크 게임 만들기

STEP 1 초기화: 프로젝트 초기화와 문서 생성

__01 게임 개발 준비

__02 moai init으로 프로젝트 시작

__03 moai project로 프로젝트 문서 생성

__04 생성한 프로젝트 문서 확인

__05 클로드 코드의 프로젝트 컨텍스트 인식

__06 HTML5 Canvas와 게임 루프 패턴

__다음 단계 미리보기

STEP 2 plan: 스펙 문서로 게임 규칙 정의하기

__01 클로드에 게임 규칙 설명하기

__02 스펙 문서 생성

__03 구현 계획: 마일스톤과 파일 매핑

__04 수용 테스트 시나리오

__05 단일 SPEC과 모듈형 SPEC

__06 컨텍스트 윈도우 관리

STEP 3 run: TDD 방식으로 모던 스네이크 게임 구현하기 .

__01 클로드에 구현 요청하기

__02 전체 구현 결과 요약

STEP 4 sync: 문서화와 완료

__Phase 1 : 분석 및 계획 수립

__Phase 2 : 문서 동기화

__Phase 3 : 깃 커밋 생성

__Phase 4 : 완료 요약

__버그 수정: /moai fix와 /moai loop

__워크플로 전체 복습

__실습을 마치며

APPENDIX A 개발자를 위한 실전 팁

__A -1 클로드 코드 개발자의 실전 노하우

__A -2 에이전틱 코딩을 위한 SaaS/BaaS 서비스 가이드

__A -3 MCP와 CLI 도구 선택 전략

__A -4 바이브 디자인 Pencil MCP 설치와 활용

__A -5 클로드 코드에서 GLM -5 사용

__A -6 매니지드 에이전트

__에필로그

__찾아보기

이경록 테디노트 (유튜브, 랭체인 앰배서더)

나만의 하네스를 구축하고 에이전트 오케스트레이션으로 완성하는 진짜 생산성

클로드 코드를 단순히 ‘쓰는’ 수준에 머물 것인가, 아니면 나만의 하네스를 구축하고 에이전트를 오케스트레이션하여 진짜 생산성을 끌어낼 것인가? 이 책은 바로 그 차이를 만들어 주는 책입니다.

MoAI를 직접 설계하고 오픈소스로 공개한 Goos 님이 쓴 만큼, 담긴 내용의 깊이와 실용성은 타의 추종을 불허합니다. 뜬구름 잡는 이론이 아닌 당장 실전에 써먹을 수 있는 내용만을 다뤄 온 저자의 철학이 이 책에도 고스란히 녹아 있습니다. 스킬 설계부터 서브에이전트 오케스트레이션, MCP 통합, TDD 기반의 MoAI-ADK까지, 단순한 기능 소개서가 아닌 고품질의 결과물을 반복적으로 만들어내기 위한 방법론이 담겨 있습니다. 에이전틱 코딩을 제대로 시작하고 싶은 분께 강력히 추천합니다.

김태영 ((주)인공지능팩토리 CEO, 마이크로소프트R D & AI MVP, 랭체인 앰배서더)

국내 최고 바이브 코더의 통찰, AI 에이전트 해부학__

저는 커뮤니티 세미나에서 이 책의 저자를 ‘국내 최고의 바이브 코더’라고 소개한 적이 있습니다. 기본에 충실하면서도 자신만의 소프트웨어 개발 철학을 갖추고, 강의와 실무 현장에서 수많은 (비)개발자와 호흡하며 무엇이 실제로 유효한지, 그리고 어떻게 써야 가장 효율적인지를 누구보다 깊이 이해하고 계신 분이기 때문입니다.

이 책은 단순한 클로드 코드 사용서를 넘어, AI 에이전트의 구조와 작동 원리를 해부학처럼 정교하게 풀어냅니다. 해부학이 의학부터 재활, 스포츠, 미술, 로봇공학에 이르기까지 폭넓게 활용되듯, 이 책 또한 에이전트의 뼈대와 움직임을 이해하게 함으로써 입문자에게는 길잡이가, 개발자에게는 설계의 기준을 제시하는 소중한 지침서가 될 것입니다.

김영우 (《Do it! 쉽게 배우는 R 데이터 분석》 저자, 데이터 분석가, 유튜브 데이터홀릭 운영자)

혼란의 시대, 진짜 에이전틱 코딩으로 안내하는 가이드북

SNS에서 조금 이상한 사람을 발견했습니다. AI 작동 원리와 한계를 끝까지 파헤치겠다며 온갖 기상천외한 방법으로 토큰을 쏟아부으면서, 이것은 차라리 고문이 아닐까 싶은 지경까지 AI를 실험하는 사람이었습니다. 그러더니 그 과정에서 알게 된 온갖 노하우와 지식을 아낌없이 사람들과 공유하고, 결국에는 프롬프트 몇 문장만 입력하면 소프트웨어가 뚝딱 완성되는 MoAI-ADK를 개발해 배포하기 시작했습니다. 심지어 제약 없이 마음대로 쓰라며 Copyleft 라이선스로 말이죠.

그가 바로 이 책의 저자, Goos 님이었습니다. 끊임없이 쏟아지는 모델과 도구로 혼란스러웠던 시기에 Goos 님을 알고 ‘이제 이분만 따라가면 되겠구나’ 하고 안도하는 마음이 들었습니다. 그런 Goos 님의 노하우를 정리한 책이 세상에 나왔다니, 반가울 수밖에요.

그동안 이러저러한 코딩 도구를 찔러 보며 정처 없이 떠돌았다면, 이제 이 책을 보며 클로드 코드와 MoAI-ADK의 세계에 안착하세요. ‘이게 진짜 에이전틱 코딩이구나’ 하며 감동하고, 새로운 아이디어가 샘솟고, 마치 슈퍼히어로가 된 기분이 들 겁니다.

조대협 (Google Cloud Principal Architect)

입문자와 고급 사용자 누구에게나 통하는 책

한마디로 매우 깊이가 있는 책입니다. 양산형 입문서와 달리, 스킬, 에이전트 등 고급 기능까지 깊이 있게 다루었고, 실전 예제를 통해서 활용 방법까지 자세하게 설명합니다. 클로드 코드를 사용한다면 입문자와 고급 사용자 상관없이 반드시 읽어야 하는 책입니다.

권승민 (블루툴스 대표, 풀스택 에이전틱 코더)

집요한 설계자가 제안하는 새로운 일의 문법, 분해하고 위임하고 검증하라

AI로 일하는 방식을 근본부터 바꾸고 싶다면 이 책을 권합니다. MoAI-ADK를 설계하고 발전시켜 온 과정에서 다듬어진 문제의식과 방법론에는 집요함만이 닿을 수 있는 섬세함이 배어 있습니다. 이 책에서는 문제를 어떻게 분해하고, 에이전트에 어떻게 위임하며, 결과를 어떤 기준으로 검증할 것인가라는 사고의 구조를 다룹니다.

AI를 단순한 보조 도구가 아니라 파트너로 삼고 싶다면 분명한 지침이 되어 줄 책입니다.

김명호 (김명호 영어 강사, 바이브 코더)

결과물의 격을 바꾸는 에이전틱 코딩의 정석을 배우고 싶은 분들께

문과 출신 영어 강사인 제가 개발에 발을 들인 건 클로드 코드와 Goos 님 덕이었습니다. 처음에는 클로드 코드와 MoAI의 명령어조차 구분하지 못했으나, 이제는 개발 속도가 빨라지고, 품질 높은 결과물을 생산할 수 있게 되었습니다. Goos 님이 강의에서 오랫동안 강조했던 에이전틱 코딩은 비개발자인 제 단점을 보완하고 AI의 장점을 극대화해 주었습니다. 좋은 모델과 많은 토큰만으로는 한계가 있습니다. 에이전틱 코딩이라는 올바른 방법론이 뒷받침될 때 비로소 결과물 수준이 달라진다는 것을 몸소 체감했습니다. 이 책은 바로 그 방법론을 체계적으로 담고 있습니다.

오롯이 나누는 사람Giver인 Goos 님의 철학이 담긴 MoAI-ADK와 평소 나누는 정보글 덕분에 배우고 성장할 수 있었습니다. 먼저 책을 읽어 보니 강의와 글을 포함해 나누고자 하는 마음까지도 책에 잘 담겨 있었습니다. 비개발자이든, 개발자이든 클로드 코드와 에이전틱 코딩을 하며 한 단계 도약하고 싶으신 모든 분께 이 책을 진심으로 추천드립니다.

김해영 (카카오페이 기술전략실 리더)

하네스 엔지니어링으로 여는 실전의 문

에이전틱 코딩을 실무에 어떻게 적용해야 하는지 저마다 길을 찾고 있는 이 순간, 이 책은 그 여정에 큰 도움을 줄 수 있습니다. 제품을 빠르고 쉽게 만드는 차원을 넘어, 일하는 방식을 설계하고 AI가 스스로 잘 일할 수 있는 방법을 실무자 시각으로 풀어냅니다. 또한 에이전틱 코딩을 어떻게 적용해야 할지 막막했던 분들에게는 해결의 단초를 제공하며, 하네스 엔지니어링 패러다임에서 실무 수준의 방향을 제시합니다.

제목에 들어간 ‘실전’은 결코 과장이 아닙니다. 동시에 이 책의 깊이가 깊다고 해서 클로드 코드를 처음 접하는 사람에게 어려운 수준의 책은 아닙니다. 기초부터 차근차근 안내하기 때문에 누구나 에이전틱 코딩의 세계에 자연스럽게 입문할 수 있고, 그 위에서 실전 수준의 깊이까지 도달할 수 있습니다.

박종우 (디지털 드로잉 작가, 바이브 코더)

에이전틱 코딩이 제시하는 새로운 협업의 표준_

《클로드 코드로 시작하는 실전 에이전틱 코딩》은 인공지능과 개발자가 협업하는 미래의 방식을 가장 앞서 제시하는 가이드북입니다. IT 분야에서 다양한 경험을 쌓은 저자가 오랜 시간 다양한 AI와 클로드 코드를 직접 다루며 쌓아 온 실전 노하우와 온 오프라인 커뮤니티를 통해 수많은 유저와 소통하며 정제한 지식이 고스란히 담겨 있습니다.

책은 단순히 명령어 사용법을 나열하는 데 그치지 않고, 개발 환경 구축부터 복잡한 리팩터링, 자동화 테스트까지 이어지는 일련의 과정을 저자의 깊이 있는 통찰력으로 풀어내어 초보자부터 숙련된 개발자까지 모두가 새로운 영감을 얻을 수 있습니다.

AI 시대를 준비하는 모든 창작자와 개발자에게 이 책은 든든한 나침반이 되어 줄 것입니다. 에이전틱 코딩의 정수를 경험하고 싶다면 주저 없이 펼쳐 보시길 권합니다.

채승엽 ((주)팝콘사 대표, 자동차 도메인 AX 리더)

AI 코딩 분야의 ‘수학의 정석’, 원리부터 실무까지 꿰뚫는 필독서

단순한 따라하기식 입문서를 넘어, 에이전틱 루프, 컨텍스트 격리, 스킬 시스템의 내부 원리와 실무 적용까지 균형 있게 담은 책입니다. 더불어 저자님이 배포한 MoAI-ADK를 시작부터 지금까지 매일 직접 분석하고 사용해 본 사용자로서, 하네스(MoAI-ADK)는 AI가 어떻게 진화하는지 가장 깊이 배울 수 있는 거의 유일한 오픈소스라고 확신합니다. 이 둘을 가장 잘 설명한 이 책은 반복해 읽고 익히며 내공을 쌓아 가는 ‘AI 코딩 분야 수학의 정석’입니다.

AI가 코드를 작성하는 시대에 개발자의 역할을 고민하는 모든 분께 이 책을 권합니다.