| name | book-editing |
| description | Integrate all finished chapters into a single book-ready manuscript — polish chapter transitions, unify terminology, insert cross-chapter callbacks, and write front/back matter (preface, epilogue, references). Produce a manuscript + book_manifest.json for EPUB build. Use when chapters are individually complete and need to become a coherent book. |
Book Editing
완성된 챕터들을 한 권의 책으로 직조한다. 내용을 새로 쓰지 않고, 흐름과 일관성만 다듬는다.
절차
- 확인 — 모든
{NN}_final.md 존재 여부
- 순회 읽기 — 1장부터 마지막까지 순서대로
- 전환부 점검 — 각 챕터 끝 단락과 다음 챕터 시작 단락의 연결 품질
- 용어 통일 — 불일치 발견 시 한쪽으로 정렬 (기준은
02_plan.md의 용어 표기를 따름)
- 콜백 삽입 — 뒤 챕터가 앞 개념을 언급할 때 자연스러운 참조 추가
- 부속 자료 작성 — 서문, 에필로그, 참고문헌, (선택) 용어집. 장르에 맞춘다: narrative=작가의 말/헌사(참고문헌 보통 생략), practical="이 책 활용법"+준비물 총정리, essay=짧은 머리말, tech-book=현행 그대로
- 통합 —
04_manuscript.md로 합본 저장
- 분량 균형 점검 — 챕터별 분량 편차 확인 (아래 "분량 균형 점검" 절차)
- 매니페스트 생성 —
book_manifest.json 작성
- 스타일 점검 요청 —
style-guardian에게 통합 원고 전체 변주 점검(책 단위 whole-book 점검)을 반드시 요청한다. 이 단계는 생략하지 않는다 — 최종 확정 전 책 전체의 문장·오프닝 변주가 한 번 더 검수되어야 한다
전환부 체크
- 끝-시작 연결이 갑작스럽지 않은가?
- 다음 장 예고가 너무 길거나 짧지 않은가?
- 같은 표현("다음 장에서는 ~를 살펴보자")이 모든 챕터 말미에 반복되는가?
용어 통일 원칙
- 한 용어의 여러 표기(영문/한글, 축약/풀)가 있으면 가장 많이 쓰인 표기 기준
- 예외: 장르가 기술서면 "사용자"보다 "유저"가 자연스러울 때도 있음 — 문맥 우선
- 결정 불가능 → 서문에 "이 책에서는 {A}를 {B}로 표기한다" 정의
서문 작성 지침
- 왜 이 책을 썼는가 (문제의식)
- 이 책을 누가 읽으면 좋은가 (대상 독자)
- 어떻게 읽으면 좋은가 (순서·선택 독서 가이드)
- 감사의 말 (선택)
- 길이: 2~4페이지 분량
에필로그 작성 지침
- 여정을 짧게 돌아봄
- 책이 답하지 못한 질문들
- 다음 걸음에 대한 제안 (추천 도서·실천 과제)
- 길이: 1~2페이지
참고문헌
- 챕터 각주를 모아 단일 목록으로 재정렬
- 중복 제거
- 정렬: 인용 순서 or 저자 가나다순 (한 방식 고수)
- 형식 통일:
저자. 제목. 발행처/URL, 날짜.
분량 균형 점검
챕터 간 분량 편차가 크면 독서 리듬이 무너진다. 통합 후 다음을 점검한다.
- 코드 제거 후 글자 수 계산 — 챕터별로 코드 블록(
```로 둘러싸인 영역)을 제외한 본문 글자 수를 센다
- 편차 플래그 — 중앙값(median) 대비 70% 미만이거나 150% 초과인 챕터를 표시한다. (
02_plan.md에 챕터별 "예상 분량"이 있으면 그 값 대비 ±20%를 함께 기준으로 쓴다)
- 오프닝 챕터 가드 — 1장(훅 챕터)이 중앙값 아래로 떨어지지 않게 특별히 살핀다. 첫 장이 빈약하면 책의 첫인상이 죽는다
- 리포트 작성 —
{slug}/length_report.md에 챕터별 글자 수·중앙값·플래그를 기록한다
- 조치 요청 — 플래그된 챕터는 해당
chapter-writer에게 표적 확장/축약을 요청하거나, 정당한 사유(예: 의도적으로 짧은 막간 장)가 있으면 length_report.md에 예외로 명시한다
length_report.md 예시:
# 분량 균형 리포트
| 장 | 코드 제외 글자 수 | 중앙값 대비 | 예상 분량 대비 | 판정 |
|----|------------------|------------|---------------|------|
| 1장 | 8,200 | 96% | -4% | OK (훅 챕터, 중앙값 이상 확인) |
| 2장 | 5,100 | 60% | -35% | ⚠️ 축소됨 — 확장 요청 |
| 3장 | 13,400 | 158% | +30% | ⚠️ 비대 — 축약 또는 분할 검토 |
중앙값: 8,500자
조치: 2장 확장 요청, 3장 축약 요청.
출력 형식
04_manuscript.md:
# {책 제목}
## 저자
{author}
**판본:** v{version} · {pub_date}
---
## 판권
**{책 제목}**
**판본:** v{version}
**발행일:** {pub_date}
**저자:** {author}
**식별자:** {identifier}
### 라이선스
이 책은 **CC BY-NC-SA 4.0** 라이선스로 배포된다 — [Creative Commons 저작자표시-비영리-동일조건변경허락 4.0 국제](https://creativecommons.org/licenses/by-nc-sa/4.0/).
- **저작자 표시(BY):** 출처를 밝혀야 한다.
- **비상업적 이용(NC):** 상업적 목적으로 이용할 수 없다.
- **동일조건 변경허락(SA):** 변경·재배포 시 동일한 라이선스를 적용해야 한다.
매니페스트에 `license` 필드가 다른 값으로 명시되어 있으면 그 값으로 위 문장과 링크를 갈음한다. 어느 경우든 매니페스트의 `license` **정식 코드 문자열이 지면에 그대로 등장해야 한다** — `epub-build`의 필수 확인 항목이 콜로폰과 매니페스트의 `license` 문자열 일치를 대조한다.
### 출처
이 책은 [book-writer](https://github.com/tobyilee/book-writer) 하네스 v{harness_version}로 자동 생성되었다.
---
## 서문
...
## 목차
- 1장. ...
- 2장. ...
---
# 1장. {제목}
(전환부 다듬어진 본문)
# 2장. ...
...
## 에필로그
...
## 참고문헌
...
book_manifest.json:
{
"title": "...",
"subtitle": "...",
"author": "Toby-AI",
"language": "ko",
"pub_date": "YYYY-MM-DD",
"identifier": "urn:uuid:...",
"description": "한 문단 소개",
"cover_image": "cover.png",
"cover_alt": "{title} 표지",
"version": "1.0.0",
"license": "CC BY-NC-SA 4.0",
"genre": "tech-book",
"harness_version": "1.8.0",
"rights": "© {year} {author} — Licensed under {license}"
}
license, harness_version, rights는 옵션 필드. 비우면 빌드 스크립트가 하네스 기본값(CC BY-NC-SA 4.0 + 루트 VERSION + 자동 생성 rights)으로 채운다. genre는 오케스트레이터가 확정한 장르(tech-book/narrative/practical/essay)를 기록한다 — 재실행 시 활성 프로필을 결정적으로 재사용하는 출처다. 누락 시 tech-book.
cover_alt는 표지 이미지의 대체 텍스트로, 빌드 스크립트의 alt-text 주입이 이 값을 출처로 쓴다. 비우면 기본 패턴 "{title} 표지"를 적용한다.
식별자(identifier) 발급 규칙: identifier는 신규 책일 때 한 번만 생성한다 — python3 -c "import uuid;print('urn:uuid:'+str(uuid.uuid4()))". 플레이스홀더 "urn:uuid:..."를 그대로 복사하지 않는다. 같은 책 재빌드 시 기존 book_manifest.json의 identifier를 그대로 보존하고 version만 올린다 (식별자는 책의 영구 ID — 재빌드마다 바뀌면 안 된다).
재편집 시
- 일부 챕터만 갱신 → 해당 섹션만 교체 후 전체 재저장
- 서문·에필로그 개선 요청 → 해당 섹션만 다시 작성, 버전 증가
- 내용 변경 제안은 반드시
editor_notes.md에 기록 (직접 수정 금지)
