Clickreel

Clickreel은(는) 무엇을 하나요?

당신은 사용자의 실제 앱에 대한 인터랙티브 데모를 만들고 있습니다. 방문자가 랜딩 페이지나 링크를 통해 열면, 강조 표시된 지점을 클릭하고 앱의 실제 다음 화면이 나타납니다. 방문자는 1분 이내에 앱을 시도해 볼 가치가 있는지 판단합니다. 좋은 결과물은 앱이 잘하는 한 가지 작업을 6~12번의 클릭으로 보여줍니다.

사용자가 스토리보드를 작성하고 결과를 평가합니다. Clickreel이 나머지를 처리합니다: 헤드리스 브라우저에서 앱을 열고, 각 단계를 실제로 수행하며, 페이지 전후 사진을 찍고, 화면과 플레이어를 하나의 HTML 파일로 패키징합니다.

명령어

모든 작업은 하나의 스크립트를 통해 이루어집니다. Node와 Chromium 기반 브라우저만 있으면 됩니다.

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <command>

위에서 ${CLAUDE_SKILL_DIR}이 리터럴 텍스트로 나타나면, 에이전트가 이를 채우지 않은 것입니다. 이 SKILL.md가 포함된 폴더를 사용하세요.

명령어	기능
build <storyboard>	단계를 실행하고 스토리보드 옆에 <name>.html(데모)과 <name>.stops.png(접촉 시트)를 작성합니다. 10~30초가 소요됩니다.
check <storyboard>	단계를 실행하고 접촉 시트만 임시 폴더에 작성합니다. 프로젝트를 건드리지 않고 스토리보드를 시험해보는 데 사용합니다.
doctor	이 머신이 데모를 빌드할 수 있는지 확인합니다. 시작에 실패하면 먼저 실행하세요.
init [file]	시작 스토리보드를 작성합니다.

유용한 플래그: --out <dir>, --json, --headed (브라우저 작동 확인), --force.

작업 방법

1. 데모가 보여줄 내용 결정

하나의 데모, 하나의 흐름입니다. 이 앱이 하는 가장 설득력 있는 한 가지가 무엇인지 스스로에게 물어보고, 그 주제로 데모를 만드세요. 사용자가 기능이나 흐름을 지정했다면 그것이 주제입니다. 사용자가 "데모 만들어"만 말했다면, 핵심 흐름(README의 첫 문장이 약속하는 것)을 직접 선택하고 어떤 것을 선택했는지 알려주세요. 앱에 여러 관련없는 제품이 없는 한 사용자에게 선택을 요청하지 마세요.

2. 앱을 실행하고 실제 레이블 파악

앱 시작 방법(package.json 스크립트, README, dist/ 폴더)을 찾으세요. 그런 다음 하나를 선택하세요:

• 이미 실행 중이거나 직접 시작할 수 있음: "url" 설정.
• 정적 사이트 또는 빌드된 폴더: "serve": "./dist" 설정. Clickreel이 제공합니다.
• 나중에 빌드를 반복 가능하게 하려면: "start": "npm run dev"와 "url" 설정. Clickreel이 시작하고 대기합니다.

단계는 사람이 보는 단어(버튼 텍스트, 필드의 레이블 또는 플레이스홀더, aria-label)로 요소를 대상으로 합니다. 선택한 흐름의 컴포넌트를 읽고 레이블을 정확히 복사하세요. 추측하면 한 번 더 왕복해야 합니다.

데모는 볼 가치가 있는 상태에서 열려야 합니다. 빈 첫 실행 화면이나 로그인 벽은 약한 시작입니다. 앱에 데이터나 로그인 세션이 필요하면 첫 번째 스탑 전에 설정하세요: 앱의 시드 스크립트 사용, localStorage에 쓰는 eval 단계 사용, 또는 테스트 계정으로 시작 부분에서 로그인. 비밀번호와 토큰은 환경 변수에 넣고 ${env:NAME}으로 참조하세요. 실제 비밀을 스토리보드에 절대 작성하지 마세요.

3. 스토리보드 작성

별도로 지정하지 않는 한 프로젝트 루트에 demo.click.json으로 저장하세요. 프로젝트에 이미 Demoreel 스토리보드(*.reel.json)가 있으면 해당 파일을 그대로 빌드할 수 있습니다.

{
  "url": "http://localhost:5173",
  "displayUrl": "acme.app",
  "demo": {
    "title": "Acme",
    "intro": "프로젝트가 아이디어에서 완료까지 어떻게 진행되는지 확인하세요.",
    "cta": { "label": "무료 체험", "url": "https://acme.app/signup" }
  },
  "steps": [
    { "say": "몇 초 안에 프로젝트 시작" },
    { "click": "새 프로젝트" },
    { "type": "웹사이트 런칭", "into": "프로젝트 이름" },
    { "click": "프로젝트 만들기" },
    { "say": "입력하는 만큼 빠르게 작업 추가" },
    { "type": "발표 포스트 작성하기", "into": "작업 추가" },
    { "press": "Enter" }
  ]
}

각 단계는 스탑(방문자가 무언가를 하는 것)이 되거나 아무것도 되지 않습니다:

단계	데모에서
{ "click": "새 프로젝트" }	요소 위의 핫스팟. 방문자가 클릭하면 실제 결과가 표시됩니다.
{ "type": "hello", "into": "이메일" }	필드 위의 핫스팟. 클릭하면 텍스트가 입력되는 모습이 재생됩니다. into를 생략하면 포커스된 필드에 계속 입력합니다.
{ "press": "Enter" }	클릭할 키 캡, 또는 방문자가 실제 키를 누릅니다. "Mod+K"는 macOS에서 Cmd, 그 외에서는 Ctrl입니다.
{ "hover": "차트" }	호버링 또는 휴대폰에서 탭에 반응하는 핫스팟.
{ "select": "Pro", "in": "요금제" }	기본 드롭다운 위의 핫스팟.
{ "say": "짧은 한 줄" }	그 이후 스탑 동안 표시되는 캡션. 다음 say까지 유지됩니다. 뒤에 스탑이 없는 say는 다음 버튼이 있는 카드가 됩니다.
{ "zoom": "합계" }	노트: 요소가 강조되고 나머지 페이지가 어두워지며, 다음 버튼과 함께 캡션을 보여주는 카드가 표시됩니다.
{ "scroll": 600 }, { "goto": "/settings" }, { "wait": 800 }, { "waitFor": "리포트 준비 완료" }, { "eval": "..." }	스탑 없음. 데모가 자동으로 통과합니다. 설정 및 올바른 위치로 이동하는 데 사용하세요.

각 핫스팟 옆의 단어는 자동으로 생성됩니다: "새 프로젝트" 클릭, "웹사이트 런칭" 입력, 키 캡과 함께 누르기. 단계에 "hint": "설정 열기"를 추가하면 직접 표현할 수 있습니다. 읽을 수 있는 이름이 없는 선택기를 사용하는 단계에서 이렇게 하세요(기본값은 "여기 클릭").

대상은 표시되는 이름과 정확히 일치하는 순서로 매칭됩니다. 이름이 모호할 때는 "nth": 2를 추가하거나 선택기("css=.sidebar button", "#save", "testid=submit")를 사용하세요. 쿠키 배너를 닫는 것과 같이 작동할 대상이 없을 수 있는 단계에는 "optional": true를 추가하세요.

전체 단계, 옵션, 스타일 및 프레임 목록은 references/storyboard.md에 있습니다. 여기에 표시되지 않은 것을 사용하기 전에 읽어보세요.

4. 빌드

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json

수행할 수 없는 단계는 빌드를 중단하고 정확히 무엇이 잘못되었는지 알려줍니다:

4단계 ("Creat project" 클릭) 실패: 클릭할 "Creat project"를 찾을 수 없습니다.
  혹시: "Create project"?
  현재 화면: "Cancel", "Create project", "Project name"
  해당 순간의 페이지 스크린샷: /tmp/clickreel/demo-123/step-04-failed.jpg

단계를 수정하고 다시 빌드하세요. 프로젝트에 Clickreel이 작성하지 않은 <name>.html이 이미 있으면 빌드가 교체를 거부합니다. 스토리보드에 "name"을 설정하거나 --out <dir>을 전달하세요.

성공한 빌드라도 노트를 출력할 수 있습니다. 읽어보세요. Note: 4단계 (...)가 페이지에서 볼 수 있는 것을 변경하지 않았습니다는 단계가 작동할 대상을 찾았지만 페이지가 이후에 동일하게 보였다는 의미입니다. 거의 항상 잘못된 요소를 찾은 것이며, 데모에서 그 스탑은 아무 효과가 없습니다. 대상(더 정확한 이름, nth, 또는 선택기)을 수정하고 다시 빌드하세요.

5. 결과를 보고하기 전에 확인

build는 접촉 시트 <name>.stops.png를 작성합니다: 각 스탑마다 하나의 그림이며, 핫스팟이 그려져 있고 단계와 캡션이 아래에 있으며, 마지막 화면이 있습니다. 그림을 열고 하나씩 확인하세요. 이것이 자신의 데모를 확인하는 방법입니다.

각 그림에서 다음을 확인하세요:

• 핫스팟. 상자가 의도한 요소에 있고 해당 요소가 보이는가? 잘못된 것에 상자가 있으면 이름이 다른 것과 일치한 것입니다. nth 또는 선택기를 사용하세요.
• 진실. 그림이 앱이 작동하는 모습을 보여주는가? 오류 메시지, 빈 상태, 완료되지 않은 스피너, 플레이스홀더 텍스트를 찾아보세요. 각 그림은 방문자가 클릭하기 전에 보는 것이므로, 그 다음 그림은 클릭 후의 결과를 보여줍니다.
• 캡션. 그림 아래의 캡션이 그림에서 일어나는 일을 설명하는가?
• 마지막 그림. 종료 카드 뒤에 있습니다. 앱의 가장 보기 좋은 상태여야 합니다.

스토리보드를 수정하고 다시 빌드하세요. 2~3회 정도 반복하는 것이 일반적입니다. 시트가 올바르게 보이면 중단하세요.

6. 전달

파일 위치, 크기, 스탑 수, 보여주는 흐름을 사용자에게 알려주세요. build가 출력한 임베드 라인을 제공하세요:

<iframe src="demo.html" title="Acme: 인터랙티브 데모" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>

파일이 무엇인지 명확히 말하세요: 앱 사진이 포함된 하나의 HTML 파일이며, 디스크 및 모든 웹 호스트에서 작동하고 네트워크에서 아무것도 로드하지 않습니다. Clickreel이 출력한 모든 노트(페이지 오류, 가려진 요소, 큰 파일)를 보고하세요. 단계를 작동시킬 수 없어 제거했다면 그렇게 말하세요.

GitHub README는 HTML 파일을 실행할 수 없습니다. README의 경우 데모가 호스팅된 곳(GitHub Pages는 docs/ 폴더를 잘 제공함)으로 링크하거나 Demoreel의 GIF를 사용하세요.

좋은 데모 작성 요약

• 6~12개의 스탑. 각 스탑은 방문자가 클릭해야 하는 것입니다. 설정 단계는 자르거나 첫 번째 스탑 전에 eval로 처리하세요.
• 캡션은 헤드라인입니다. 7단어 이하로, 이점("진행 상황을 체크하세요")에 대해 설명하고 행동("이제 체크박스를 클릭하세요")은 말하지 마세요. 힌트가 이미 무엇을 클릭할지 알려줍니다. 데모에는 3~5개의 캡션이 적당합니다.
• 실제 내용을 입력하세요. "웹사이트 런칭", "test"나 "asdf"가 아닙니다. 입력된 텍스트도 피치의 일부입니다.
• 시작과 끝을 잘 처리하세요. 시작 카드에 demo.title과 한 줄 demo.intro를 설정하세요. 앱의 최상의 상태에서 끝내고 demo.cta를 방문자가 다음에 가야 할 곳으로 설정하세요.
• 배치될 위치에 맞는 크기를 선택하세요. 기본 desktop 뷰포트는 랜딩 페이지에 적합합니다. 모바일 웹 앱의 경우 "viewport": "phone"을 사용하세요. 더 작은 뷰포트는 작은 임베드에서 앱을 더 크게 보이게 만듭니다.

구조, 노트, 자동 재생 및 데모 이벤트 수신에 대한 자세한 내용: references/writing.md.

개인정보 보호 및 정직성

• 모든 것은 이 머신에서 실행됩니다. Clickreel은 자체적으로 네트워크 연결을 열지 않습니다. 브라우저는 사용자가 지정한 앱만 로드합니다. 완성된 파일은 어떤 요청도 하지 않고 아무것도 추적하지 않습니다.
• 데모는 페이지에 있던 것의 사진으로 구성되며, 게시용으로 만들어집니다. 테스트 계정과 가상 데이터를 사용하세요. 사용자의 명시적 동의 없이 실제 고객 데이터, 실제 이메일 주소 또는 내부 URL을 캡처하지 마세요.
• 앱을 있는 그대로 보여주세요. eval을 사용하여 기능을 위조하거나, 실제 오류를 숨기거나, 무언가를 실제보다 빠르게 보이게 하지 마세요. 데이터 시딩 및 개발자 오버레이 숨기기는 괜찮지만, 동작을 조작하는 것은 안 됩니다.

할 수 없는 것

웹 앱만 가능합니다. 화면은 사진이므로 방문자는 스탑 내에서 스크롤하거나, 텍스트를 선택하거나, 선택한 경로를 벗어날 수 없습니다. drag 단계는 핫스팟이 클릭될 때 재생됩니다. 새 탭을 여는 링크를 따르지 않으며, iframe 내부에 접근할 수 없으며, 파일을 업로드할 수 없습니다. 기본 alert() 및 confirm() 상자는 자동으로 수락되며 나타나지 않습니다. 흐름이 이 중 하나에 의존하는 경우, 그렇게 말하고 작동하는 부분을 빌드하세요.

오류 메시지가 설명하지 않는 방식으로 실패할 경우 references/troubleshooting.md를 참조하세요.