하네스 엔지니어링, 클로드 코드로 내 일을 대신하는 AI 에이전트 만들기

★ 프롬프트만 잘 쓰면 끝? 이제는 AI가 일할 '환경'을 설계할 차례!
★ 개발자의 전유물이던 하네스 엔지니어링, 실무자를 위한 업무 자동화 무기로

AI 활용 방식은 세 단계로 발전해왔다. 질문과 지시를 다듬는 프롬프트 엔지니어링, 필요한 정보와 맥락을 제공하는 컨텍스트 엔지니어링 그리고 AI가 안정적으로 일할 수 있는 환경 전체를 설계하는 하네스 엔지니어링이다. 하네스 엔지니어링은 AI가 맡은 일의 범위를 벗어나지 않고 끝까지 수행하도록 역할과 규칙, 도구와 기억, 검증과 재시도 절차까지 체계적으로 설계한다.

그동안 하네스 엔지니어링은 코드 리뷰나 앱 구현처럼 주로 개발 현장의 사례를 중심으로 다뤄졌다. 이 책은 그 문턱을 낮춰 회의록 정리, 이메일 작성, 데이터 분석부터 사내 문서 검색, 반복 보고서 자동화, 주식 종목 추천, 개인 자산 진단까지 익숙한 업무와 일상 속 사례로 하네스 엔지니어링을 익히게 한다. 복잡한 코드 구현은 클로드 코드에 맡기고, 독자는 한국어로 AI가 어떻게 일해야 할지 정하고 결과를 확인하며 다듬는 데 집중한다. 덕분에 코딩 경험이 없어도 단계별 실습을 따라가며 자신만의 자동화 에이전트를 만들 수 있다. 실습 프롬프트와 예제 파일은 물론, 저자에게 직접 질문할 수 있는 Q&A 오픈채팅방까지 제공해 막힘없이 실습을 이어갈 수 있도록 돕는다.

· 카카오톡 오픈채팅방: open.kakao.com/o/pjafVfLi
· 프롬프트 모음: bit.ly/45YTEbH

★ 하네스를 이루는 7가지 핵심 부품을 하나씩 직접 만든다
★ 무조건 자동화는 금물! '하네스를 적용할 일'을 가려내는 안목까지

하네스를 시스템 프롬프트, 도구/MCP, 메모리, 서브 에이전트라는 4가지 핵심 요소와 훅, 스킬, 스펙이라는 3가지 전술 요소로 나누어 하나씩 직접 구축해본다. 각 요소가 어떤 역할을 하는지 개별 실습으로 익힌 뒤 실제 에이전트에 하나씩 결합해보며 AI가 어떻게 작동하는지 이해한다. 덕분에 결과가 기대와 다를 때 무엇이 문제인지 짚어보고, 어느 부분을 보완해야 할지 판단하는 실전 감각까지 기를 수 있다.

중요한 것은 기능을 무작정 많이 늘리는 것이 아니다. 이 책에선 에이전트를 만들기 전에 해당 업무에 하네스를 적용할 가치가 있는지부터 따져보게 한다. 같은 형식의 일이 반복되는지, 일정한 결과 형식과 품질이 필요한지, 반복되는 실패가 있는지, 합격 기준을 명확히 정할 수 있는지 등 7가지 기준으로 업무의 적합성을 판단한다. 모든 일을 에이전트로 전환하기보다 어떤 일에 AI를 투입해야 시간과 노력을 가장 효과적으로 줄일 수 있는지 판단하는 안목까지 길러준다.

★ 코드는 AI가, 업무 기준은 내가! 한국어 '스펙'으로 에이전트를 만든다
★ 클로드 코드부터 헤르메스까지, 한 번 만든 업무 기준을 그대로 재사용한다

모든 실습은 '결과물 정하기 → 한국어로 스펙 작성하기 → 클로드 코드에 구현 맡기기 → 결과 확인하기 → 스펙 다듬기'의 흐름으로 진행된다. 코드 작성은 클로드 코드에 맡기고, 독자는 이 업무를 어디까지 처리할지, 무엇을 해서는 안 되는지, 어떤 상태를 완료로 볼지처럼 AI가 일할 기준과 범위를 정하는 데 집중한다. 결과를 확인하고 수정이 필요하면 코드를 직접 고치는 대신 원하는 결과에 가까워질 때까지 스펙을 다듬는 과정을 반복한다.

이 방식의 장점은 도구가 바뀌어도 내가 만든 스펙은 자산으로 남는다는 것이다. 코드는 도구나 모델에 따라 달라질 수 있지만, 에이전트의 역할과 작업 순서, 결과 형식 등을 정리한 스펙은 다른 환경에서도 재사용할 수 있다. 책 후반부에서는 같은 설계 방식을 오픈소스 에이전트 '헤르메스'로 확장해 폴더 자동 정리 비서와 작업에 따라 모델을 골라 쓰는 라우터까지 만들어본다. 이어 비용 점검과 장애 대응, 도구 선택까지 다루며 에이전트를 만드는 데서 끝나지 않고 오래 안정적으로 운영하는 방법까지 익힌다.

★이 책의 대상 독자
__챗GPT·클로드를 사용하지만 결과가 매번 달라 답답한 사람
프롬프트 수정만으로 해결되지 않던 문제의 원인을 하네스 관점에서 진단하고 개선하는 법을 배울 수 있다.

__보고서 작성·문서 검색·데이터 분석 등 반복 업무를 줄이고 싶은 실무자
실제 업무 기반의 예제를 직접 따라 하며 자신의 반복 작업을 손쉽게 자동화할 수 있다.

__새 AI 모델이 나올 때마다 에이전트를 다시 구축하고 싶지 않은 기획자·개발자
코드가 아닌 업무 목적과 규칙을 담은 스펙을 자산화하여 특정 도구에 묶이지 않는 자동화 구조를 만드는 법을 익힌다.

__업무 자동화가 필요한 1인 사업자·프리랜서, 조직의 AI 도입 담당자
어떤 업무부터 자동화할지 가려내는 판단 기준부터 비용 계산, 장애 대응, 도구 선택까지 실제 운영에 필요한 실전 노하우를 습득할 수 있다.

★이 책에서 만드는 에이전트
__회사 업무
01 회의록 작성 에이전트
02 회의록 양식 통일 에이전트
03 이메일 답장 에이전트
04 사내 문서 검색 에이전트
05 반복 보고서 자동화 에이전트
06 글쓰기 첨삭 에이전트

__개인 생활·자산
07 주식 종목 추천 에이전트
08 자산 진단·노후 계획 에이전트
09 카드 사용 내역 분석 에이전트
10 폴더 자동 정리 에이전트

__조사·분석·도구
11 다세션 리서치 에이전트
12 다단계 역할 분담형 리서치 에이전트
13 데이터 분석 에이전트
14 QR 코드 생성 에이전트
15 작업별 모델 선택 라우터 에이전트

| Part 01 | 에이전트 시대와 하네스 엔지니어링

Chapter 01 AI 에이전트 시대의 명암
1.1 AI 사용 방식의 변화: 챗봇에서 에이전트로
____챗봇과 에이전트의 차이
____에이전트 시대를 연 세 가지 사건
1.2 자율 에이전트 1세대의 흥망
1.3 에이전트가 무너지는 네 가지 패턴
____네 가지 실패 패턴
____네 가지 패턴에 내재된 문제: 환각과 비용 증가
1.4 같은 모델, 다른 환경: 성능 격차와 검증 부채

Chapter 02 하네스 엔지니어링이란 무엇인가
2.1 프롬프트에서 하네스로: 모델 활용 기술의 진화
____1단계: 프롬프트 엔지니어링
____2단계: 컨텍스트 엔지니어링
____3단계: 하네스 엔지니어링
2.2 하네스 엔지니어링의 정의와 핵심 공식
____하네스의 다섯 가지 패턴
2.3 하네스 엔지니어링이 적합한 업무를 판단하는 7가지 기준

Chapter 03 하네스의 구조 이해와 아우터 하네스 설계
3.1 하네스를 이루는 7가지 구성요소
____핵심 요소 4가지
____전술 3가지
3.2 이너 하네스와 아우터 하네스
3.3 아우터 하네스 만들기
____안티 패턴과 지속성: 도구가 바뀌어도 살아남는 환경

| Part 02 | 하네스 엔지니어링을 위한 환경 설정

Chapter 04 클로드 코드 설치와 실습 환경 세팅
4.1 핵심 도구 준비: 클로드 코드
____Git for Windows 설치
____Claude Pro 플랜 구독
____클로드 코드 설치
____클로드 코드 로그인
____클로드 코드 첫 실행하기
4.2 실습 재료 준비: Node.js와 파이썬
____Node.js 설치
____파이썬 설치
____클로드 코드에 클로드 API 키 등록하기
4.3 외부 서비스 연결 준비: API 키
____클로드 API 키 발급 및 크레딧 충전
____웹 검색용 Tavily API 키 발급
____환경 변수로 키 안전하게 관리하기

| Part 03 | 하네스 핵심 구성요소 실습

Chapter 05 실습을 위한 필독 사항과 진행 방식
5.1 실습 전 필독 사항
____실행 결과는 매번 다른 것이 정상이다
____코드보다 프롬프트와 스펙에 집중하자
____클로드 코드와 클로드 API는 서로 다른 서비스이다
____권한과 보안에 주의하자
____실습 환경을 미리 점검하자
____결과는 반드시 사람이 검증한다
5.2 실습 진행 방식
____진행 방식
____실습별 도메인 및 작성 파일
____실습 폴더 구조

Chapter 06 에이전트의 기본: 시스템 프롬프트, 도구와 MCP, 스킬
6.1 시스템 프롬프트
____실습 개요
____[실습] 회의록 작성 에이전트
____마무리
6.2 도구와 MCP
____실습 개요
____[실습] QR 코드 생성 에이전트
____마무리
6.3 스킬
____실습 개요
____[실습] 회의록 양식 통일 에이전트
____마무리

Chapter 07 실행 제어와 규모 확장: 훅, 메모리, 서브 에이전트
7.1 훅 - 진단형 재시도
____실습 개요
____[실습] 데이터 분석 에이전트
____마무리
7.2 훅 - 가드레일
____실습 개요
____[실습] 이메일 답장 에이전트
____마무리
7.3 메모리
____실습 개요
____[실습] 다세션 리서치 에이전트
____마무리
7.4 서브 에이전트
____실습 개요
____[실습] 다단계 역할 분담형 리서치 에이전트
____마무리

Chapter 08 스펙 주도 개발: 스펙 사이클 완주
8.1 스펙(명세)
____실습 개요
____[실습] 글쓰기 첨삭 에이전트
____마무리

| Part 04 | 하네스 엔지니어링 실전 프로젝트

Chapter 09 사내 문서 검색 에이전트
9.1 사내 문서 검색 에이전트 만들기
____실습 개요
____[실습] 사내 문서 검색 에이전트
____마무리

Chapter 10 주식 종목 추천 에이전트
10.1 주식 종목 추천 에이전트 만들기
____실습 개요
____[실습] 주식 종목 추천 에이전트
____마무리

Chapter 11 자산 진단 및 노후 계획 에이전트
11.1 자산 진단 및 노후 계획 에이전트 만들기
____실습 개요
____[실습] 자산 진단 및 노후 계획 에이전트
____마무리

Chapter 12 카드 사용 내역 분석 에이전트
12.1 카드 사용 내역 분석 에이전트 만들기
____실습 개요
____[실습] 카드 사용 내역 분석 에이전트
____마무리

Chapter 13 반복 보고서 자동화 에이전트
13.1 반복 보고서 자동화 에이전트 만들기
____실습 개요
____[실습] 반복 보고서 자동화 에이전트
____마무리

| Part 05 | 같은 스펙, 다른 하네스: 헤르메스 에이전트

Chapter 14 헤르메스의 이해
14.1 헤르메스 에이전트란 무엇인가
____하네스 엔지니어링과 헤르메스 에이전트의 관계
____헤르메스 에이전트의 개념과 특징
____헤르메스의 구조: 모델을 둘러싼 다섯 개의 층
____자기개선 루프: 제품이 된 메타 하네스
14.2 헤르메스 vs 클로드 코드
____두 도구 함께 쓰기

Chapter 15 헤르메스 실습
15.1 헤르메스 설치와 실습 환경 세팅
____헤르메스 설치하기
____외부 도구 설치하기
____헤르메스 기본 설정 및 실행하기
____YOLO 모드와 API 키 설정하기
15.2 폴더 자동 정리 비서 만들기
____실습 개요
____[실습] 폴더 자동 정리 비서
____마무리
15.3 작업에 따라 모델을 골라 쓰는 라우터 만들기
____실습 개요
____[실습] 작업에 따라 모델을 골라 쓰는 라우터
____마무리

| Part 06 | 에이전트의 안정적인 운영과 확장

Chapter 16 하네스 운영: 비용 점검·장애 대응·도구 선택
16.1 비용 점검
____비용을 점검하는 6가지 항목
16.2 트러블슈팅
____자주 발생하는 6가지 문제와 대응법
16.3 도구 선택
____에이전트 운영 도구 6가지 비교
16.4 프레임워크 도입
____프레임워크 도입을 검토해야 하는 5가지 신호

Chapter 17 하네스의 미래: 메타 하네스·NLAH·A2A
17.1 메타 하네스의 다음 단계
____메타 하네스의 세 가지 발전 방향
17.2 NLAH
17.3 A2A

서지영 마이크로소프트 Data & AI Specialist이자 20년 넘게 IT 시장의 변화를 함께한 엔지니어다. 고려대학교 대학원에서 빅데이터와 인공지능을 연구했고, 딥러닝 프레임워크부터 랭체인, RAG, MCP, 멀티 에이전트까지 빠르게 발전하는 AI 기술을 현장에서 익히고 이를 책으로 정리해왔다. 『딥러닝 파이토치 교과서』(길벗, 2022), 『랭체인으로 RAG 개발하기』(길벗, 2025), 『나만의 MCP 서버 만들기 with 커서 AI』(길벗, 2025), 『이것이 멀티 에이전트다』(한빛미디어, 2026) 등을 집필했으며, 기술을 누구나 쉽게 이해하고 활용할 수 있도록 지식을 나누는 데 힘쓰고 있다.