문서자동화 사례 단일 원본 문서 자동화 (FaveCast)

한 줄 정의

FaveCast = 내용(원고)을 데이터 한 곳에 적어두면, 슬라이드·PDF·PPT·Word·Excel·웹문서를 자동으로 만들어내고, 사람이 보기 전에 기계가 먼저 검사해 주는 도구.

이 강의의 핵심 메시지("답변받기에서 끝내지 않고 입력 → 규칙 → 결과물 → 반복 실행 구조로")를 문서 제작에 그대로 적용한 실제 사례다. 매번 새로 PPT를 그리는 대신, 원본 1개에서 여러 형식을 찍어내는 구조를 만든다.

왜 이게 좋은 학습 사례인가

즉 "AI에게 예쁜 PPT를 한 번 받는 것"이 아니라, 한 번 만들어두면 계속 찍어내는 공장을 짓는 것이다.

핵심 발상: 내용·디자인·출력·검증을 분리한다

내용은   content.json 에 구조화한다   (사람이 쓰는 원고)
디자인은 템플릿/테마가 담당한다        (한 번 정해두면 재사용)
출력은   렌더러가 담당한다             (형식마다 변환기 1개)
검증은   Playwright가 담당한다         (전달 전 자동 점검)

이 분리가 핵심이다. 내용을 고쳐도 디자인은 그대로, 디자인을 바꿔도 내용은 그대로, 새 형식이 필요하면 변환기 1개만 추가하면 된다.

전체 구조

content.json  (단일 원본: 제목 + 슬라이드/섹션 배열)
   │
   ├─▶ HTML 슬라이드(deck) 또는 원페이지 문서(onepage)
   │        │
   │        ├─▶ PDF      (Playwright 인쇄)
   │        └─▶ PNG      (Playwright 캡처)
   │
   ├─▶ PPTX  (PNG을 슬라이드에 박은 버전 + 텍스트 편집 가능 버전)
   ├─▶ DOCX  (제목+본문+표 흐름의 Word 보고서)
   ├─▶ XLSX  (견적표·비교표를 시트로)
   │
   └─▶ 검증 리포트(JSON/Markdown)  ← 전달 전 자동 점검

구현 단계 (Claude Code에게 시키는 순서)

코드를 직접 짜는 게 아니라, 각 단계를 검증 가능한 업무 단위로 쪼개서 Claude Code에게 맡긴다. 아래가 그 순서다.

1) 프로젝트 뼈대 만들기

• 새 폴더에 독립 Node.js + TypeScript CLI 프로젝트를 만든다. (운영 사이트와 섞지 않는다)
• 폴더 역할 분리: content/(원본), templates/(디자인), src/(변환기·검증), outputs/(결과물).

2) 원본 데이터 형식 정하기 (content.json 스키마)

• "어떤 슬라이드 종류가 있는가"를 먼저 정한다: 표지, 한 줄 메시지, 카드 3개, 2단 비교, 타임라인, 로드맵, 비교표, 가격표, 마무리 등.
• zod로 스키마 검증을 건다 → 오타·빠진 항목을 사람이 보기 전에 잡는다.
• 가드레일도 스키마에 넣는다: 예) 이미지 경로에 file://(내 컴퓨터 경로)가 있으면 거부.

3) 디자인을 템플릿/테마로 분리하기

• 색·폰트·레이아웃을 테마로 정의한다(예: 제안서용, 내부 보고서용, 견적서용).
• 슬라이드 종류별 HTML 조각을 만든다. 슬라이드는 16:9 고정 크기(1600×900)로 그린다.

4) 형식별 변환기 만들기 (한 형식 = 변환기 1개)

• HTML: content.json → 슬라이드 HTML 문자열.
• PDF / PNG: Playwright(자동화된 크롬)로 그 HTML을 열어 인쇄(PDF)·화면 캡처(PNG).
• PPTX: pptxgenjs로 (a) 캡처 PNG을 슬라이드에 꽉 채운 버전, (b) 제목·표·카드를 진짜 텍스트 도형으로 만든 편집 가능 버전.
• DOCX: docx 라이브러리로 제목 → 본문 → 표/목록이 흐르는 Word 보고서.
• XLSX: exceljs로 가격표·비교표를 엑셀 시트로.

5) 검증기 만들기 (가장 중요)

생성보다 검증이 더 중요하다. Playwright로 결과물을 자동 점검하고 합격/불합격 리포트를 남긴다.

• 슬라이드 수가 원본과 같은가
• 각 슬라이드가 16:9 비율인가
• 글자가 칸 밖으로 넘치지(overflow) 않는가
• 브라우저 콘솔 에러가 없는가
• 이미지가 깨지지 않았는가
• file://(내 컴퓨터 절대경로)가 남아있지 않은가
• PDF 페이지 수 = 슬라이드 수인가
• PPTX/DOCX/XLSX 파일이 정상 구조(열리는 파일)인가

6) 명령 하나로 묶기

• render --target all 한 번으로 원하는 형식 전부 생성 + 검증까지.
• 다음 문서는 content.json만 바꿔 같은 명령을 다시 실행한다. → 반복 실행 구조 완성.

검증이 실제로 잡아준 버그 3가지 (왜 자동검증을 하나)

실제 고객 자료를 이 구조로 재현하다가, 사람 눈으로는 놓쳤을 문제를 검증기가 잡았다. 이게 "검토 가능한 결과물"의 힘이다.

1. 레이아웃이 깨지는 CSS 충돌 — 특정 슬라이드 종류에서 제목·내용이 가로로 흩어졌다. 내용이 짧을 땐 우연히 화면에 들어와 통과했지만, 글자 많은 실제 자료에서 드러났다. 검증기의 "넘침 검사"가 잡았다.
2. 폰트 로딩 타이밍 문제 — 폰트가 적용되기 직전에 캡처돼 높이가 흔들렸다. "16:9 비율 검사"가 잡아서, 폰트 로딩을 기다리도록 고쳤다.
3. 옵션 무시 버그 — "전체 생성" 명령이 켜고 끈 형식 설정을 무시하고 다 만들고 있었다. 새 형식(DOCX/Excel) 검증을 붙이자 드러났다.

교훈: 만드는 코드보다 검사하는 코드를 먼저 신뢰하라. 검증이 없으면 "되는 것처럼 보이는" 결과물이 고객에게 그대로 나간다.

보안·가드레일 (수업에서 반드시 강조)

• 비밀번호·DB 주소·토큰을 코드/문서/로그에 절대 쓰지 않는다. 필요하면 .env(공유 금지)에만.
• 고객정보·투자정보·회사자료는 입력 전에 익명화/샘플화한다.
• 결과물에 file:// 같은 내 컴퓨터 경로가 남지 않게 한다(검증이 자동으로 막는다).
• 외부 공유/게시(예: 고객용 자료실 등록)는 별도의 운영 단계로 분리한다 — 이 문서의 자동화 범위 밖이며, 자격증명이 필요한 작업은 사람이 직접 실행한다.

Claude Code에게 요청하는 흐름 (붙여넣기용 골격)

1. "새 폴더에 독립 CLI 프로젝트를 만들어줘. 운영 코드와 섞지 마.
    폴더는 content/ templates/ src/ outputs/ 로 나눠줘."
2. "content.json 스키마를 zod로 정의해줘. 슬라이드 종류는 표지/카드3/2단비교/
    타임라인/가격표/마무리. 이미지에 file:// 경로가 있으면 검증에서 막아줘."
3. "이 예시 원고를 content.json으로 만들어줘."   (← 내 원고 첨부)
4. "HTML 슬라이드 렌더러를 만들고, Playwright로 PDF와 PNG도 뽑아줘. 16:9 고정."
5. "PNG 기반 PPTX와 텍스트 편집 가능한 PPTX를 만들어줘."
6. "같은 원본으로 Word(docx)와 Excel(xlsx)도 만들어줘."
7. "Playwright로 검증해줘: 슬라이드 수, 16:9, 넘침, 콘솔에러, file:// 여부.
    합격/불합격 리포트를 파일로 남겨줘."
8. "render --target all 한 명령으로 전부 생성+검증되게 묶어줘."

핵심은 매 단계 성공 기준과 금지사항(가드레일)을 함께 주는 것. "예쁘게 만들어줘"가 아니라 "16:9여야 하고, 넘치면 안 되고, file:// 금지"라고 말한다.

수강생 적용

• 김성범 (보고서·발표자료 자동화): 자료 폴더 → content.json 구조화 → 보고서(DOCX)·발표자료(PPTX/PDF) 동시 생성 → 검토 체크리스트(검증 리포트). FaveCast 구조가 그대로 목표 산출물과 일치한다.
• 최지혜 (데이터 기반 브리핑): 고객 자산현황(CSV/Excel) → 요약 데이터(JSON) → 브리핑 문서(DOCX/PDF) + 견적/수치표(XLSX). 표 중심이라 XLSX·DOCX 출력이 특히 잘 맞는다.

핵심 교훈

1. 원본은 하나. 내용은 content.json 한 곳에만. 형식은 거기서 파생.
2. 내용·디자인·출력·검증을 분리하면 고치기 쉽고 재사용된다.
3. 검증을 자동화하면 사람이 놓치는 사고를 전달 전에 막는다.
4. PM처럼 지휘한다 — 목표·입력·성공기준·금지사항·검수방법을 Claude Code에게 준다.
5. 공유/게시는 별도 운영 단계 — 자동 생성과 분리하고, 비밀은 사람이 다룬다.