Browser Walkthrough (headed 모드 대화형 진행) Skill

Browser Walkthrough (headed 모드 대화형 진행)

사용자가 열어둔 headed 브라우저에 attach해서 같은 화면을 보며 한 스텝씩 진행한다. 명령어 전체 레퍼런스는 playwright-cli skill 참조 — 이 skill의 핵심은 대화 프로토콜이다. 사전 조건 — playwright-cli 스킬 필요 (외부 플러그인 또는 user-level 설치, README 참조).

사용자 응답 해석 (최우선)

| 입력 | 행동 | |---|---| | 다음 / next / 진행 / ok / 응 | 직전 제안 액션 실행 → snapshot → 다음 스텝 요약·대기 | | 뒤로 | go-back | | 스킵 / 건너뛰기 | 현재 스텝 건너뛰고 다음 | | 잠깐 / 멈춰 / wait / 대기 | 아무 액션도 하지 않고 대기 (사용자 수동 조작 중) | | 구체적 값 (스테판초 랩스, 010-...) | 직전에 물어본 필드에 fill | | 질문 (이거 뭐임?) | 액션 금지. 답변만 하고 다시 대기 | | ok 제출 / 결제 진행 / 최종 확인 | 위험 액션 실행 (아래 게이트) | | 완료 / 끝 | 후속 액션 아이템을 기한 포함 체크리스트로 요약 |

Step Loop

playwright-cli -s=<name> snapshot — 현재 화면의 DOM(yaml, ref 포함) 확보
2-5줄 요약 — 무슨 페이지이고 어떤 선택지·필드가 있는지
다음 액션 제안 or 필요한 입력값 질문
사용자 응답 대기 → 위 표대로 해석

snapshot이 비거나 ref가 안 잡히면 iframe 가능성 → iframe-handling.md.

Bootstrap

playwright-cli list                                                          # 기존 세션 확인
playwright-cli -s=<name> open <url> --browser=chrome --persistent --headed  # 없으면 headed 새 세션
playwright-cli -s=<name> attach                                              # 이미 열린 브라우저면 attach

세션 이름은 작업 도메인 (hometax, gov24, coupang). 이후 모든 명령에 -s=<name> 필수.

위험 액션 게이트 (필수)

최종 제출·결제·삭제·취소 같은 되돌릴 수 없는 액션은 다음만으로 실행하지 않는다. 실행 전에:

[ ] 체크포인트 요약 표로 지금까지 입력한 핵심 값 재표시 (금액·날짜·상호·접수번호 등)
[ ] ok 제출 / 결제 진행 / 최종 확인 중 어떤 키워드가 필요한지 명시
[ ] 사용자가 그 키워드를 말할 때까지 대기

긴 폼(5-6단계 이상)은 페이지 전환 직전마다 채운 값을 짧은 표로 재요약해 스텝 드리프트 방지.

민감값 · 한국 사이트 특이사항

주민번호·인증서 비밀번호·계좌번호·카드번호는 응답에 그대로 에코 금지. 인증서 비번 등은 사용자가 직접 입력하게 하고 잠깐 대기.
사용자가 브라우저 확장으로 민감값을 마스킹 중일 수 있다 — screenshot의 마스킹에 혼동하지 말 것.
홈택스·금융사: 실제 컨텐츠가 iframe 안 → iframe-handling.md
IPINSIDE / Veraport / MagicLine: 보안프로그램 게이트. playwright로 우회 불가 — 사용자 수동 설치 후 새로고침
다운로드: playwright가 임시폴더로 가로챔 → downloads.md
공동인증서 팝업: 사용자가 직접 비번 입력. Claude는 잠깐 모드

Guide 모드 — 사용자가 직접 클릭하게 하기

기본은 Claude가 click/fill. 민감 입력·학습 목적·최종 버튼은 highlight만 하고 사용자가 직접 조작.

scripts/guide-launcher.sh <mode> "<title>" "<ref|heading|desc>" [more...]   # mode = seq | opt | one

| 상황 | 권장 방식 | |---|---| | 단순 폼 (제목·내용·날짜 등 비민감) | Claude fill | | 민감값 (아이디/비번, 카드번호, 전화번호) | highlight → 사용자 직접 | | 체크박스·라디오 선택 | Claude click (확인 후) | | 최종 제출·결제·삭제 | highlight → ok 제출에 Claude가 최종 click | | 인증서 로그인·OTP | 기본 대기 (잠깐) |

모드·spec 포맷·렌더 구성·예시는 guide-mode.md.

기타 명령

playwright-cli -s=<name> dialog-accept   # snapshot에 dialog 키워드 있으면 먼저 accept/dismiss
playwright-cli -s=<name> tab-list        # 팝업이 떴으면 tab-list부터, tab-select <n>으로 전환
playwright-cli -s=<name> fill e133 "0" && playwright-cli -s=<name> click e174   # 확정된 필드는 일괄 체이닝
playwright-cli -s=<name> close           # 종료 — 창만 닫기. delete-data는 프로필까지 삭제

Screenshot

snapshot 우선, screenshot은 보조. 찍으면 즉시 긴 변 1568px로 리사이즈 후 Read:

playwright-cli -s=<name> screenshot --filename=s.png && sips -Z 1568 .playwright-cli/s.png --out .playwright-cli/s-small.png >/dev/null

근거·예외(작은 폰트, PDF 뷰어)는 screenshot-resolution.md.

Anti-patterns

WRONG: 사용자 질문에 답하면서 다음 액션까지 실행. RIGHT: 답만 하고 대기.
WRONG: 다음에 최종 제출/결제 click. RIGHT: 체크포인트 표 + 위험 키워드 대기.

전체 예시 대화는 example-flow.md.

Agent Skills: Browser Walkthrough (headed 모드 대화형 진행)

Install this agent skill to your local

Skill Files