데모 녹화하기

데모 녹화하기은(는) 무엇을 하나요?

사람이 앱을 사용하는 것처럼 보이는 둘러보기 영상을 녹화합니다. - 곡선 커서 경로, 키 입력별 타이핑, 의도적인 멈춤 - 기계가 UI를 순간이동하는 것과는 다릅니다.

아래 규칙은 모든 표면의 모든 녹화에 적용됩니다. 플랫폼 레퍼런스가 아닌 여기에 있는 이유는 각 규칙이 한 번씩 어겨져서 다시 촬영해야 했고, 하나의 메커니즘 옆에만 두면 다음 사람이 읽지 않기 때문입니다.

표면 선택하기

• 웹 앱 - reference/web.md. Playwright 아래 헤드리스 Chromium으로, 페이지에 DOM 커서가 그려집니다. 운영자의 화면에는 아무것도 도달하지 않으므로, 변경 사항이 브라우저에서 보일 때는 항상 이것을 선호하세요.
• 데스크탑 앱 - reference/desktop.md. 데모에 실제 Electron 셸이 필요할 때 사용합니다: 네이티브 메뉴, 파일 다이얼로그, 트레이, 여러 창, 또는 렌더러 외부의 모든 것. Linux에는 번들 러너가 있습니다. macOS는 단일 창을 ID로 녹화하며 아직 러너가 없습니다.

변경 사항이 둘 다 보이면 웹 앱을 녹화하세요.

입력

첫 테이크 전에 이것들을 확립하세요. 프로젝트에서 찾을 수 있는 곳(README, package.json 스크립트, Electron 메인 프로세스)에서 읽고, 찾을 수 없는 것은 추측하지 말고 사용자에게 물어보세요.

• 웹: 실행 중인 앱의 URL로, PR_RECORDER_BASE_URL로 레코더에 전달됩니다(예: http://localhost:3000). 앱은 변경 사항이 있는 체크아웃에서 이미 실행 중이어야 하며, 커밋되지 않은 편집 내용도 포함됩니다 - 같은 브랜치의 새 체크아웃에는 그것들이 없으며, git은 같은 브랜치를 두 번 체크아웃하는 것을 거부합니다. 또한 데모에 필요한 상태여야 합니다. 흐름에 로그인한 사용자나 시드 데이터가 필요하면, 그것은 레코더의 일이 아니라 프로젝트의 설정이 제공할 일입니다 - 하지만 캡처 시작 전에 확인하세요. 그렇지 않으면 로그인 화면을 얻게 됩니다.
• 데스크탑:
  • DEMO_APP_DIR - 앱의 실행 명령이 실행되는 디렉토리입니다.
  • DEMO_WINDOW_TITLE - 메인 창의 정확한 제목으로, X11 창과 렌더러 페이지를 모두 찾는 데 사용됩니다.
  • DEMO_LAUNCH_CMD - 선택 사항. {port}에서 원격 디버깅으로 앱을 시작하는 셸 명령입니다. 기본값인 pnpm dev --remoteDebuggingPort {port} --noSandbox는 electron-vite에 적합합니다.

스킬이 위치한 곳

이 문서에서 <skill-dir>은 이 SKILL.md가 로드된 디렉토리를 의미합니다. Claude Code에서는 ${CLAUDE_SKILL_DIR}이며, 프로젝트, 개인 및 플러그인 설치 모두에 적용됩니다. 다른 곳에서는 스킬이 로드된 경로를 사용하세요 - Codex의 경우, 리포지토리의 .agents/skills/record-demo 폴더 또는 ~/.agents/skills/record-demo입니다. 한 번 확인하고 절대 경로를 사용하세요. 스크립트는 스킬이 설치된 위치를 추정하지 않습니다.

중요한 테이크 전에 리허설하세요

배송할 테이크를 녹화하기 전에 전체 흐름을 처음부터 끝까지 실행하세요. 데모는 발견되는 것이지, 작성되는 것이 아닙니다: 컨트롤 이름이 예상과 다르고, 버튼이 말한 대로 동작하지 않으며, 표면이 예상보다 안정되는 데 시간이 더 걸립니다. 카메라에서 그것을 발견하면 시청자가 당신이 그것을 발견하는 모습을 보게 됩니다.

리허설은 저렴하고 재녹화도 저렴합니다. 잘못된 방향이 있는 테이크를 배송하거나 리뷰어에게 중간 8초를 무시해 달라고 요청하는 것은 그렇지 않습니다.

먼저 실제 컨트롤 이름을 확인하세요

존재를 확인하지 않았고 이름이 제안하는 대로 동작하는지 확인하지 않은 컨트롤에 대해 스크립팅하지 마세요. 앱을 한 번 로드하고, 접근성 이름을 덤프하고, 스크린샷을 찍으세요:

const names = await page
  .getByRole("button")
  .evaluateAll((els) =>
    els.map((e) => (e.getAttribute("aria-label") || e.textContent || "").trim()).filter(Boolean),
  );
console.log(JSON.stringify(names));
await page.screenshot({ path: "/tmp/probe.png" });

그런 다음 스크린샷을 읽으세요. 덤프는 이름이 존재한다는 것을 알려줍니다. 오직 그림만이 컨트롤이 무엇인지 알려줍니다. 네 가지 문제점:

• 예상과 다른 이름. 스위처의 접근성 이름은 현재 선택된 항목의 이름이었고, "Select project"가 아니었습니다.
• 소리만 들어서는 알 수 없는 이름. 사이드바의 Files 버튼은 섹션 토글이어서, 클릭하면 아무데도 탐색하지 않고 섹션이 접혔습니다. 그게 테이크에 배송되었습니다.
• 다른 이름의 일부인 이름. getByLabel("First message")가 "first message"를 포함한 레이블을 가진 근처 옵션과도 일치하여, 입력이 필드에 도달하지 못했지만 아무것도 실패하지 않았습니다. exact: true를 전달하거나 역할과 이름 모두에 일치시키세요.
• 텍스트처럼 보이지만 그렇지 않은 것. 스크린샷에서 읽은 선택기 제목은 입력의 플레이스홀더여서 getByText가 결코 일치할 수 없었습니다. 스크립팅하기 전에 로케이터가 해결되는지 확인하세요.

여러 요소가 이름을 공유할 때 - 아이템이 사이드바, 페이지 헤더 및 브레드크럼에 나타나는 경우 - .first()로 범위를 지정하세요.

사람이 조작하는 방식으로 구동하세요

보이는 역할이나 텍스트로 컨트롤을 찾으세요 (getByRole, getByText, getByLabel, getByPlaceholder). CSS 선택자, 테스트 전용 속성은 절대 사용하지 말고, 녹화가 무언가를 찾을 수 있도록 앱에 훅을 추가하지 마세요. 데모 스크립트는 일회용이며 PR별로 사용합니다. 리포지토리 외부에 두세요.

데모를 위해 앱, 스킬 또는 프로덕션 코드를 절대 수정하지 마세요. 데모에 앱이 달라야 한다면, 데모가 잘못된 것입니다.

시간에 절대 의존하지 마세요

waitForTimeout(9000)으로 "에디터가 로드되도록 기다리는" 것은 볼만하지만 지루한 데모의 가장 큰 원인입니다. 항상 최악의 경우를 기다리며, 그 모든 초가 파일에 남습니다. 실제로 기다리고 있는 것 - 상호작용할 첫 번째 컨트롤 - 을 기다리세요. 그래야 데모가 앱이 준비되는 즉시 계속되고, 로케이터를 명명하며 크게 실패하고, 반쯤 빌드된 페이지를 구동하는 대신 실패합니다.

고정된 일시 중지는 페이싱 용도로만 사용하세요: 시청자가 변경된 내용을 인지할 수 있도록 액션 후 약간의 박자. 초 단위, 수십 초가 아니며, 대기를 대체하는 용도로 절대 사용하지 마세요.

쓰여진 파일은 증거가 아닙니다

레코더는 스크립트가 예외를 던질 때 부분 파일을 플러시하고, 일부 캡처 도구는 종료 시 발생한 것을 씁니다. 따라서 파일이 존재하는 것 자체는 아무 의미가 없습니다. 테이크를 믿기 전에:

• 종료 상태와 stderr를 확인하고, 오류가 있으면 읽으세요 - 보통 일치하는 것이 없는 로케이터를 명명합니다.
• 출력 경로를 이미 보유하고 있는 오래된 캡처가 있는지 확인하세요. 이전 시도에서 계속 실행 중인 캡처가 여전히 파일 이름을 소유하고 있으며, 잘못된 것의 녹화를 조용히 생성할 것입니다.
• 프레임을 확인하세요. 연락처 시트, 마지막 프레임 및 확실하지 않은 전환을 추출하고 살펴보세요.

데모를 확인하고, 스크립트를 확인하지 마세요

깨끗한 종료는 스크립트가 실행되었다는 것을 의미할 뿐, 기능이 작동했다는 것을 의미하지 않습니다. 둘 다 확인하세요:

• 시각적 - 변경 사항이 프레임의 화면에, 요청한 상태로 있습니다.
• 기능적 - 유지된 상태가 실제로 변경되었으며, UI에서 추론하는 것이 아니라 데이터베이스나 API에서 읽었습니다.

주장이 레이아웃에 관한 것일 때 - 두 패널이 나란히, 패널이 가장자리에 도킹됨 - 경계 상자에서 주장하세요. 요소가 존재한다고 해서 그것들이 어디에 있는지는 알 수 없습니다.

최종 상태를 약 3초 동안 유지하여 시청자가 볼 수 있게 한 후, 출력 파일의 코덱, 크기 및 지속 시간을 ffprobe로 확인한 후 전달하세요.

증거를 보관하세요

테이크가 성공할 때까지 실패 로그, 부분 테이크 및 스크린샷을 보관하세요. 배송할 만한 것이 생긴 후에만 폐기 가능한 상태를 삭제하세요. 버려진 중간 결과는 종종 테이크가 잘못된 이유에 대한 유일한 기록입니다.

녹화 중인 머신을 방해하지 마세요

로컬 녹화는 사람의 실제 컴퓨터에서 그들이 사용하는 동안 실행됩니다.

• 앱에 자체 폐기 가능 프로필을 제공하고 운영자의 실제 프로필을 절대 건드리지 마세요.
• 데모에 필요한 것을 첫 실행 전에 시드하세요. 그렇지 않으면 첫 실행 화면이 그들 앞에 나타납니다.
• 시작한 모든 프로세스를 소유하고, 완료되면 중지하세요 - 특히 스크립트가 반환된 후에도 계속 실행되는 캡처.
• 장기 실행 프로세스는 포그라운드 래퍼 내에서 후행 &로 시작하지 말고, 핸들을 잡고 있는 백그라운드 작업으로 시작하세요. 래퍼가 종료되면 서버도 함께 종료됩니다.
• 프로세스가 예상하는 방식으로 중지하세요. SIGKILL로 죽인 개발 서버는 정리 트랩을 건너뛰고 다시 쓰여진 env 파일과 오래된 포트 파일을 남겼습니다. 시작한 프로세스에 신호를 보내고 정리하게 하세요. 절대 패턴-킬(pkill -f next)을 사용하지 마세요. 공유 머신에서는 다른 사람의 서버도 종료시킵니다.
• 데모 중인 앱이 어떤 백엔드와 통신하는지 확인하세요. 한 개발 런처는 달리 지시하지 않는 한 프로덕션 API를 기본값으로 사용하여, 데모의 클릭이 실제 데이터를 썼을 수 있습니다. 첫 테이크 전에 로컬 또는 개발 백엔드를 가리키세요.
• 데모가 의존하는 외부 항목(로그인해야 하는 CLI, 가동 중이어야 하는 서비스)을 디스플레이를 잡거나 캡처를 시작하기 전에 사전 점검하세요. 그래야 누락된 종속성이 테이크 중간이 아닌 몇 초 만에 실패합니다. 도구가 실행되었음을 증명하기 위해 메시지 보내기와 같은 부작용 작업을 절대 수행하지 마세요.
• 테이크에 그들의 화면, 그들의 창 관리자 또는 그들의 입력이 필요하면 말하고 물어보세요. 빼앗지 마세요.

파일을 PR에 첨부하기

gh는 v2.99.0부터 비디오 자체를 업로드합니다:

gh pr comment <number> --body-file ./note.md --attach ./demo.mp4

--attach는 gh pr create, gh pr edit 및 gh issue 동등 명령에도 작동합니다. 명령당 최대 50개 파일까지 반복 가능하며, user-attachments CDN에 업로드되어 GitHub에서 비디오를 인라인으로 렌더링합니다.

알아둘 네 가지:

• 대체 텍스트는 이미지 전용입니다. './shot.png#The error state'는 이미지에 대체 텍스트를 설정합니다; 비디오에 동일한 구문을 사용하면 cannot set alt text on video로 거부됩니다. 비디오는 경로만으로 첨부하세요.
• 로컬 경로를 이미 참조하는 본문은 다시 작성됩니다. 원하는 위치에 ![alt](./demo.mp4)를 쓰면 gh가 업로드된 URL로 바꿉니다; 그렇지 않으면 첨부 파일이 끝에 추가됩니다.
• 본문 플래그 없이 gh pr edit --attach를 사용하면 기존 본문을 유지하고 추가합니다. 따라서 데모를 사후에 PR 설명에 추가할 수 있습니다.
• 의존하기 전에 버전을 확인하세요. 2.99.0보다 오래된 gh에는 --attach가 없으며, API를 통해 다른 방법으로 CDN에 도달할 수 없습니다. 따라서 사람에게 PR에 직접 끌어다 놓을 파일 경로를 제공하는 것으로 대체하세요.