Record & Replay (브라우저 + 데스크톱)
Record & Replay를 사용하면 에이전트가 사용자가 시연하는 워크플로우를 학습하고 재사용 가능한 스킬로 변환할 수 있습니다. 두 가지 모드:
- 브라우저 모드 (기본값, 가장 풍부한 증거): 헤드 Playwright 브라우저(가능하면 시스템 Google Chrome 사용)가 모든 사용자 동작을 여러 선택자 후보와 함께
events.jsonl에 기록하고, Playwright 트레이스 청크(trace-NNN.zip)를 생성합니다. macOS, Windows, Linux에서 작동합니다. - 데스크톱 모드 (네이티브 앱): 가벼운 단일 프로세스 레코더(pynput)가 전역 마우스/키보드 이벤트, 활성 창 변경, 클릭 순간 스크린샷 및 각 클릭의 접근성 대상(macOS AX, Windows UI Automation)을
desktop-events.jsonl+screens/에 캡처하고, 비밀번호 필드는 마스킹 처리합니다(Codex와 동등: Codex도 비디오가 아닌 이벤트/컨텍스트 스트림을 기록하며, CPU ~1-3% 사용). macOS, Windows, Linux(X11)에서 작동합니다. "데스크톱 녹화" 참조.
워크플로우가 브라우저 전용일 때는 브라우저 모드를 선택하세요. 의미론적 선택자가 데스크톱 좌표보다 훨씬 더 나은 스킬을 생성합니다.
설정 (한 번만)
cd ~/.agents/skills/record-and-replay
node setup.mjs # npm install + (Chrome이 없을 경우에만 Chromium 다운로드) + 자체 테스트
node install.mjs # 에이전트 스킬 디렉토리에 링크 (macOS/Linux는 심볼릭 링크, Windows는 정션)
playwright npm 패키지를 설치합니다. Google Chrome이 설치된 경우 브라우저를 다운로드하지 않습니다(레코더는 channel: 'chrome' 사용). 그렇지 않으면 스크립트가 Chromium을 다운로드합니다. 두 스크립트 모두 크로스 플랫폼(Node)입니다.
녹화 워크플로우
-
시작하기 전에 사용자에게 캡처하고 싶지 않은 창, 파일, 대화를 닫고, 저장하고 싶지 않은 비밀을 입력하지 말라고 알리세요. 사용자가 준비되었을 때만 백그라운드에서 분리되어 레코더를 시작하세요. 출력 디렉토리를 미리 알 수 있도록 항상
--name <slug>를 전달하세요:cd ~/.agents/skills/record-and-replay # macOS / Linux: nohup node scripts/recorder.mjs --minutes 30 --name <slug> [--url <startUrl>] \ > ~/.agents/recordings/recorder.log 2>&1 & # Windows (PowerShell): Start-Process node -WindowStyle Hidden -ArgumentList "scripts/recorder.mjs","--minutes","30","--name","<slug>"네이티브 백그라운드 실행 기능(예: Claude Code의 Bash
run_in_background)이 있는 에이전트는 이를 대신 사용할 수 있습니다. 출력은~/.agents/recordings/<slug>/로 이동합니다. -
시작 확인을 한 번(약 2-3초 후, 폴링 루프가 아닌 단일 확인):
~/.agents/recordings/<slug>/session.json이"status": "recording"과 함께 존재하는지 확인합니다(레코더는 성공 시 로그에{"status":"recording",...}줄도 출력합니다). 확인이 실패하면 로그를 읽으세요:recording_already_active(종료 코드 2)는 다른 녹화가 잠금을 보유하고 있음을 의미합니다.launch_failed또는 누락된 모듈 오류는 설정이 필요함을 의미합니다. 사용자에게 녹화가 시작되었다고 알리지 않고 실제 문제를 보고하세요. -
시작 확인 후에는 루프에서 sleep, poll 또는 wait하지 마세요. 턴을 종료하세요: 사용자에게 녹화가 시작되었고, 시간 제한이 무엇이며, 작은 부동 제어 창(오른쪽 아래, Codex의 녹화 제어와 유사)에 일시 중지/재개, 중지 및 폐기(두 번 탭하여 확인) 버튼이 있는 타이머가 있음을 알리세요. 일시 중지되면 아무것도 캡처되지 않습니다(이벤트와 트레이스 모두 중지). 사용자가 실수로 제어 창을 닫으면 자동으로 다시 열립니다. 메인 브라우저 창을 닫으면 세션도 종료됩니다(Cmd+Q로 브라우저를 완전히 종료하면 마지막 1분의 트레이스가 손실될 수 있으므로 피하세요). 시작 시
--badge를 전달하여 제어 창 대신 페이지 내 배지를 사용하세요(이국적인 환경을 위한 대체). -
일시 중지/재개(사용자가 일시 중지를 요청하거나 민감한 구간을 건너뛰어야 하는 경우):
touch ~/.agents/recordings/<slug>/PAUSE는 2초 이내에 일시 중지합니다. 파일을 삭제하면 재개됩니다. 제어 창 버튼과 PAUSE 파일은 동기화 상태를 유지합니다.session.json은 현재paused상태를 전달합니다. 일시 중지된 간격은events.jsonl에paused/resumed마커로 나타나며 트레이스에는 없습니다. -
사용자가 완료했다고 말하면:
- 프로세스가 아직 실행 중이면 정상적으로 중지합니다:
touch ~/.agents/recordings/<slug>/STOP(레코더가 2초 이내에 감지하고 마무리합니다). session.json을 읽으세요 —status: "recording"은 아직 라이브 상태임을 의미합니다."completed"는 출력이 최종임을 의미합니다."discarded"는 사용자가 폐기를 눌렀음을 의미합니다 — 증거 파일이 삭제되었으므로 이를 인정하고 절대 스킬을 만들지 마세요.endReason은user_stopped,user_discarded,browser_closed,stop_file,time_limit,signal,event_limit중 하나입니다.- 응답하기 전에 캡처된 이벤트를 검사하세요: 간결한 타임라인을 위해
node scripts/summarize.mjs <outDir>를 실행한 다음, 세부 정보가 필요한 단계에 대해events.jsonl을 직접 읽으세요.
- 프로세스가 아직 실행 중이면 정상적으로 중지합니다:
-
취소는 endReason이 아닌 내용으로 정의됩니다: 녹화에
kind: "dom"이벤트가 거의 없거나 전혀 없는 경우(endReason이 무엇이든) 취소된 것으로 처리하세요. 인정하고 스킬을 생성하거나 업데이트하지 마세요. -
녹화에 재사용 가능한 워크플로우를 식별하기에 충분한 정보가 포함된 경우, 기본적으로 해당 스킬을 생성하거나 개선하세요 — 사용자가 명시적으로 요청하지 않더라도 마찬가지입니다. 요약 또는 재생 계획만 생성한 후 멈추지 마세요. 아래 "녹화에서 스킬 생성"을 따르세요 — 짧은 설명 라운드로 시작합니다.
-
녹화가 너무 얇거나 모호하여 워크플로우를 식별할 수 없는 경우, 추측하지 마세요. 무엇이 불분명한지 설명하고 사용자에게 누락된 부분을 물어보세요.
동시 녹화
한 번에 하나의 녹화만 활성화될 수 있습니다(잠금 파일 ~/.agents/recordings/.lock). 레코더가 recording_already_active로 종료되면 다른 강제 시작을 하지 말고, 사용자에게 이미 녹화가 진행 중임을 알리고 녹화를 사용할지 아니면 먼저 중지할지 물어보세요. 동일한 --name으로 다시 시작해도 안전합니다: 이전 events.jsonl은 타임스탬프가 있는 .bak으로 보존되며, 추가되지 않습니다.
이벤트 해석
events.jsonl이 기본 증거입니다. session.json은 타이밍/경로만 제공합니다. trace-NNN.zip 청크는 DOM 수준의 실측 자료입니다(npx playwright show-trace <outDir>/trace-*.zip; session.json의 traceChunks가 순서대로 나열). 트레이스는 기본적으로 라이트 모드입니다 — 작업당 전체 DOM 스냅샷이지만 연속 스크린샷은 없습니다(CPU를 낮게 유지). 사용자가 픽셀 완벽한 시각적 증거를 원할 때는 --trace full로 시작하고, 절대 최소 용량을 원할 때는 --trace off로 시작하세요.
각 줄은 하나의 이벤트입니다: {seq, t (ms since start), kind, type, url, ...}.
kind: "page"— 탐색, 다운로드, 대화 상자, 탭 열기/닫기. 탐색은 워크플로우를 단계로 분할합니다.kind: "dom"— 사용자 작업.target.selectors는 여러 선택자 후보를 전달합니다:testId,role({role, name}),id,nameAttr,text,css. 재생 코드를 생성할 때는 이 순서대로 선호하세요.css는 최후의 수단입니다.type: "input"이벤트는 디바운스됩니다 — 필드당 최종 값이 포함된 하나의 이벤트(blur, Enter, 변경 및 양식 제출 시 플러시). 비밀번호/신용카드/OTP와 유사한 필드(영어 및 터키어 이름: password, parola, şifre, kart, kimlik…)는 미리 마스킹되어 도착합니다(***MASKED***,masked: true).selection및copy이벤트는 사용자가 작업 중이던 내용을 보여줍니다. 사용자가 "이것" 또는 "내가 선택한 것"을 언급할 때 가장 좋은 단서가 되는 경우가 많습니다. 비밀스러워 보이는 선택(OTP, API 키, 토큰)은 마스킹됩니다.paste이벤트는 길이/단어 수만 전달하고 내용은 절대 전달하지 않습니다.- 민감한 데이터: 마스킹은 휴리스틱이며 보장되지 않습니다 — 그리고
events.jsonl에만 적용됩니다. 트레이스 청크는 마스킹되지 않습니다: DOM 스냅샷에는 원시 입력 값(JSONL에서 마스킹된 값 포함)이 포함되어 있으며, 스크린샷은 화면에 보이는 모든 것(노출된 토큰, 2FA 코드, 잔액)을 캡처합니다. 전체~/.agents/recordings/<name>/디렉토리를 민감한 것으로 취급하세요: 로컬에서만 검사하고, 절대 업로드하거나 커밋하지 마며, 요약이나 생성된 스킬에서 리터럴 비밀을 인용하지 마세요(자리 표시자 또는 일반 설명 사용).
녹화에서 스킬 생성
글을 쓰기 전에 references/skill-authoring.md를 읽으세요: 질문 은행, 프론트매터 제한, SKILL.md 뼈대, 번들 스크립트 규칙 및 품질 체크리스트가 있습니다. 환경에 skill-creator 스킬이 있는 경우 해당 지침도 적용됩니다. 단순한 Markdown 실행 설명서가 아닌 실제 검색 가능한 스킬(SKILL.md 폴더)을 생성하세요.
이 체크리스트를 복사하여 완료 표시하세요:
- [ ] 1. 녹화 요약; 모든 간격(결정, 마스킹된 구간, 사각 지대) 기록
- [ ] 2. 명확히 하기: 하나의 메시지, 최대 6개의 질문, 간격에 대해서만
- [ ] 3. 이 워크플로우를 다루는 기존 스킬 확인 → 중복 대신 업데이트
- [ ] 4. 스킬 + evals/evals.json 작성(녹화는 테스트 케이스 1)
- [ ] 5. 검증: node scripts/export-skill.mjs <skillDir> --check → 오류 수정, 재실행
- [ ] 6. 트리거 확인 + 드라이 런 제공; 수정 사항을 반영하여 metadata.version 증가
- [ ] 7. claude.ai ZIP 내보내기 제공
2단계 — 쓰기 전에 명확히 하세요. 오디오는 없습니다. 녹화는 무엇이 일어났는지 보여주지만, 이유는 알려주지 않습니다. 녹화에서 보여주는 내용에 대해 답변한 다음, 사용자에게 한 번, 단일 메시지에 최대 6개의 질문으로 보여줄 수 없는 내용을 물어보세요: 결과와 어떻게 작동했는지 알 수 있는 방법, 실행 간에 달라지는 값, 특정 순간에 X를 선택한 이유, 어떤 동작이 우회였는지, 스킬을 트리거하기 위해 무엇이라고 말할지(그리고 무엇이 안 되는지), 어떤 동작이 확인이 필요한지. 의미하는 순간을 인용하세요("02:14에서 날짜 필터를 지웠는데 — 왜요?"). 구조화된 질문 도구가 있으면 사용하고, 없으면 일반 채팅을 사용하세요. 녹화와 사용자의 요청이 모든 것을 이미 답변하는 경우에만 라운드를 건너뛰고 그렇게 말하세요.
작성 규칙:
- 녹화를 픽셀 단위로 재생할 스크립트가 아닌 사용자의 의도된 결과에 대한 증거로 취급하세요. 커넥터/API/CLI/MCP 도구가 동일한 결과를 의미론적으로 달성할 수 있는 경우(캘린더 이벤트 생성, PR 열기, 메시지 게시) UI 자동화보다 선호하세요.
- UI 재생이 실제로 필요한 경우
scripts/replay-template.mjs에서 Playwright 스크립트를 생성하세요: 의미론적 로케이터(getByTestId>getByRole>getByLabel>getByText), 각 중요한 작업 후 검증 단계, 환경 변수에서 가져온 비밀. 이벤트 스트림이 더 나은 대상을 제공하지 않는 한 원시 좌표를 사용하지 마세요. - 데스크톱 단계는 캡처된 대상(역할 + 이름 + 창, 예: "Invoice — Acme"의 버튼 "저장")의 이름을 지정하여 접근성 트리 도구가 찾을 수 있도록 합니다. 대상이 캡처되지 않은 경우에만 좌표를 사용합니다.
- 레코더의 영구 프로필(
~/.agents/recordings/.browser-profile)은 세션 간에 로그인을 유지하므로, 생성된 스킬에는 일반적으로 로그인 단계가 필요하지 않습니다. 보안: 이 디렉토리는 라이브 인증된 세션 자료(쿠키/localStorage; Playwright가 모의 키체인으로 Chrome을 시작하므로 일반 텍스트 자격 증명으로 취급)를 보유합니다. 절대 암호화되지 않은 상태로 커밋, 공유 또는 백업하지 마세요. 그리고 이를 재사용하는 모든 재생 스킬은 사용자의 로그인으로 실행된다는 점을 기억하세요. 신뢰할 수 없거나 민감도가 높은 사이트의 녹화의 경우 일회용 프로필(--out+ 임시 프로필)을 선호하거나 나중에 프로필을 지우세요. - 새 스킬을
~/.agents/skills/<skill-name>/(폴더 이름 =name, 케밥 케이스)에 저장하고 에이전트 스킬 디렉토리에 심볼릭 링크(install.mjs패턴 참조)하여 이 머신의 모든 에이전트가 사용할 수 있도록 하세요. - 변하는 것(날짜, 금액, 이름)은 매개변수화하고, 변하지 않는 것은 하드 코딩하세요. 생성된 SKILL.md에 워크플로우의 목적과 검증 기준을 명시하세요. 비밀 또는 마스킹된 값을 스킬에 절대 복사하지 마세요.
claude.ai 내보내기(제공, 요청 시 실행): node scripts/export-skill.mjs ~/.agents/skills/<name>는 ~/.agents/exports/<name>.zip을 작성합니다(ZIP 루트에 폴더, README, 평가, 캐시 및 녹화 증거는 제외되고 아카이브는 성공 전에 다시 읽힘). 스킬이 Claude Code 전용 프론트매터(disable-model-invocation, …)를 사용하는 경우 --strip-cc-keys를 추가하세요. 사용자에게 파일 위치와 사용자 지정 › 스킬 › + › 스킬 업로드(코드 실행 활성화되어야 함)에서 업로드된다고 알리세요.
데스크톱 녹화 (macOS, Windows, Linux/X11)
설정: node setup.mjs (requirements-desktop.txt에서 최소 .venv-desktop Python 환경 생성 — pynput+mss+pillow, Windows의 경우 comtypes, ~50 MB, uv 필요).
권한 (macOS): 레코더는 이를 사전 점검하고 기계 판독 가능한 상태를 보고하므로 추측하지 마세요. start는 permissions: {inputMonitoring, screenRecording, grantTo}와 함께 누락된 것이 있을 때 warning을 출력하고, 자동으로 시스템 대화 상자를 열고 올바른 설정 창을 엽니다(--no-permission-prompt는 이를 비활성화하고, node scripts/desktop-record.mjs permissions는 요청 시 실행). grantTo는 사용자가 권한을 부여해야 하는 앱의 이름을 지정합니다 — TCC 권한은 Python이 아닌 에이전트를 호스팅하는 .app 번들에 바인딩되며, 해당 앱은 이후에 다시 시작해야 합니다. grantTo를 그대로 전달하세요. 사용자에게 "터미널에 권한을 부여하세요"라고 말하는 것은 일반적으로 잘못된 것입니다. Windows는 권한이나 관리자 권한이 필요하지 않습니다.
엔진은 단일 프로세스 레코더(~0-3% CPU)입니다: 입력 이벤트 스트림 + 활성 창/제목 변경 + 각 클릭 시 절반 해상도 JPEG(최대 1/700ms) → desktop-events.jsonl + screens/. 각 클릭은 또한 커서 아래 요소의 접근성 설명(kind: "target" 줄, forSeq로 클릭에 결합)을 전달합니다: role, name, automationId, window, ancestors — 단순 좌표가 아닌 Button "Save"와 같은 의미론적 대상(macOS AX, Windows UI Automation, Linux에서는 없음). 타이핑은 각 버스트의 최종 값을 보유한 type: "text" 이벤트로 도착합니다(백스페이스 수정 적용됨). 단축키 및 특수 키는 press 이벤트(ctrl+c, enter)로 도착합니다. 스크린샷, 대상 쿼리 및 포커스 확인은 작업자 스레드에서 실행되며 입력 콜백에서는 절대 실행되지 않습니다. 느린 콜백은 macOS 이벤트 탭이 비활성화되고 Windows 후크가 자동으로 제거됩니다(레코더는 후자를 감시하고 후크를 다시 설치합니다).
이것은 Codex와 동등한 수준입니다: Codex의 Record & Replay도 기록합니다.