L35 — 고객 산출물을 만드는 두 스킬: client-usage-guide vs manual (수정중)

우리 스킬 카탈로그(L11)에는 "고객에게 기능 사용법을 전달하는" 산출물을 만드는 스킬이 둘 있다 — client-usage-guide 와 manual. 둘 다 비개발자 고객을 향하고, 둘 다 스크린샷을 쓴다. 그래서 헷갈리기 쉬운데, 만들어 내는 산출물의 형태가 다르다. 하나는 읽는 문서(md, 고객엔 Word 로), 하나는 넘겨 보는 슬라이드/PDF 덱이다. 오늘은 각각이 뭘 하는지 실제 파일로 뜯어보고, 마지막에 "언제 어느 걸 쓰나" 를 정리한다.

1. client-usage-guide — 사용법을 담은 md 가이드 + Word 배포본을 만든다

무엇을 만드나. 비개발자 고객이 "이 기능을 실제로 어떻게 쓰는지" 이해할 수 있는 가이드다. 산출물은 두 벌이다 — 작업·검수용 마크다운(docs/guides/{그룹}_usage_guide.md, 그룹이 여러 개면 목차 usage_guide_index.md·요약 usage_guide_overview.md 도 함께)과, 고객에게 건넬 Word 배포본(docs/guides/{그룹}_usage_guide.docx, 스크린샷 임베드). md 가 SoT 고 docx 는 그 위의 배포 포맷이다. 스킬 정의는 .claude/skills/client-usage-guide/SKILL.md 에 있다.

핵심 아이디어 — "사용자 기능 그룹" 단위. docs/features/ 의 기능 문서는 흔히 구현 단위로 잘게 쪼개져 있다(한 사용자 기능이 여러 sub-feature 문서로 나뉨). 고객은 그런 내부 구분을 모른다. 그래서 이 스킬은 feature 문서 1:1 로 가이드를 뽑지 않고, 고객이 하나의 기능으로 인식하는 단위(그룹) 로 묶어 만든다. 이 그룹핑은 어딘가에 저장해 두지 않고 매 실행 시 docs/features/ 를 스캔해 동적으로 도출한다(기존 가이드 파일명을 앵커로 삼아 실행 간 경계가 흔들리지 않게).

어떻게 굴러가나. 대략 이 순서다:

1. 선행 — feature 문서 현행화. 가이드는 feature 문서에서 파생되므로, 먼저 대상 feature 문서가 최신 코드와 맞는지 확인·갱신한다(문서와 코드의 마지막 커밋 시각 비교). 이 0단계를 건너뛰지 않는 게 규칙이다.
2. 그룹핑 → 그룹별 가이드 생성. 그룹마다 "이 기능으로 뭘 하나 / 접속 방법 / 사용 방법(단계) / 화면 구성 / FAQ / 제한사항" 구조로 md 를 쓴다.
3. 스크린샷 채우기(기본). 본문의 [스크린샷: 설명] 자리를 실제 앱 화면을 찍어 채운다 — 이건 이제 기본 동작이다. "스크린샷 없이 / 텍스트만" 이라고 명시하면 플레이스홀더로 남긴다(opt-out). 캡처는 ui-tester(Playwright) 서브에이전트에 맡기고, 부작용 0 — 기존 레코드 화면만 찍고 새 워크플로우(LLM 호출·외부 쓰기·결제)를 트리거하지 않는다. 저장 위치는 static/images/guides/{그룹}/.
4. Word(.docx) 배포본 생성(기본). md 를 확정한 뒤, 같은 내용을 Word 로도 함께 낸다 — 고객 배포본은 md 가 아니라 Word 인 경우가 많기 때문이다. 이때 docx 생성 로직을 새로 짜지 않고 형제 스킬 create-docx 를 재사용한다(중복 구현 금지). 스크린샷은 create-docx 의 image 로 임베드된다. "md 만 / docx 없이" 를 명시하면 생략(opt-out).

호출 방식. all(전체 그룹) / {group}(특정 그룹) / {feature ...}(그 문서가 속한 그룹) / 인자 없이(그룹 목록 보여주고 고르기).

톤은 "테스트/합격 체크리스트" 가 아니라 "사용법 안내" 다. 검증·합격 여부를 다루는 건 형제 스킬 client-test-guide 몫이다(L28 에서 이 둘의 경계를 다뤘다).

2. manual — 화면 캡처를 박은 슬라이드/PDF 매뉴얼을 만든다

무엇을 만드나. 앱 화면 스크린샷이 들어간 슬라이드형 매뉴얼(HTML + PDF)이다. 좌측에 화면 설명(개요·사용방법), 우측에 스크린샷을 놓고, 클릭할 위치를 주황 박스로 강조한 16:9 슬라이드 덱이다. 산출물은 src/manual/ 아래 HTML·PDF, 스크린샷은 src/manual/screenshots/. 스킬 정의는 .claude/skills/manual/SKILL.md.

핵심 아이디어 — 뼈대는 공통, 콘텐츠는 프로젝트가 채운다. 이 스킬은 두 파이썬 파일로 구성된다:

• capture_screenshots.py — dev 앱에서 화면을 캡처하고 클릭 대상을 주황으로 강조한다. 프로젝트는 여기 CAPTURERS 에 "어느 화면을, 어디를 강조해, 어떤 파일명으로" 를 자기 기능에 맞게 정의한다.
• build_manual.py — 섹션별 슬라이드 스펙(SECTIONS)을 standarda_core.presentation 렌더 엔진으로 HTML/PDF 로 만든다. (이 엔진은 원래 한 프로젝트에 하드코딩 경로로 박혀 있던 걸 standarda-core 로 승격한 것 — core 승격 라이프사이클은 L14 와 같은 결이다.)

즉 워크플로우·엔진은 standarda-template 이 주고, SECTIONS·CAPTURERS(어떤 화면·어떤 슬라이드)는 각 프로젝트가 자기 기능에 맞게 작성한다. standarda-template 에는 동작하는 예시 섹션 1개만 들어 있다.

어떻게 굴러가나.

1. 사전 준비(한 번). standarda-core >= v0.20.0(presentation 포함) + playwright, 그리고 python -m playwright install chromium. PDF 한글이 깨끗하려면 로컬 한글 폰트(Noto Sans CJK KR 등)가 필요하다(원격 웹폰트를 쓰면 Chromium PDF 가 글자를 삐뚤게 임베드한다).
2. dev 서버 기동 → 캡처. capture_screenshots.py <섹션> 으로 화면을 찍는다. 실제 고객 데이터를 찍지 않는다 — 필요하면 임시/가짜 데이터를 시드하고 끝나면 정리한다. 찍은 png 는 눈으로 확인(강조 위치·여백).
3. 렌더 → 검수. build_manual.py <섹션> 으로 슬라이드를 만들고, 생성된 PDF 를 열어 페이지별로 확인한다. 고칠 게 있으면 해당 섹션 슬라이드 스펙만 고쳐 재실행.

작성 원칙: 화면 슬라이드는 "좌측 설명 + 우측 스크린샷", 텍스트 과밀 금지, 스크린샷은 항상 현재 앱에서 새로 캡처, 사용자 용어로.

3. 언제 어느 걸 쓰나

둘 다 "고객에게 기능 사용법을 전달" 하지만, 갈림길은 산출물의 형태와 출처다.

고르는 기준 한 줄씩:

• client-usage-guide — "고객이 볼 사용법 문서를 빠르게, feature 문서 기반으로 뽑고 싶다." 기능이 여러 개고, 사용자 인식 단위로 묶어 문서화하고 싶을 때.
• manual — "화면을 짚어가며 발표하거나 PDF 로 건네줄 시각 매뉴얼이 필요하다." 클릭 지점을 강조한 스크린샷 워크스루가 핵심일 때.

이 경계는 각 스킬 description 에도 서로를 가리키는 한 줄로 박아 뒀다 — 자연어로 "사용 가이드 만들어줘" / "화면 넣은 매뉴얼 만들어줘" 라고 부를 때 엉뚱한 스킬로 안 새게 하려는 것이다(그 원리는 L28).

오늘 정리 + 다음

• 정리: 고객용 산출물 스킬은 둘 — client-usage-guide(feature 문서 기반 md 사용 가이드, 스크린샷 기본 포함)와 manual(손으로 짠 SECTIONS 로 만드는 슬라이드/PDF 매뉴얼, 주황 강조 캡처가 핵심). 갈림길은 "읽는 문서냐, 넘겨 보는 덱이냐" 그리고 "출처가 feature 문서 자동이냐, 손 작성이냐" 다.
• 흔한 함정: manual 을 처음 쓸 때 playwright install chromium 이나 로컬 한글 폰트가 없어 PDF 생성이 실패하거나 한글이 깨지는 것. 사전 준비 3종을 먼저 확인한다.
• 다음 시간: manual 이 쓰는 standarda_core.presentation 렌더 엔진을 뜯어, 화면 없는 일반 발표자료를 직접 만들어 보기.
• 자습 권장: 두 스킬의 SKILL.md(.claude/skills/client-usage-guide/, .claude/skills/manual/)를 직접 열어 워크플로우 섹션을 읽어 본다. 그리고 자기 프로젝트에서 하나를 골라 실제로 산출물을 한 번 뽑아 본다.