주제, 주요 내용, 대상 독자만 주면 리서치부터 EPUB 빌드까지 한 번에 수행하는 에이전트 하네스다. 모든 챕터는 toby-book-writing-style.md에 정의된 Toby 문체로 저술되며, 저자명은 기본값 Toby-AI에서 원하는 값으로 바꿀 수 있다 (아래 저자명 변경 참고).

• Repo: https://github.com/tobyilee/book-writer
• 실행 환경: Claude Code + Claude Agent SDK
• 저자 모델: Claude Opus (하네스 내 모든 에이전트가 model: opus 사용)

주제를 던지면 다음을 자동으로 수행한다.

1. 리서치 — 웹·논문·커뮤니티를 병렬로 뒤져 레퍼런스 문서 작성
2. 저술 계획 — 제목 후보, 책 특성, 챕터 목록과 내러티브 아크 설계
3. 계획 리뷰 — 저자와 리뷰어 에이전트가 2회 왕복 토론 후 계획 확정
4. 챕터 저술 — 에이전트 팀이 Toby 문체로 초안 작성, 스타일 가디언이 실시간 감수
5. 편집 — 챕터 통합, 전환부 다듬기, 서문·에필로그·참고문헌 작성
6. 표지 + EPUB 빌드 + 책 소개 — 표지 이미지 생성, pandoc으로 EPUB 3 조립, 짝을 이루는 책 소개 markdown 작성

산출물은 프로젝트 루트에 두 파일이 짝으로 저장된다.

• {책-제목}-v{version}.epub — 본문 EPUB
• {책-제목}-v{version}.md — 외부 독자용 책 소개 (logline, 대상 독자, 핵심 약속, 차례, 저자 소개, 책 정보). 블로그·스토어·SNS에 바로 붙여 쓸 수 있도록 작성된다.

git clone https://github.com/tobyilee/book-writer.git
cd book-writer
# 의존 도구가 없다면 위 '사전 준비' 설치

Claude Code를 이 디렉토리에서 실행하면 .claude/agents/, .claude/skills/, CLAUDE.md를 자동 인식한다.

Claude Code 프롬프트에 주제·내용·대상 독자를 자연어로 입력하면 자동으로 book-writing-orchestrator 스킬이 발동한다.

주제: 효과적인 SQL 쿼리 튜닝
주요 내용: 실행 계획 읽기, 인덱스 설계, N+1 회피, 실전 사례
대상 독자: 백엔드 주니어 개발자 (SQL 기본은 아는 수준)
분량: 150페이지 정도
이 주제로 책 써줘.

오케스트레이터가 Phase 0부터 Phase 5까지 순차적으로 진행하며, 각 Phase에서 필요한 에이전트를 자동으로 호출한다. 중간에 계획 리뷰가 끝나면 사용자 승인을 요청하는 지점이 있다.

{slug}/
├── research/
│   ├── web.md
│   ├── papers.md
│   └── community.md
├── 01_reference.md          # 리서치 종합
├── 02_plan.md               # 저술 계획 (리뷰 반영된 최종본)
├── 03_review_log.md         # 리뷰 기록
├── chapters/
│   ├── 01_draft.md / 01_final.md
│   ├── 02_draft.md / 02_final.md
│   └── ...
├── 04_manuscript.md         # 통합 원고
├── style_log.md             # 스타일 검수 로그
├── book_manifest.json       # EPUB 메타데이터
├── cover.png                # 표지 이미지
├── cover_prompt.md          # 표지 프롬프트 기록
└── build_log.md             # 빌드 로그

{책-제목}-v1.0.0.epub        # 최종 산출물 (프로젝트 루트)
{책-제목}-v1.0.0.md          # 책 소개 markdown (EPUB과 같은 폴더, 같은 stem)

• research-lead가 web-researcher, paper-researcher, community-researcher를 병렬로 스폰
• 각 리서처는 독립 소스에서 자료 수집 → research/*.md에 저장
• research-lead가 결과를 종합해 01_reference.md 작성

• book-planner가 레퍼런스를 읽고 02_plan.md 작성
• 독자 여정(진입 상태 → 출구 상태)부터 역산해 챕터 배치

• book-planner와 plan-reviewer가 팀으로 구성됨
• 리뷰어가 5축(커버리지, 흐름, 독자 적합도, 균형, 중복)으로 비판
• 최대 2회 왕복 후 합의된 02_plan.md 확정
• 사용자 승인 요청

• chapter-writer × N + style-guardian + editor가 팀으로 구성
• 각 chapter-writer는 {NN}_draft.md 작성 → style-guardian에 리뷰 요청
• style-guardian은 Toby 문체 체크리스트 10개 항목으로 검수
• 합의 시 {NN}_final.md로 저장
• editor가 완료된 챕터들을 04_manuscript.md로 통합 + book_manifest.json 생성

왜 팀 모드인가? 여러 챕터를 병렬로 쓸 때 문체가 갈라지는 게 가장 흔한 실패 지점이다. 팀 내 SendMessage로 실시간 조율하고, 전담 스타일 가디언이 일관성을 잡는다.

• cover-designer가 이미지 생성 (MCP > API > ImageMagick 폴백 순)
• epub-builder가 scripts/build_epub.sh를 호출해 결정적 빌드
• pandoc으로 04_manuscript.md + cover.png + book_manifest.json을 EPUB 3로 변환
• epubcheck 설치 시 자동 검증
• EPUB 빌드 직후 epub-builder가 02_plan.md·04_manuscript.md·매니페스트를 읽어 책 소개 markdown({책-제목}-v{version}.md)을 EPUB 옆에 작성

완성된 책에 수정 요청이 생기면 같은 오케스트레이터가 처리한다.

챕터 3 처음 부분이 너무 딱딱해. 다시 써줘.

→ 해당 챕터만 재저술, 나머지 유지. chapter_3_draft_v1.md로 백업 후 신규 초안.

표지를 좀 더 따뜻한 느낌으로 바꿔줘.

→ cover-designer만 재호출, cover_v1.png로 백업.

계획을 좀 더 입문자 친화적으로 다시 세워줘.

→ Phase 3부터 재실행. 기존 02_plan.md는 02_plan_v1.md로 백업.

재실행 시 버전은 minor 증가 (v1.0.0 → v1.1.0) 또는 사용자가 명시적으로 지정.

프로젝트 루트의 toby-book-writing-style.md가 모든 챕터 저술의 제약 조건이다. 여기를 수정하면 저술 톤이 바뀐다. 확장 가이드는 .claude/skills/chapter-writing/references/toby-style-guide.md에 있다.

저자 기본값은 Toby-AI다. 다른 저자로 쓰고 싶다면 두 방법 중 하나를 고른다.

방법 1. 프롬프트에서 지정 (일회성, 권장)

책 쓰기 요청에 저자: {이름} 한 줄을 추가한다. 오케스트레이터가 Phase 0에서 이 값을 캡처해 book_manifest.json과 표지 메타에 그대로 반영한다.

주제: 효과적인 SQL 쿼리 튜닝
저자: Jane Doe
대상 독자: 백엔드 주니어 개발자
이 주제로 책 써줘.

방법 2. 기본값 자체를 교체 (반복 사용)

모든 책에 새 기본 저자를 쓰려면 하네스 파일에 있는 Toby-AI를 일관되게 교체한다:

• .claude/skills/book-writing-orchestrator/SKILL.md — description과 Phase 0·Phase 5 메타데이터
• .claude/agents/editor.md, .claude/skills/book-editing/SKILL.md — book_manifest.json 템플릿의 "author" 기본값
• .claude/agents/cover-designer.md, .claude/skills/cover-design/SKILL.md — 표지 저자 표기 기본값
• .claude/skills/epub-build/scripts/build_epub.sh — 빈 매니페스트일 때의 fallback

epub-builder와 build_epub.sh는 매니페스트 값을 그대로 사용하므로, 매니페스트에 사용자 지정 저자가 들어 있으면 이 fallback은 발동하지 않는다.

새로운 역할(예: fact-checker)을 추가하려면:

1. .claude/agents/fact-checker.md 생성 (핵심 역할, 작업 원칙, 프로토콜)
2. .claude/skills/fact-check/SKILL.md 생성 (description은 pushy하게)
3. 오케스트레이터(book-writing-orchestrator/SKILL.md)의 Phase 구성에 통합
4. CLAUDE.md의 변경 이력 테이블에 기록

book-writer/
├── CLAUDE.md                        # 하네스 포인터 + 변경 이력 (새 세션 자동 로드)
├── README.md                        # 이 파일
├── toby-book-writing-style.md       # Toby 문체 기본 가이드
├── .gitignore                       # .omc 등 툴 로컬 파일 제외 (책 산출물은 버전 관리 대상)
└── .claude/
    ├── agents/                      # 11개 에이전트 정의
    │   ├── research-lead.md
    │   ├── web-researcher.md
    │   ├── paper-researcher.md
    │   ├── community-researcher.md
    │   ├── book-planner.md
    │   ├── plan-reviewer.md
    │   ├── chapter-writer.md
    │   ├── style-guardian.md
    │   ├── editor.md
    │   ├── cover-designer.md
    │   └── epub-builder.md
    └── skills/                      # 오케스트레이터 + 11개 전문 스킬
        ├── book-writing-orchestrator/   # 최상위 워크플로우
        ├── research-coordination/
        ├── web-research/
        ├── paper-research/
        ├── community-research/
        ├── book-planning/
        ├── plan-review/
        ├── chapter-writing/
        │   └── references/
        │       ├── toby-style-guide.md
        │       └── chapter-scaffolds.md
        ├── style-review/
        ├── book-editing/
        ├── cover-design/
        └── epub-build/
            └── scripts/
                └── build_epub.sh

파일명 컨벤션: {NN}_{artifact}.md (NN = Phase 번호 2자리)

brew install pandoc

원고가 너무 짧거나 챕터 변환 실패 가능성. {slug}/build_log.md와 .pandoc_err를 확인한다. 원고가 진짜 짧다면(샘플·테스트) 무시해도 된다.

EPUB은 생성되지만 표준 위반 사항이 있다. {slug}/.epubcheck.log를 읽고 문제 구절을 수정한다. 대부분 <script> 태그나 금지된 네임스페이스 같은 마크다운 소스 문제다.

style-guardian이 몇 번 왕복했는지 {slug}/style_log.md에서 확인. 3회 왕복에도 합의가 안 되면 저술가 결정이 채택된다. 이 경우 toby-book-writing-style.md나 references/toby-style-guide.md의 규칙이 너무 모호할 수 있으니 구체적 예시를 보강하자.

1. 이미지 생성 MCP/API가 연결되어 있지 않으면 ImageMagick 폴백 사용 → 단순 타이포그래피 표지가 생성됨
2. ImageMagick도 없으면 brew install imagemagick 후 재실행
3. 품질이 부족하면 cover-designer를 수동으로 재호출 요청

프롬프트에 "책 써줘", "저술", "EPUB" 같은 키워드가 있는지 확인한다. 단순 질문(예: "이 하네스가 뭐야?")에는 트리거되지 않는 게 정상이다. 억지로 발동시키려면 /book-writing-orchestrator를 직접 호출.

하네스는 정적 산출물이 아니라 진화하는 시스템이다.

• 실행 완료 후 사용자 피드백이 있으면 해당 에이전트·스킬을 수정
• 변경은 CLAUDE.md의 변경 이력 테이블에 기록
• 같은 유형 피드백이 2회 이상 반복되면 구조적 수정 검토
• 브랜치 전략 권장: 실험은 harness 브랜치, 안정화되면 main으로 머지

MIT License. 전문은 LICENSE 참조.

• 저자: Toby-AI (AI 저자 페르소나)
• 하네스 설계: Toby Lee + Claude Opus 4.7