JavaScript 개발자를 위한 AICE 자격증 대비 Python e-book을 Claude Code의 멀티 에이전트 하네스로 제작한 전 과정 기록. 결과물: python4js e-book (라이브) · GitHub 저장소
프롬프트 6개로 다음이 만들어졌습니다.
- e-book 1권: 25챕터 + 부록 3편, 자기완결형 단일 HTML(287KB), GitHub Pages 배포
- 코드 품질: Python 코드 블록 306개 중 실행 가능한 221개 전부 실제 실행 검증 통과 (FAIL 0)
- 재사용 가능한 하네스: 전문 에이전트 5종 + 스킬 5종 — 저장소를 클론하면 같은 파이프라인으로 책을 재생성·수정할 수 있음
사람이 한 일은 방향 제시(프롬프트 6개)뿐이고, 목차 설계·집필·코드 검증·QA·조판·배포는 전부 에이전트 팀이 수행했습니다.
세션에서 실제로 입력한 프롬프트 전문입니다.
| # | 프롬프트 | 결과 |
|---|---|---|
| 1 | /harness:harness Javascript 는 잘 아는 개발자가 AICE 자격증을 위하여 Python 문법을 공부하고자 할 때 필요한 e-book 생성 |
하네스(에이전트 5 + 스킬 5) 구축 |
| 2 | AICE Professional 도 범위에 포함하고, e-book 만들어줘. | 24챕터 + 부록 3편 생성 |
| 3 | github 에 올리고, 배포해서 인터넷에서 조회할 수 있게 해줘. | GitHub 저장소 + Pages 배포 |
| 4 | matplotlib, tensorflow 설치하고 no-run 챕터도 재검증해줘 | 시각화·딥러닝 챕터 실행 검증 전환 (+21 PASS) |
| 5 | 재검증 끝나면 재빌드하고 배포까지 반영해줘 | 재빌드·라이브 갱신 |
| 6 | Chapter 00. 에 이 문서에 관한 개요, 학습 대상, 학습 방법 등 서술 | ch00 추가 (25챕터) 및 배포 |
핵심은 1번입니다. "e-book을 써줘"가 아니라 **"e-book을 만드는 시스템(하네스)을 만들어줘"**를 먼저 요청했습니다. 이 순서 덕분에 이후의 모든 요청(범위 확장, 재검증, 챕터 추가)이 일회성 작업이 아니라 파이프라인의 부분 재실행으로 처리됐습니다.
메타 스킬(harness)이 도메인을 분석해 파이프라인 + 생성-검증 복합 패턴의 에이전트 팀을 설계했습니다.
[curriculum-architect] 목차 설계
↓
[chapter-writer] 집필 ⇄ [code-verifier] 실행 검증 ⇄ [qa-reviewer] 정합성 QA
↓
[ebook-builder] 단일 HTML 조판
에이전트마다 역할·작업 원칙·통신 프로토콜을 정의한 파일(.claude/agents/)과, "어떻게 하는가"를 담은 스킬(.claude/skills/)을 분리했습니다. 스킬에는 결정적 작업용 스크립트 2개를 번들했습니다.
verify_code_blocks.py— 마크다운에서 ```python 블록을 추출해 같은 네임스페이스에서 순차 실행하고,# 출력:주석과 실제 stdout을 대조build_ebook.py— 챕터들을 목차·사이드바·라이트/다크 테마를 갖춘 단일 HTML로 조립
구축 단계에서 스크립트를 스모크 테스트했는데, 이때 이미 버그 2건(빌드 제목을 덮어쓰는 변수 섀도잉, 미사용 인자)이 잡혔습니다. 하네스도 코드다 — 만들었으면 실행해서 검증한다는 원칙이 초반부터 효과를 냈습니다.
- 목차 설계: AICE 시험 범위 × "JS→Python 개념 매핑"의 2축으로 24챕터를 설계. Part 1(문법 12) / Part 2(Associate 실전 6) / Part 3(Professional 심화 6)
- 병렬 집필: 집필자 4명이 Part별로 동시에 집필. 각자 챕터 하나를 끝낼 때마다 검증 스크립트를 직접 실행해 실패를 즉시 수정(점진 검증 — 같은 결함이 전 챕터에 복제되는 것을 방지)
- 독립 검증: 별도의 검증 에이전트가 집필자들의 자가 검증을 신뢰하지 않고 전수 재검증. 304블록 중 200 PASS / 0 FAIL, no-run(실행 제외) 처리된 104블록도 전수 분류해 남용 0건 확인
- 정합성 QA: 목차↔본문 커버리지 교차 비교, JS 코드(실행 검증이 없는 쪽) 정확성, 용어·콜아웃 일관성 검수. CRITICAL/HIGH 0건, MEDIUM 4건 → 담당 집필자들에게 병렬 배정해 전부 수정
- 조판: 앵커 전수 검사·외부 리소스 0(오프라인 동작) 확인 후 단일 HTML 산출
흥미로웠던 지점: 4명이 나눠 쓴 흔적(챕터 참조 표기가 ch04 vs 4장으로 갈림)을 QA가 잡아냈습니다. 병렬 생산의 이음새 문제는 사람 팀과 똑같이 발생하고, 똑같이 검수로 잡습니다.
gh CLI로 공개 저장소 생성 → GitHub Pages(main:/docs) 활성화 → 라이브 URL 응답을 실제로 fetch해 콘텐츠 서빙 확인. 배포 절차는 스킬에 기록해 이후 재빌드 시 "docs/ 갱신 누락" 실수를 구조적으로 방지했습니다.
matplotlib·seaborn·tensorflow 설치 후, no-run이던 시각화·딥러닝 챕터 5개를 실행 가능 코드로 전환했습니다(+21 PASS, 총 221 PASS / FAIL 0).
이 과정에서 두 집필자가 독립적으로 같은 문제를 재현했습니다: macOS에서 matplotlib/sklearn을 실행한 프로세스에서 이어서 TensorFlow fit()을 호출하면 OpenMP 런타임 충돌로 교착. 검증 스크립트를 파일별 격리 프로세스 방식으로 패치해 해결했습니다. no-run 시절에는 드러나지 않던 문제로, "실행 검증 범위를 넓히면 파이프라인 자체의 결함도 드러난다"는 사례였습니다.
목차 갱신 → 집필 → QA → 재빌드 → 배포의 부분 재실행. 이때 집필자가 "함정 콜아웃 라벨은 1종"이라고 서술했는데, 리더가 전 챕터를 실측 스캔해 2종(JS 함정 39 / 함정 26)임을 확인하고 정정 지시했습니다. 프런트매터처럼 "책 전체를 서술하는 문서"는 개별 집필자의 시야(자기 담당 챕터)보다 넓어서, 전체를 보는 역할의 팩트체크가 필수였습니다.
| 항목 | 수치 |
|---|---|
| 최종 산출물 | 단일 HTML 287KB (외부 리소스 0, 오프라인 동작, 라이트/다크 테마) |
| 분량 | 25챕터 + 부록 3편 (치트시트 / 트랙별 시험 팁 / 학습 로드맵) |
| 코드 검증 | 306블록 중 실행 대상 221개 전부 PASS, FAIL 0 |
| 실행 제외(no-run) | 85블록 — 연습문제 빈칸·정답, XGBoost/LightGBM(미설치) 뿐 |
| QA | CRITICAL/HIGH 0, MEDIUM 5건 발견 → 전부 수정 반영 |
| 콜아웃 | |
| 연습문제 | 빈칸 채우기형(AICE 실기 형식) + 접기 정답 61개 |
| 배포 | https://newids.github.io/python4js/ (GitHub Pages) |
부산물로 재사용 가능한 자산이 남았습니다.
- 하네스 전체가 저장소에 포함 — 클론 후 "ch05만 다시 써줘" 같은 요청으로 부분 재실행 가능
- 중간 산출물(목차·검증 보고서·QA 보고서)이
_workspace/에 보존 — 감사 추적 가능 - 세션 중 발견된 하네스 개선 4건이 변경 이력으로 기록 (빌드 버그 2, 부록 glob 패치, OpenMP 격리 패치)
| 구분 | 내용 |
|---|---|
| 도구 | Claude Code (모델: Claude Fable 5) |
| 실행 구조 | 리더 1 + 서브 에이전트(집필 4·검증 1·QA 1·설계 1·조판 1), 백그라운드 병렬 실행 + 메시지 기반 재호출 |
| OS | macOS (Apple Silicon) |
| Python | 3.13.5 |
| 검증 환경 | numpy 2.5.0 · pandas 3.0.3 · scikit-learn 1.9.0 · matplotlib 3.11.1 · seaborn 0.13.2 · tensorflow 2.21.0 (keras 3.15) |
| 배포 | GitHub Pages (main 브랜치 /docs, gh CLI로 무중단 설정) |
환경이 최신 버전(pandas 3.x, keras 3.x)이었던 것이 오히려 이득이었습니다. 집필 중 검증 스크립트가 구식 API(mean_squared_error(squared=False) 등)를 즉시 실패시켜, 책이 현행 API 기준으로 강제되었습니다.
- "콘텐츠를 만들어줘"보다 "만드는 시스템을 만들어줘"가 낫다. 수정·확장 요청이 전부 파이프라인 재실행으로 흡수된다.
- LLM이 쓴 코드는 LLM이 "맞아 보인다"고 판단하게 두지 말고 실행시켜라. 이 책의 신뢰도는 전적으로 "예제 221개가 실제로 돌았다"는 사실에서 온다.
- 생성자와 검증자를 분리하고, 검증자에게 생성자를 의심하라고 명시하라. 자가 검증 + 독립 재검증의 이중화가 여러 결함을 걸렀다.
- 점진 검증이 일괄 검증보다 싸다. 챕터 1개 완성 직후 검증하면 결함 패턴이 복제되기 전에 잡힌다.
- 전체를 보는 역할(리더·QA)의 실측 팩트체크는 생략할 수 없다. 개별 에이전트는 자기 시야 안에서만 정확하다.