이 실습에서 만들 것
AI 에이전트 팀으로 책 한 권을 완성하는 하네스를 직접 구축합니다
이 페이지는 하네스 엔지니어링이란?과 Claude Code 101을 먼저 읽으면 더 잘 이해됩니다.
보통 출판사에는 편집장, 기획자, 리서처, 작가, 편집자, 디자이너가 있습니다. 이 실습에서는 그 출판사 조직 전체를 파일 8개로 만듭니다. 편집장이 CLAUDE.md이고, 기획서가 book-toc.md이고, 전문가 5명이 스킬 파일 5개입니다.
하네스 없이 AI로 책 쓰기
- 매번 처음부터 지시를 다시 내림
- 장마다 문체가 달라짐
- 사실 확인 없이 출판
하네스와 함께 AI로 책 쓰기
- 규칙이 파일에 저장되어 일관성 유지
- 10명의 리뷰어가 자동으로 품질 검증
- book-toc.md만 교체하면 다른 책도 제작 가능
- Claude Code가 설치되어 있어야 합니다 (Claude Code 101 참고)
- 터미널(맥) 또는 명령 프롬프트(윈도우)를 열 수 있어야 합니다
- 책의 주제를 미리 정해 두면 좋습니다 (예: "비개발자를 위한 AI 활용법")
실습 1단계. 에이전트 팀 구조를 설계한다
출판사에 어떤 팀원이 필요한지 먼저 정합니다
책을 만들려면 여러 역할이 필요합니다. 이 프로젝트에서는 AI 에이전트가 각각 하나의 역할을 담당합니다. 먼저 어떤 역할이 필요한지 정리하는 것이 첫 번째 단계입니다.
리서처
웹에서 자료를 수집하고, 출처와 함께 정리합니다
저자
수집한 자료를 바탕으로 목차를 설계하고 초안을 작성합니다
합평단 (총 10명)
아래 10명의 리뷰어가 모두 합평단에 소속되어 원고를 검토합니다
| 구분 | 리뷰어 | 역할 |
|---|---|---|
| 내부 리뷰 (초안 검토) |
🔴 비평가 | 논리적 비약, 근거 없는 주장, 규칙 위반을 검출합니다 |
| 🟠 예상 독자 | 기술 배경이 없는 독자 관점에서 이해도를 확인합니다 | |
| 5인 동시 평가 (품질 게이트) |
① 사실 검증관 | 정보의 정확성과 출처를 검증합니다 |
| ② 구조 분석가 | 전체 흐름과 장 간 연결이 자연스러운지 평가합니다 | |
| ③ 논리 평가자 | 주장과 근거의 논리적 연결을 점검합니다 | |
| ④ 독자 대변인 | 대상 독자가 실제로 이해할 수 있는지 판단합니다 | |
| ⑤ 서식 검수자 | 문체 규칙, 금지 표현, 부호 규칙 준수 여부를 확인합니다 | |
| 외부 리뷰 (전문가 점검) |
📖 편집자 | 20년차 출판 편집자 관점에서 구성력, 서사력, 경쟁력을 평가합니다 |
| 📣 마케터 | 타겟 명확성, 제목 임팩트, 시의성을 점검합니다 (참고만, 본문 미반영) | |
| 🔍 프루프리더 | 20년차 교정교열 전문가로서 맞춤법, 비문, 용어를 교정합니다 |
추가 역할
- 퍼블리셔: 최종 원고를 Word 문서로 변환하고, 메타데이터를 생성합니다 (/publish)
- 디자이너: 책 내용을 기반으로 표지 컨셉을 설계합니다 (/cover)
팀장 (사람 = 나)
- 어떤 주제의 책을 쓸지 기획서(book-toc.md)를 작성합니다
- 각 단계를 슬래시 커맨드로 실행합니다
- 최종 결과물을 직접 확인하고 판단합니다
내가 만들 책에는 어떤 역할이 필요할지 종이에 적어 보세요. 위 구성은 "책 쓰기"에 특화된 팀입니다. 다른 프로젝트(예: 블로그, 보고서)를 만든다면 역할 구성이 달라질 수 있습니다.
실습 2단계. 전체 워크플로우를 설계한다
팀원을 정했으면, 누가 언제 어떤 순서로 일할지 흐름을 짭니다
"리서치 먼저, 집필 다음, 리뷰는 그 다음"처럼 순서가 명확해야 AI가 혼란 없이 일할 수 있습니다.
3단계(리뷰)에서 "통과 못 하면 수정 후 재도전"하는 루프가 있습니다. 이 루프가 바로 하네스의 "가드레일"입니다. 기준 미달이면 최대 3라운드까지 자동으로 재도전합니다.
실습 3단계. 작업 계획서와 파일 구조를 만든다
1~2단계에서 정한 팀 구조와 워크플로우를 파일로 구체화합니다
"누가(역할)", "어떤 순서로(워크플로우)" 일할지 정했으니, 이제 이것을 실제 파일 구조로 변환합니다. 이 파일 구조 자체가 곧 하네스입니다.
| 파일 | 역할 | 수정 가능 여부 |
|---|---|---|
| CLAUDE.md | 범용 규칙 8가지, 품질 기준 7가지를 정의합니다 | 수정 불가 (고정) |
| skills/*.md | 각 에이전트의 업무 절차를 정의합니다 | 수정 불가 (고정) |
| book-toc.md | 책의 제목, 페르소나, 목차, 문체를 정의합니다 | 수정 가능 (교체) |
| draft/ | 리서치 노트, 초안, 리뷰 결과 등이 자동으로 저장됩니다 | 자동 생성 |
| output/ | 최종 Word 파일, 메타데이터, 표지 이미지가 저장됩니다 | 자동 생성 |
시험 규칙과 채점 기준은 고정이고, 답안지만 수정 가능한 것과 같습니다. 규칙까지 바꿀 수 있으면 시험의 의미가 없어집니다. CLAUDE.md와 스킬은 채점 기준이고, book-toc.md와 draft/는 답안지입니다.
실습 4단계. Claude Code에게 실행을 맡긴다
설계가 끝났으면, 이제 AI 에이전트 팀이 일하게 합니다
먼저 GitHub에서 프로젝트를 가져옵니다. 터미널에서 아래 명령어를 입력합니다.
Claude Code를 열고, 아래 프롬프트를 입력합니다. 이 파일 하나가 "이번에 쓸 책"을 결정합니다.
기획서가 완성되면, 아래 커맨드를 순서대로 하나씩 실행합니다.
| 순서 | 커맨드 | 하는 일 | 예상 소요 시간 |
|---|---|---|---|
| 1 | /research |
웹에서 자료를 수집하고 정리합니다 | 10~20분 |
| 2 | /write |
목차 설계 후 초안을 작성합니다 | 30~60분 |
| 3 | /review |
합평단 10명이 9단계 리뷰를 수행합니다 | 40~90분 |
| 4 | /publish |
Word 문서로 변환하고 메타데이터를 생성합니다 | 10~15분 |
| 5 | /cover |
표지 컨셉을 설계하고 이미지를 생성합니다 | 5~10분 |
각 스킬은 draft/ 폴더의 파일 존재 여부를 자동으로 감지합니다. /write 도중 중단해도, 다시 /write를 실행하면 마지막 산출물부터 이어서 작업합니다. 게임의 자동 저장과 같은 원리입니다.
실습 5단계. 결과물을 확인하고 검증한다
AI가 만든 결과물을 직접 열어보고, 품질 기준을 충족하는지 확인합니다
모든 커맨드 실행이 끝나면 output/ 폴더에 최종 결과물이 생성됩니다. 아래 체크리스트로 점검합니다.
목차 일치
book-toc.md의 목차와 실제 원고 구조가 일치하는가
분량 충족
목표 분량(12~15만자)을 달성했는가
페르소나 일관성
처음부터 끝까지 동일한 캐릭터와 말투를 유지하는가
내부 참조 정확성
"3장에서 다룬 내용" 같은 참조가 실제와 일치하는가
정보 일관성
동일 기능에 대한 설명이 장마다 모순되지 않는가
마크다운 기호 제거
최종 Word 문서에 #, *, ``` 같은 기호가 남아있지 않은가
결과물에 문제가 있을 때
CLAUDE.md와 5개 스킬은 그대로 유지하고, .claude/book-toc.md 한 파일만 새로운 주제의 기획서로 교체하면 동일한 품질의 다른 책을 만들 수 있습니다. 이것이 하네스의 본질입니다. "AI 모델을 바꾸는 것"이 아니라 "AI가 일하는 환경을 설계하는 것"입니다.
이제 직접 책을 써보세요
레포를 클론하고, book-toc.md를 작성하고, /research부터 시작하세요.
하네스가 나머지를 해줍니다.