release-showcase — 화면으로 보여 주는 릴리스 문서

릴리스 노트가 커밋 제목 목록이면 읽는 사람은 무엇이 어떻게 바뀌었는지, 자기가 무엇을 해야 하는지 알 수 없다. 이 스킬은 사용자가 겪는 변화 단위로 묶은 이야기(story.json)에 저장소가 이미 가진 시각 자료를 붙여, 메신저에 그대로 올릴 수 있는 HTML 한 파일을 만든다.

• 화면은 지어내지 않는다. 이전·이후 태그 시점에 커밋된 스크린샷(골든)을 git show로 꺼내고, 영상은 태그 시점 코드를 띄워 녹화한다.
• 실데이터 위주로 보여 준다. 사용자가 실제로 넣을 자료(실제 서류·기록·사진, 식별 정보는 가림)와 그 자료로 제품이 실제로 낸 결과가 "합성 예시"보다 훨씬 잘 읽힌다. 테스트 데이터는 실제 자료를 구할 수 없을 때만 쓰고, 그 사실을 팀 참고에 적는다(아래 "실데이터").
• 글 품질은 손으로 기억하지 않는다. check가 기계로 보고(TODO·없는 그림·미배포 PR·앱에 없는 메뉴 이름·쓰지 않기로 한 말·어투), verify가 데스크톱·모바일 폭으로 열어 넘침·빈 이미지·영상·상호작용을 본다.
• 결과물: <stories>/<태그>/<태그>.html (이미지·영상이 base64로 들어 있어 첨부 하나로 끝난다).

경로 표기: <SKILL_DIR>는 이 SKILL.md가 있는 폴더다. 명령은 대상 저장소 안에서 python3 <SKILL_DIR>/scripts/showcase.py …로 실행한다(아래에서는 showcase로 줄인다).

진행 체크리스트

아래를 할 일 목록으로 만들고 차례로 닫는다. 게이트를 통과하지 못하면 다음 단계로 가지 않는다.

• 0 준비 — 설정 파일·도구
• 1 범위 — 이번 태그와 기준 태그
• 2 재료 — 화면 후보·PR 본문 읽기
• 3 story.json 쓰기 + 실데이터 고르기
• 4 clips.json 쓰기 (녹화할 수 있는 앱만)
• 5 check 오류 0
• 6 build --record --verify 통과
• 7 남긴 화면을 직접 열어 보기
• 8 한국어 문장 다듬기
• 9 보고·공유

0. 준비

• 저장소 루트에 .release-showcase/config.json이 있는지 본다. 없으면 references/config.md대로 만든다. 앱마다 태그 접두사·소스 경로·스크린샷 폴더·화면 문구 경로·녹화 방법을 적는다. 저장소에 프로젝트 전용 스킬이나 CLAUDE.md가 있으면 거기 적힌 릴리스 규칙(기준 태그 고르는 법, 쓰지 않는 말)을 먼저 읽는다.
• 필요한 것: git, Python 3.10+, gh(PR 본문·릴리스 파일 — 없으면 그 부분만 빠진다), Node 18+ 또는 bun(녹화·검수), ffmpeg + libx264(영상 녹화·MP4 인코딩 — 없으면 흐릿한 WebM으로 물러나 Safari·iPhone에서 재생되지 않는다). Playwright는 프로젝트의 node_modules에 있으면 그것을, 없으면 ~/.cache/release-showcase에 한 번 설치한다.
• git fetch --tags로 태그를 최신으로 맞춘다.

1. 범위

showcase init <이번 태그>            # 기준 태그를 골라 story.json 초안과 .media/brief.md를 만든다
showcase init <이번 태그> --base <태그>

• 기준(base)은 사용자가 직전에 실제로 쓰던 정식 버전이다. staging·beta·rc 태그는 기준이 아니다. 며칠 만에 핫픽스가 이어졌으면(예: 1.4.4 → 다음 날 1.4.5) 그 사슬은 건너뛰고 그 앞 버전을 기준으로 둔다. init이 이 규칙으로 고른 이유를 출력하니 맞는지 확인한다.
• 브랜치가 갈라져 있어도(stable·main, cherry-pick) 변경 목록은 PR 번호로 가르므로 이중 계산이 없다.

게이트: 기준 태그가 정식 태그이고, 고른 이유를 설명할 수 있다.

2. 재료

• .media/brief.md를 읽는다: 범위, 새로 생기거나 바뀐 화면 목록, 새 기능 PR 본문 요약, 고친 것 목록.
• 새 화면은 하이라이트 후보, 바뀜은 대부분 공통 요소(로고·문구) 변화라 작은 카드(minor) 후보다. showcase goldens <태그>로 다시 볼 수 있다.
• 하이라이트에 쓸 PR은 gh pr view N으로 본문 전체를 읽고 왜 바꿨는지, 사용자 흐름이 어떻게 달라지는지 확인한다. 제목만 보고 쓰지 않는다.
• 같은 기간 서버 변경 중 이 앱 사용자가 느끼는 것(품질·한도·속도)은 팀 참고(notes) 후보다.
• 보여 줄 화면이 저장소에 없으면 먼저 스크린샷 테스트(골든)를 더하는 것이 정석이다. 급하면 직접 찍은 그림을 .media/에 두고 local로 쓴다(references/story.md).

3. story.json

형식은 references/story.md, 문장 기준과 좋은·나쁜 예는 references/writing.md를 먼저 읽고 쓴다. 요점:

• 하이라이트 3~6개. 각각 lead(예전에는 어땠고 지금은 어떤지 두 문장), points(사실만 — 숫자·조건·화면 문구), how(따라 할 순서, 메뉴 경로는 앱 문구 그대로), prs, media.
• 하이라이트마다 시각 자료가 하나는 있다. 바뀐 화면은 compare, 여러 단계 흐름은 video+steps, 상태가 여럿이면 tabs, 절차가 바뀌었으면 flow.
• audience: 독자별(처음 쓰는 분 / 이미 쓰던 분 / 지원·영업 등) 카드에 할 일이 있는지 없는지를 먼저 말한다.
• 태그에 없는 기능은 쓰지 않는다 — 머지됐어도 이 태그에 안 들어갔으면 다음 문서 몫이다. check가 하이라이트의 PR이 태그에 있는지 본다.

3-1. 실데이터

하이라이트마다 "사용자가 넣는 것 → 제품이 내는 것"이 있으면 그 둘을 실제 사례로 보여 줄 수 있는지 먼저 본다(예: 첨부 기능이면 실제 검사지·기록 화면 사진과 그걸로 만든 실제 결과).

• 자료는 사용자·팀에게 받는다. 받은 자료는 식별 정보(이름·등록번호·생년월일·연락처·기관명, 뒷면 비침)를 가린 사본만 쓴다. 가린 사본을 직접 열어 남은 것이 없는지 확인한다.
• 실제 자료와 그 결과는 커밋하지 않는다 — <story>/.media/real/(gitignore)에 둔다. check는 clips가 가리키는 파일이 없으면 오류를 내므로, 다른 사람이 다시 만들 때는 자료를 받아 같은 자리에 둔다.
• 결과도 지어내지 않는다. 제품의 실제 처리(서비스 함수·API)를 그 자료로 한 번 돌려 받은 출력을 쓴다. 이때 관측 도구(추적·로그)에 자료 원문이 남지 않게 끈다.
• 녹화 하네스가 목 응답을 쓰면 clip의 initScript·initData로 그 응답만 실제 결과로 바꾸고, 자료는 upload 단계로 넣는다(references/story.md "clips.json").
• 팀 참고(notes)에 어떤 화면이 실데이터이고(무엇을 가렸는지), 어떤 화면이 테스트 데이터인지 적는다. 실제 처리 시간을 영상에서 줄였으면 그것도 적는다.

4. clips.json (녹화)

설정에 record가 있는 앱만 한다. 새 기능의 대표 흐름 1~2개를 30초 안팎으로 고른다. 단계는 화면의 텍스트·버튼 이름으로 찾는다(형식은 references/story.md "clips.json").

• 단계 이름은 태그 시점 소스에서 확인한다(git grep -n "<문구>" <태그> -- <uiDir>). 실패하면 .media/<id>.fail.png에 그 순간 화면이 남으니 열어 보고 고친다.
• 녹화할 수 없는 앱(모바일 네이티브 등)은 시뮬레이터 녹화 파일을 .media/<id>.webm(또는 .mp4)으로 넣고 챕터를 .media/<id>.chapters.json에 적는다. 영상 없이 steps·tabs만으로도 된다.

5. 검사

showcase check <태그>

• ✗ 오류는 전부 고친다. 빌드는 오류가 있으면 멈춘다.
• △ 경고는 고치거나, 그대로 둘 이유를 보고에 적는다. 특히 "앱 소스에서 찾지 못했어요"는 메뉴 이름을 지어냈다는 뜻일 때가 많다.
• · 범위 안내의 "글에 안 쓴 새 기능 N건"을 훑어 빠뜨린 큰 변화가 없는지 본다.

게이트: 오류 0, 남긴 경고마다 이유가 있다.

6. 빌드·검수

showcase build <태그> --record --verify   # 처음: 태그 worktree에서 녹화 → HTML → 검수
showcase build <태그> --verify            # 글만 고친 뒤: 녹화본 재사용, 몇 초
showcase verify <태그>                    # 만들어 둔 HTML만 다시 검수

• --record는 태그 시점 코드를 임시 worktree로 꺼내 설치·실행하고 녹화한 뒤 지운다. 작업 중인 브랜치로 녹화하면 아직 나가지 않은 화면이 섞인다.
• --verify는 1280px·400px로 열어 가로 넘침, 빈 이미지, 재생 안 되는 영상, 영상 길이를 넘는 챕터, 반응 없는 비교·단계·탭·챕터·크게 보기, 콘솔 오류를 잡고 .media/review/에 화면을 남긴다.

게이트: 검수 통과.

7. 눈으로 보기

.media/review/의 desktop-*·mobile-* PNG를 직접 열어 본다. 기계가 못 잡는 것: 글과 그림이 맞지 않음, 비교의 이전·이후가 바뀐 점을 못 보여 줌, 영상이 너무 길거나 핵심 전에 끝남, 영상·그림 속 제품 화면이 틀에 비해 작음, 모바일에서 한 줄에 한두 글자씩 끊기는 제목, 화면 속 자료가 "합성·테스트"처럼 보여 실제 쓰임이 안 그려짐(실데이터로 바꿀 수 있는지 다시 본다), 가리지 못한 식별 정보.

8. 한국어 문장

check가 .media/copy.txt에 사람이 읽는 글만 모아 둔다. ko-natural 스킬이 있으면 그 린트로 한 번 돌리고(--register casual), 없으면 references/writing.md 기준으로 직접 다듬는다. 고친 뒤 build를 다시 한다.

9. 보고·공유

• 사용자에게: 결과 HTML 절대 경로, 범위(기준 → 이번), 하이라이트 목록, 남긴 경고와 이유, 영상이 없는 하이라이트와 그 이유.
• 공유는 결과 HTML 한 파일을 팀 메신저에 첨부하거나 GitHub Release 파일로 올린다. 프로젝트에 정해진 공유 경로가 있으면 그것을 따른다.
• .media/(녹화본·재료·검수 화면)와 결과 HTML은 커밋하지 않는다(.gitignore). 커밋하는 것은 config.json, story.json, clips.json뿐이다.

함정

• 실데이터는 가린 사본만, 저장소 밖에만. 가리지 않은 원본이나 실데이터를 커밋하지 않는다. 골든·녹화에 우연히 실제 사용자 정보가 보이면 그 화면은 싣지 않는다.
• 스크린샷 안의 버전 표기·날짜가 테스트 고정값일 수 있다. 그렇다면 설정 notes에 한 줄 적어 팀 참고에 남긴다.
• 비교(compare)는 같은 파일 이름이라도 두 태그에서 내용이 같으면 check가 막는다 — 바뀌지 않은 화면은 image로.
• 녹화에서 두 번째 영상이 멈추는 일을 막으려고 영상마다 별도 프로세스로 찍는다. 녹화가 느리면 영상 수를 줄인다.
• 영상은 장치 픽셀(record.scale) 그대로 찍는다(Chrome screencast + ffmpeg). Playwright 기본 녹화는 배율을 무시해 제품 화면이 틀 왼쪽 위에 작게 찍히므로 쓰지 않는다 — ffmpeg가 없을 때만 그쪽으로 물러난다(흐릿함).
• 영상은 H.264 MP4로 싣고 페이지가 열릴 때 Blob 주소로 바꿔 튼다. WebM은 Safari·iPhone이 못 틀고, data: 주소 영상은 Safari가 열지 못한다. verify는 영상을 실제로 틀어 시간이 흐르는지 본다.
• 결과 HTML이 10MB를 넘으면 메신저 첨부 한도에 걸린다. 영상을 줄이거나(30초 안팎) steps로 바꾼다.