Playwright 스크립트가 브라우저 스킬(Browser Skill)로 전환되어야 하는 시점

대부분의 브라우저 자동화는 단순한 방식으로 시작됩니다.

열어야 할 페이지가 있고.
클릭해야 할 버튼이 있고.
확인해야 할 대시보드가 있고.
내보내야 할 보고서가 있고.
저장해야 할 스크린샷이 있습니다.

그래서 여러분은 Playwright 스크립트를 작성합니다.

import { chromium } from "playwright";

const browser = await chromium.launch({ headless: false });
...

작은 작업에는 이 방식이 완벽합니다.

문제는 나중에, 스크립트가 코드에 보이지 않는 요소들에 의존하게 될 때 시작됩니다.

어떤 계정 (account) 으로 로그인했는가?
어떤 브라우저 프로필 (browser profile) 이 사용되었는가?
어떤 프록시 (proxy) 가 활성화되었는가?
세션이 새로 생성된 것인가, 아니면 어제로부터 복구된 것인가?
스크립트가 폼을 제출할 수 있는 권한이 있는가, 아니면 페이지를 검사하기만 해야 하는가?
인증 프롬프트가 나타나면 어떻게 해야 하는가?

그 시점에서 자동화는 더 이상 단순한 스크립트가 아닙니다.

그것은 워크플로 (workflow) 가 되었습니다.

그리고 많은 팀에서, 그 워크플로는 브라우저 스킬 (browser skill) 이 되어야 합니다.

워크플로가 무언가를 기억하기 시작할 때까지는 스크립트로 충분하다

단순한 스크립트는 브라우저를 제어합니다.

진정한 워크플로는 컨텍스트 (context) 를 기억합니다.

그 컨텍스트에는 로그인 상태 (login state), 쿠키 (cookies), 로컬 스토리지 (local storage), 확장 프로그램 상태 (extension state), 프록시 지역 (proxy region), 계정 소유권 (account ownership), 이전 실패 기록 (previous failures), 검토 규칙 (review rules), 그리고 출력 증거 (output evidence) 가 포함될 수 있습니다.

이것들은 사소한 구현 세부 사항이 아닙니다.

이 요소들은 자동화가 실행하기에 안전한지, 반복 가능한지, 그리고 원작자 이외의 다른 사람이 이해할 수 있는지를 결정합니다.

다음과 같은 스크립트는 무해해 보일 수 있습니다:

await page.goto("https://example.com/account");
await page.click("text=Settings");
await page.screenshot({ path: "settings.png" });

하지만 코드는 운영상의 질문들에 답하지 못합니다.

이것은 어떤 계정인가?
이 계정은 설정을 열 수 있는 권한이 있는가?
현재 IP가 이 계정에 예상되는 IP인가?
보안 페이지가 나타나면 스크립트를 중단해야 하는가?
증거는 어디에 저장되어야 하는가?
결과를 누가 검토하는가?

이러한 질문들이 중요해질 때, 브라우저 작업은 느슨한 스크립트 파일보다 더 강력한 구조를 필요로 합니다.

첫 번째 신호는 반복되는 수동 설정입니다

첫 번째 신호는 대개 기술적인 문제가 아닙니다.

사람의 문제입니다.

스크립트를 실행하기 전에 누군가가 브라우저를 수동으로 준비해야 합니다.

그들은 적절한 프로필을 엽니다.
프록시 (Proxy)를 확인합니다.
계정이 여전히 로그인되어 있는지 확인합니다.
확장 프로그램 (Extension)이 설치되어 있는지 확인합니다.
헤드리스 모드 (Headless mode) 대신 가시 모드 (Visible mode)를 선택합니다.
어떤 계정을 사용해야 하는지 설명하는 메모를 Slack에 붙여넣습니다.

그러한 설정은 자동화와 별개의 것이 아닙니다.

그것은 자동화의 일부입니다.

만약 누군가가 수동으로 브라우저를 준비해야만 스크립트가 작동한다면, 그 준비 과정은 워크플로 (Workflow)의 일부로 선언되어야 합니다.

브라우저 스킬 (Browser skill)은 설정을 명시적으로 만들어야 합니다.

{
  "requires": {
    "logged_in_session": true,
...

이것은 자동화를 더 복잡하게 만드는 것이 아닙니다.

실제 복잡성을 가시화하는 것입니다.

두 번째 신호는 계정 컨텍스트 (Account context)입니다

하나의 스크립트가 여러 계정에 걸쳐 사용될 때 브라우저 자동화는 훨씬 더 어려워집니다.

공개적인 스크래핑 (Scraping) 스크립트는 종종 상태가 없는 (Stateless) 방식일 수 있습니다.

하지만 계정 인지형 (Account-aware) 작업은 그럴 수 없습니다.

스크립트가 어떤 계정, 프로필, 프록시, 그리고 지역이 서로 연결되어 있는지 알아야 하는 시점이 되면, 해당 값들은 파일 이름, 주석, 스프레드시트 또는 기억 속에 머물러서는 안 됩니다.

그것들은 구조화된 입력값 (Structured inputs)이 되어야 합니다.

{
  "account_id": "acct_us_018",
  "profile_id": "profile_us_018",
...

이것은 스크립트가 스킬로 전환되어야 한다는 가장 명확한 신호 중 하나입니다.

스킬은 단순히 "이 페이지를 여세요"라고 말하지 않습니다.

다음과 같이 말합니다:

이 계정을 사용하세요.
이 브라우저 프로필을 사용하세요.
이 프록시 컨텍스트 (Proxy context)를 사용하세요.
허용된 작업을 실행하세요.
신원 경계 (Identity boundary)가 잘못된 것처럼 보이면 중단하세요.
예측 가능한 위치에 증거를 저장하세요.

이는 특히 **다중 계정 자동화 (Multi-account automation)**에서 매우 중요합니다.

계정 컨텍스트가 없다면, 동일한 스크립트의 두 실행은 완전히 다른 리스크 프로필 (Risk profiles)을 생성할 수 있습니다.

한 실행은 해롭지 않은 대시보드 확인일 수 있습니다.

다른 실행은 잘못된 계정 내에서의 민감한 작업일 수 있습니다.

코드는 동일할 수 있습니다.

컨텍스트는 그렇지 않습니다.

세 번째 신호는 실패 처리 (Failure Handling)입니다

일회성 스크립트는 보통 실패할 때 명확하게 드러납니다.

에러를 던지고, 종료되며, 운영자가 무슨 일이 일어났는지 파악하도록 남겨둡니다.

로컬 실험(Local experiments)을 위해서는 이 정도면 충분합니다.

하지만 반복되는 브라우저 워크플로우 (Browser workflows)에는 충분하지 않습니다.

재사용 가능한 브라우저 스킬 (Browser skill)은 어떤 실패가 **재시도 가능 (Retryable)**한지, 어떤 실패가 **강제 중단 (Hard stop)**을 요구하는지, 그리고 어떤 실패가 **사람의 검토 (Human review)**를 필요로 하는지 알고 있어야 합니다.

{
  "retry_on": [
    "timeout",
...

이 지점에서 많은 자동화 프로젝트가 조용히 취약해지기 시작합니다.

팀은 계속해서 try/catch 블록을 추가합니다.

그다음에는 스크린샷을 추가합니다.

그다음에는 재시도 (Retries)를 추가합니다.

그다음에는 누군가에게 알림을 보내는 메시지를 추가합니다.

그다음에는 로그인 페이지, 캡차 (Captchas), 차단된 계정, 변경된 셀렉터 (Selectors), 그리고 예기치 않은 리다이렉트 (Redirects)를 위한 특수 사례들을 추가합니다.

결국, 스크립트는 더 이상 단순히 브라우저를 자동화하는 것이 아니게 됩니다.

그것은 운영 정책 (Operational policy)을 담고 있습니다.

그 정책은 명확하게 선언되어야 합니다.

브라우저 스킬은 실패 동작을 우발적인 예외 처리 (Exception handling)의 더미가 아니라, 작업 정의 (Task definition)의 일부로 만듭니다.

네 번째 신호는 팀에 의한 공유 사용입니다

개인용 스크립트는 개인의 기억에 의존할 수 있습니다.

팀 워크플로우 (Team workflow)는 그럴 수 없습니다.

만약 단 한 명의 개발자만이 스크립트를 실행하는 방법을 안다면, 그것은 진정으로 재사용 가능한 것이 아닙니다.

누군가가 다음과 같은 질문을 던질 때 이 사실은 명확해집니다:

어떤 프로필 (Profile)을 사용해야 하나요?
이것을 헤드리스 (Headless)로 실행할 수 있나요?
성공했다는 것은 어떤 상태를 의미하나요?
스크린샷은 어디에 저장되나요?
이 작업이 제출 (Submit) 버튼을 클릭할 수 있나요?
출력 결과는 누가 확인하나요?
로그인이 만료되면 어떻게 해야 하나요?

만약 답이 누군가의 머릿속에만 있다면, 그 자동화는 인수인계 (Handoff) 문제를 안고 있는 것입니다.

브라우저 스킬은 다음과 같은 부분들을 명확하게 만들어야 합니다:

입력값 (Inputs)
허용된 동작 (Allowed actions)
차단된 동작 (Blocked actions)
...

이것은 관료주의가 아닙니다.

브라우저 자동화가 반복적인 사용에 충분할 만큼 안전해지는 방법입니다.

팀이 보유한 계정, 프로필, 프록시 (Proxies), 그리고 운영자 (Operators)가 많아질수록, 비공식적인 지식에 의존할 수는 점점 더 줄어듭니다.

브라우저 스킬은 더 큰 스크립트가 아닙니다

브라우저 스킬은 단순히 더 긴 Playwright 파일이 아닙니다.

그것은 입력 (inputs), 규칙 (rules), 출력 (outputs), 그리고 **경계 (boundaries)**를 가진 재사용 가능한 작업 (operation)입니다.

계층을 분리하는 유용한 방법은 다음과 같습니다:

스크립트 (Script):
브라우저를 제어합니다.

...

이러한 구분은 매우 중요합니다.

스크립트는 다음과 같이 말할 수 있습니다:

await page.click("text=Export");

반면, 스킬 (skill)은 내보내기 (exporting)가 허용되는지, 어떤 계정이 사용되는지, 파일이 어디로 가는지, 어떤 증거 (evidence)가 저장되는지, 그리고 언제 작업을 중단해야 하는지를 정의해야 합니다.

많은 팀에게 부족한 계층은 또 다른 자동화 라이브러리가 아닙니다.

그것은 브라우저 작업 주위의 운영 계층 (operating layer)입니다.

그 시점에 도달하면, 많은 팀은 단순한 스크립트 폴더 이상의 것이 필요합니다. 그들은 프로필, 프록시 (proxies), 작업 규칙, 그리고 실행 로그가 서로 연결되어 유지되는 멀티 계정 팀을 위한 브라우저 자동화 워크스페이스 (a browser automation workspace for multi-account teams)가 필요합니다.

목표는 모든 작은 스크립트를 엔터프라이즈급 (enterprise-grade)으로 만드는 것이 아닙니다.

목표는 스크립트가 검토 불가능한 자동화 부채 (automation debt)가 되기 전에, 적절한 스크립트를 재사용 가능한 스킬로 승격시키는 것입니다.

최소한의 브라우저 스킬 템플릿

브라우저 스킬이 거대한 프레임워크 (framework)로 시작할 필요는 없습니다.

작은 템플릿만으로도 충분한 경우가 많습니다.

{
  "skill_name": "check_account_dashboard",
  "description": "계정 대시보드를 열고, 상태를 점검하며, 증거를 캡처하고, 요약을 작성합니다.",
...

이 템플릿은 중요한 역할을 수행합니다.

브라우저 제어 (browser control)를 워크플로우 의도 (workflow intent)로부터 분리합니다.

Playwright 코드는 여전히 실제 페이지 동작을 수행할 수 있습니다.

하지만 스킬 정의는 해당 작업이 무엇을 할 수 있는지, 무엇을 해서는 안 되는지, 그리고 어떤 증거를 남겨야 하는지를 설명합니다.

이는 자동화를 검토하기 더 쉽게 만듭니다.

또한 AI 에이전트 (AI agent) 또는 오케스트레이션 계층 (orchestration layer)이 작업을 안전하게 호출할 수 있도록 해줍니다.

간단한 Playwright 래퍼 (wrapper)만으로도 충분할 수 있습니다

첫날부터 모든 것을 다시 구축할 필요는 없습니다.

실질적인 시작점은 Playwright 함수를 스킬 러너 (skill runner)로 감싸는 (wrap) 것입니다.

async function runDashboardCheck({ page, account, evidence }) {
  await page.goto(account.targetUrl);

...

그다음 운영 규칙(operational rules)을 함수 외부로 분리하세요.

{
  "account": {
    "id": "acct_us_018",
...

이것은 여전히 단순합니다.

하지만 모든 것이 안전하다고 암묵적으로 가정하는 스크립트보다는 이미 더 나은 상태입니다.

러너(Runner)는 입력을 확인할 수 있습니다.
스킬(Skill)은 구조화된 결과(structured results)를 반환할 수 있습니다.
운영자(Operator)는 증거(evidence)를 검토할 수 있습니다.
팀은 동일한 작업을 여러 계정에 걸쳐 재사용할 수 있습니다.

이것이 스크립트에서 스킬로 나아가는 경로입니다.

스크립트로 남아있어야 하는 경우

모든 자동화 작업이 스킬이 될 필요는 없습니다.

어떤 스크립트들은 단순하게 유지되어야 합니다.

다음과 같은 경우에는 보통 스크립트만으로도 충분합니다:

• 페이지가 공개되어 있는 경우
• 로그인 상태(login state)가 필요하지 않은 경우
• 계정 신원(account identity)이 관여되지 않는 경우
• 프록시(proxy)나 지역 매핑(region mapping)이 중요하지 않은 경우
• 민감한 동작(sensitive action)이 트리거될 수 없는 경우
• 작업이 결정론적(deterministic)인 경우
• 출력이 로컬에서만 사용되는 경우
• 스크립트를 한 사람이 소유하고 사용하는 경우
• 실패 시 검토 증거(review evidence)가 필요하지 않은 경우

예를 들어, 단순한 공개 페이지의 상태 확인(health check)은 스킬 정의가 필요하지 않을 수 있습니다.

const response = await page.goto("https://example.com/status");
console.log(response.status());

모든 작은 스크립트를 공식적인 워크플로(workflow)로 전환하는 것은 그 자체로 오버헤드(overhead)를 발생시킵니다.

핵심은 브라우저 자동화(browser automation)를 과도하게 설계(over-engineer)하는 것이 아닙니다.

핵심은 코드베이스가 아직 인정하지 않았더라도, 스크립트가 이미 워크플로가 된 시점을 알아차리는 것입니다.

스킬이 되어야 하는 경우

다음 항목 중 여러 개가 해당된다면 스크립트는 브라우저 스킬(browser skill)이 되어야 합니다:

• 동일한 작업이 매일 또는 매주 실행되는 경우
• 작업이 여러 계정(account)에 걸쳐 실행되는 경우
• 각 계정마다 전용 브라우저 프로필(browser profile)이 있는 경우
• 각 프로필에 프록시(proxy) 또는 특정 지역(region) 요구사항이 있는 경우
• 작업 중 로그인, 인증 또는 보안 화면을 마주칠 수 있는 경우
• 차단되어야 하는 동작(actions)이 포함된 작업인 경우
• 사람이 출력 결과(output)를 검토해야 할 수도 있는 경우
• 증거로서 스크린샷(screenshots) 또는 로그(logs)가 필요한 경우
• 작성자가 아닌 사람도 자동화를 실행해야 하는 경우
• AI 에이전트(AI agent)가 해당 작업을 호출해야 하는 경우
• 작업이 헤드리스(headless) 모드와 가시적(visible) 모드 사이를 전환하는 경우
• 결과를 팀 기록(team record)에 저장해야 하는 경우

체크 표시를 많이 할수록, 귀하의 자동화는 단순한 스크립트(script)를 벗어나게 됩니다.

그것은 하나의 운영 단위(operational unit)입니다.

그 단위는 이름, 입력(inputs), 경계(boundaries), 그리고 출력(outputs)을 가질 자격이 있습니다.

최고의 자동화는 반복하기에 지루할 정도여야 한다

훌륭한 브라우저 자동화는 단순히 브라우저를 움직이게 만드는 것만이 아닙니다.

동일한 브라우저 작업을 안전하게 반복할 수 있도록 만드는 것입니다.

이는 다음과 같은 것들이 명확해야 함을 의미합니다:
**계정(account)**이 알려져 있어야 합니다.
**프로필(profile)**이 알려져 있어야 합니다.
**프록시 컨텍스트(proxy context)**가 알려져 있어야 합니다.
**허용된 동작(allowed actions)**이 알려져 있어야 합니다.
**중단 조건(stop conditions)**이 알려져 있어야 합니다.
**증거(evidence)**가 저장되어야 합니다.
**결과(result)**를 검토할 수 있어야 합니다.

Playwright 스크립트는 훌륭한 시작점입니다.

하지만 워크플로(workflow)가 계정 식별(account identity), 브라우저 상태(browser state), 프록시 매핑(proxy mapping), 검토 규칙(review rules), 그리고 **반복 가능한 증거(repeatable evidence)**에 의존하게 된다면, 그것은 더 내구성이 있는 무언가로 변해야 합니다.

단순한 스크립트는 단순하게 유지하십시오.

반복되는 계정 인식 작업(account-aware tasks)은 브라우저 스킬(browser skills)로 격상시키십시오.

그리고 브라우저 상태, 작업 경계, 실행 로그를 자동화 시스템의 일급 객체(first-class parts)로 만드십시오.

브라우저 프로필, 프록시 체크, MCP 워크플로, 그리고 계정 인식 자동화에 대한 더 실무적인 노트는 이 브라우저 자동화 및 프로필 워크플로 관련 추가 노트를 참조하십시오.