작업 브로셔
작업 하나를 끝낸 후 사용자는 두 가지를 원합니다:
- 채팅의 일반 요약: 평소처럼 변경 사항, 현재 상태, 미완료 항목을 설명합니다. 이 스킬은 결코 이 요약을 대체하거나 줄이지 않습니다.
- 브로셔: 하나의 독립적인 HTML 페이지로 동일한 작업을 시각적으로 안내합니다. 사용자는 이 페이지를 채팅 옆에 열어두고 다이어그램, 스크린샷, 주석이 달린 코드를 통해 변경 사항을 이해할 수 있습니다.
브로셔는 코드에 정확해야 합니다. 모든 주장, 숫자, 파일 경로, 스크린샷은 실제 diff, 실행한 명령어, 확인한 앱에서 비롯됩니다. 실행하지 않은 테스트나 보지 못한 결과를 절대 만들어내지 마십시오.
단계
1. 먼저 채팅 요약을 작성하세요
평소처럼 작업을 마치고, 일반 텍스트 요약과 wrap_up(앱에 있는 경우)을 포함하세요. 그런 다음 브로셔를 만듭니다. 사용자가 이전 작업의 브로셔만 요청했다면 2단계로 바로 건너뜁니다.
PR이 열린 후(플러그인의 PostToolUse 훅 또는 설정의 훅이 gh pr create 후 알림을 추가함), 같은 턴에 gather.sh --pr <N>을 실행하여 해당 PR에 대한 브로셔를 만들고, 마무리 메시지에 브로셔 링크를 포함하세요. 사용자가 요청하지 않는 한 PR 본문을 수정하여 링크를 추가하지 마십시오. PR이 사소한 한 줄짜리(오타, 버전 범프)인 경우에만 건너뜁니다.
2. 사실을 수집하세요
저장소 루트에서 헬퍼 스크립트를 실행합니다(커밋, 폴더별로 그룹화된 파일별 diffstat, 커밋되지 않은 변경 사항, PR 정보를 출력합니다):
bash <skill-dir>/scripts/gather.sh # 현재 브랜치 vs main + 커밋되지 않은 변경
bash <skill-dir>/scripts/gather.sh A..B # 임의의 git 범위 (예: 이미 병합된 작업)
bash <skill-dir>/scripts/gather.sh --pr 51 # GitHub PR
그런 다음 diff의 중요한 부분을 읽습니다(git diff <범위> -- <경로>). 전체를 읽지 마십시오. 또한 이 대화에서 다음을 수집합니다:
- 이유: 사용자 자신의 표현으로 된 문제 또는 요청.
- 결정: 고려한 옵션과 현재 선택을 한 이유.
- 검증: 실행한 명령어와 실제 출력, 찍은 스크린샷, 브라우저나 시뮬레이터에서 확인한 내용, 그리고 확인할 수 없었던 내용.
- 미해결 사항: 후속 작업, 위험, 남은 작업.
- 사용자에게 필요한 것: 사용자만이 결정하거나, 눈으로 확인하거나, 승인할 수 있는 사항.
3. 실제 앱을 캡처하세요 (변경 사항이 시각적인 경우)
변경 사항이 UI에 나타나는 경우, 브로셔는 실제 애플리케이션을 보여주어야 하며, 설명으로 대체해서는 안 됩니다.
- 이후: 미리보기 도구(
preview_start를 프로젝트의 launch.json 서버로 실행, 탐색,computer {action: "screenshot"}) 또는 iOS 시뮬레이터screenshot을 사용하여 실행 중인 앱의 변경된 화면을 스크린샷으로 찍습니다. 레이아웃이 변경된 경우 데스크톱 및 휴대폰 너비를 모두 캡처합니다. - 이전: 차이가 중요한 경우, 기본 리비전을 스크래치패드의 임시 워크트리로 체크아웃하고(
git worktree add <scratchpad>/before <base>), 다른 포트에서 서빙한 후 동일한 뷰를 스크린샷으로 찍고 워크트리를 제거합니다(git worktree remove). 변경 사항이 순수하게 추가적이거나 "이전"이 아무것도 추가하지 않는 경우 이 단계를 건너뜁니다. - 스크린샷을 스크래치패드에 파일로 저장하고, 크기를 줄인 후(
sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg)data:URI로 삽입합니다. 전체 페이지를 약 8MB 미만으로 유지합니다. - 비디오/애니메이션 변경의 경우, 몇 장의 스틸 프레임(
ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) 또는 프레임 스트립과 측정된 숫자를 삽입합니다. - 비시각적 변경(스크립트, 데이터, 백엔드)은 스크린샷 대신 다이어그램과 실제 출력을 사용합니다.
4. 스토리를 계획한 후 시각 자료를 선택하세요
사용자가 설명을 듣고 싶어할 순서로 페이지를 구성합니다: 결과를 먼저, 그 다음 작동 방식, 마지막으로 세부 사항. 변경된 내용에 따라 시각 자료를 선택합니다. 텍스트보다 한 장의 그림이 더 빠르게 설명할 수 있는 곳에는 그림을 선호합니다. 산문은 짧은 캡션과 한두 문장의 단락으로 유지합니다.
| 변경된 내용 | 사용할 시각 자료 |
|---|---|
| 로직, 파이프라인, 결정 규칙 | 새로운 흐름의 Mermaid flowchart; classDef changed로 새롭거나 변경된 노드 강조 |
| 부분 간 요청 (UI → API → 저장소) | Mermaid sequenceDiagram |
| 구조 (모듈, 파일, 데이터 형태) | +/− 막대가 있는 파일 맵; 부분 연결 방식을 보여주는 Mermaid graph; 전/후 필드 테이블 |
| UI | 전/후 스크린샷 쌍; 이미지 위에 번호가 매겨진 콜아웃으로 주석 추가 |
| 숫자 (시간, 크기, 개수, 성능) | 비율에 맞게 그려진 인라인 SVG 막대 차트, 전 vs 후 |
| 상태 또는 라이프사이클 | Mermaid stateDiagram-v2 |
| 작업 순서 (마이그레이션, 다단계 변경) | 번호가 매겨진 워크스루 단계 (순서가 실제로 중요한 경우만) |
| 핵심 코드 | 중요 행이 표시된 짧은 diff 발췌 (5–25줄), <details> 안에 넣어 지나치게 두드러지지 않도록 함 |
기능 크기의 변경에는 최소 세 가지 이상의 뚜렷한 시각 자료를 목표로 하고, 더 작은 변경에는 최소 하나를 목표로 합니다. 다이어그램은 실제 메커니즘(실제 함수 이름, 파일 이름, 값)을 설명해야 하며, 일반적인 상자가 아니어야 합니다.
5. 템플릿에서 페이지를 만드세요
<skill-dir>/template.html을 복사하여 채웁니다. 템플릿에는 이미 스케치북 스타일(의도적으로 하나의 라이트 테마: 모눈종이 배경, 손글씨 제목, 연필로 스케치한 카드, 손으로 그린 다이어그램), 레이아웃, 위에 나열된 모든 컴포넌트가 포함되어 있습니다. 사용자가 요청하지 않는 한 다크 모드를 추가하거나 모양을 바꾸지 마십시오. 규칙:
<style>블록과 Mermaid 로더 스크립트를 유지하고, 예제 콘텐츠를 교체합니다. 적용되지 않는 섹션은 얇게 남겨두지 말고 삭제합니다(예: 순수 리팩터링의 경우 "이전 → 이후" 없음).<title>: 기능 이름, 2~4단어 (예: "체크아웃 재시도 로직"), "작업 요약: …"이 아닙니다.- 히어로: 결과에 대한 한 문장, 메타 라인(브랜치, PR 링크, 날짜), 통계 스트립(파일, +/− 줄, 커밋, 통과한 검사). gather.sh에서 숫자를 계산하고 추정하지 마십시오.
- 사용자 입력 필요(히어로 아래 스티커 메모): 사용자를 기다리는 실제 요청만, 각각 한 줄, 어디를 봐야 하는지 표시. 최대 세 개. 항목이 없으면 전체 메모를 삭제하고, 절대 채우지 마십시오.
- 이렇게 한 이유(결정 테이블): 세션에서 실제로 고려된 2~4개의 옵션, 하나는 '선택됨'으로 표시, 각각 한 줄의 장단점. 채우기 위해 대안을 만들지 마십시오. 실제 결정이 없었다면 섹션을 삭제합니다.
- 페이지를 간결하게 유지: 위의 두 가지와 적용되는 섹션만 포함합니다. 템플릿 이상의 섹션을 추가하지 마십시오.
- 파일 맵: 의미 있는 파일당 한 행 (생성된/바이너리 파일은 한 행으로 그룹화), +/− 막대 너비는 가장 큰 파일의 총 변경량에 대한 백분율, 변경 이유를 평범한 영어로 한 줄.
- Diff 발췌:
<,>,&를 이스케이프합니다.class="add",class="del", 또는class="hl"(중요한 변경되지 않은 줄)로 줄을 표시합니다. - Mermaid는
<pre class="mermaid">안에 넣고, 템플릿의 config 블록(---/config:/look: handDrawn/theme: neutral/---)을 태그 바로 뒤에 시작하여 로컬 파일과 claude.ai 모두에서 손으로 그린 모양으로 렌더링되도록 합니다. 템플릿의classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px줄을 유지합니다. 레이블 내</>는</>로 이스케이프하고, 이 작업에서 추가하거나 변경한 내용에 대해class <ids> changed를 사용합니다. 각 다이어그램을 약 5–9개 노드로 유지하여 한 화면에 맞춥니다: 연속 단계를 하나의 노드로 병합하고<br/>세부 줄을 추가하며, 더 긴 흐름은 두 개의 다이어그램으로 나눕니다. 짧은 체인에는flowchart LR, 분기 흐름에는TD를 사용합니다. - 검증: 각 확인 항목을 통과/실패/미확인 칩과 증거(출력 발췌 또는 스크린샷)와 함께 나열합니다. "미확인" 항목은 존재하는 경우 필수입니다.
- 간결하게 작성: 짧은 문장, 사용자의 용어, 불필요한 내용 없음.
<repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html로 저장합니다. 해당 폴더를 모든 저장소에서 git에서 제외하기 위해 로컬 제외 파일에 한 번 추가합니다 (.gitignore를 건드리지 않음):
mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")
6. 한 번 확인한 후 전달하세요
- 브라우저 패널에서 한 번 엽니다(
preview_start를url: file://<path>로 실행하거나 프로젝트의 정적 서버 사용). 다이어그램이 렌더링되었고 오버플로가 없는지 확인하기 위해 스크린샷 한 장을 찍습니다. 그 한 번의 확인으로 보이는 문제를 수정하고, 반복하지 마십시오. - 사이드 패널에 표시합니다:
SendUserFile을display: "render"로 실행. - 비공개 아티팩트로 게시합니다(
Artifact게시, 파일 경로,icon: "document", 한 문장 설명 포함). 이렇게 하면 워크트리가 정리된 후에도 유지됩니다. 이것이 영구적인 복사본이며, 아티팩트는 기본적으로 비공개입니다. 아티팩트 도구를 사용할 수 없는 경우(예: 일반 터미널 세션), 이 단계를 건너뛰고 로컬 경로를 제공합니다. - 채팅에서, 일반 요약 후에 브로셔 링크와 로컬 파일 경로를 한 줄로 추가합니다.
업데이트: 사용자가 변경을 요청하면, 동일한 파일을 편집하고 동일한 경로로 다시 게시하여 링크가 유지되도록 합니다.
좋은 브로셔의 예
- 세션에 참여하지 않은 사람도 2분 이내에 스크롤하면서 무엇이 변경되었고 왜 그런지 이해할 수 있습니다.
- 첫 화면에서 스크롤 없이 "무엇이 달라졌나요?"에 답합니다.
- 모든 다이어그램, 차트, 스크린샷은 이번 변경 사항의 것입니다.
- 정직한 상태가 표시됩니다: 무엇이 검증되었고, 무엇이 검증되지 않았으며, 무엇이 남았는지.