AI 에이전트에게 브라우저를 부여하기 전, Puppeteer 경계를 정의하세요

Puppeteer는 AI 코딩 에이전트에게 줄 수 있는 가장 실용적인 도구 중 하나입니다. Puppeteer는 Node.js 워크플로우가 고수준 JavaScript API를 통해 Chrome 또는 Firefox를 제어할 수 있게 해주며, 이는 브라우저 자동화 (browser automation), 스크린샷 (screenshots), 스크래핑 (scraping), 페이지 체크 (page checks), 그리고 반복 가능한 웹 작업에 유용합니다.

그 강력한 힘은 곧 위험이기도 합니다.

에이전트가 브라우저를 열 수 있게 되면, 라이브 웹 세션에 접속하거나, 페이지 콘텐츠를 읽고, 링크를 따라가고, 파일을 다운로드하고, 양식을 제출하거나, 개인적인 상태가 포함된 스크린샷을 캡처할 수도 있습니다. 첫 번째 질문은 "에이전트가 Puppeteer를 사용할 수 있는가?"가 되어서는 안 됩니다. 더 나은 질문은 다음과 같습니다:

에이전트가 증거를 생성하면서 명확한 경계 내에 머물 수 있는 가장 작은 브라우저 작업은 무엇인가?

이것은 제가 Puppeteer 지향적 기능을 AI 코딩 호스트에 로드하기 전에 적용할 첫 사용 체크리스트입니다.

1. 두 가지 설치 경로 분리하기

Puppeteer에는 두 가지 일반적인 설치 경로가 있습니다:

• npm i puppeteer: 브라우저 다운로드 동작을 포함한 전체 패키지.
• npm i puppeteer-core: 브라우저 실행 파일(executable)을 직접 제공해야 하는 더 가벼운 코어 라이브러리.

이 선택은 에이전트 워크플로우에서 중요합니다.

만약 에이전트가 알려진 로컬 페이지나 CI 프리뷰만 확인한다면, puppeteer-core와 명시적인 executablePath를 사용하는 것이 추론하기 더 쉬울 수 있습니다. 만약 에이전트가 빠른 격리된 스모크 테스트 (smoke test)를 위해 번들된 브라우저 경로가 필요하다면 전체 패키지가 편리할 수 있지만, 이는 설치 표면 (install surface)을 변화시킵니다.

에이전트가 이를 무심코 선택하게 두지 마세요. 에이전트에게 다음 사항을 명시하도록 요청하십시오:

• 어떤 패키지를 원하는지;
• 브라우저 다운로드가 예상되는지;
• 임시 파일과 브라우저 캐시가 어디에 위치할지;
• 실행 시 네트워크 액세스가 필요한지;
• 첫 번째 작업이 성공했음을 증명하는 명령어가 무엇인지.

2. 첫 번째 실행을 증거 지향적으로 만들기

유용한 첫 번째 Puppeteer 실행은 단순히 자신감 있는 설명이 아니라, 작은 결과물 (artifact)을 생성해야 합니다.

좋은 첫 실행 증거는 다음과 같을 수 있습니다:

• 로컬 테스트 페이지의 스크린샷 (screenshot);
• 제어된 URL에서 저장된 HTML 발췌본 (HTML excerpt);
• 단일 페이지에 대한 네트워크 요청 (network requests) 목록;
• 콘솔 로그 캡처 (console log capture);
• URL, 상태 (status), 제목 (title), 셀렉터 결과 (selector result), 타임스탬프 (timestamp)를 포함하는 짧은 JSON 보고서.

나쁜 첫 실행 증거는 다음과 같습니다:

• "페이지를 검사해 보았고 괜찮아 보입니다";
• "자동화가 작동할 것입니다";
• "Puppeteer가 설치되었습니다";
• 로그인된 개인 계정의 스크린샷;
• 기본 경로를 증명하기 전에 프로덕션 자격 증명 (production credentials)을 요구하는 실행.

AI 코딩 에이전트의 경우, 규칙은 단순해야 합니다: 만약 결과물 (artifact)이 생성되지 않았다면, 브라우저 작업은 아직 검증되지 않은 것입니다.

3. 브라우저 접근을 권한 경계 (Permission Boundary)로 취급하세요

Doramagic Puppeteer 경계 카드는 최소한의 권한, 임시 디렉토리 (temporary directory), 그리고 롤백 가능한 설정 (rollbackable configuration)으로 시작할 것을 권장합니다. 그것이 올바른 기본값입니다.

에이전트가 Puppeteer를 실행하기 전에, 평이한 언어로 경계를 정의하세요:

• 허용된 URL 또는 도메인;
• 로그인 상태 (login state) 사용 가능 여부;
• 스크린샷 (screenshots) 캡처 가능 여부;
• 다운로드 허용 여부;
• 양식 제출 (form submission) 허용 여부;
• 브라우저 데이터와 임시 파일이 기록될 위치;
• 무엇이 실행을 즉시 중단시켜야 하는지.

예시:

http://localhost:3000에 대해서만 Puppeteer를 사용하세요.
기존 브라우저 프로필을 사용하지 마세요.
양식을 제출하지 마세요.
...

이렇게 하면 에이전트가 단순한 UI 확인을 개방형 웹 세션 (open-ended web session)으로 변질시키는 것을 방지할 수 있습니다.

4. 실제 첫 사용 시의 함정들을 주의하세요

Doramagic Puppeteer 팩은 설치 동작, 브라우저 버전, 패키지 경고, 불안정한 테스트 (flaky tests), 캐시 동작, Firefox 뷰포트 (viewport) 동작, 브라우저 바이너리 (browser binary) 가용성과 관련된 소스 연결 함정들을 기록합니다. 이것들을 "Puppeteer는 안전하지 않다" 또는 "Puppeteer는 고장 났다"와 같이 과장해서는 안 됩니다. 이것들은 체크포인트 (check points)입니다.

유용한 습관은 각 리스크를 검증 질문으로 바꾸는 것입니다:

• 어떤 Node 버전이 사용되고 있습니까?
• 프로젝트가 puppeteer를 설치하는지 아니면 puppeteer-core를 설치하는지?
• Chrome이 다운로드되었는지, 건너뛰어졌는지, 또는 외부에서 제공되었는지?
• 에이전트가 존재한다고 생각하는 위치에 브라우저 실행 파일이 있습니까?
• 캐시 디렉터리가 임시적이고 폐기 가능한가요?
• 스모크 테스트가 에이전트의 가정뿐만 아니라 대상 브라우저에서 작동합니까?

이는 특히 CI(지속적 통합), 컨테이너, 원격 개발 환경처럼 브라우저 의존성이 개발자 노트북과 다른 곳에서는 더욱 중요합니다.

5. 에이전트 실행에 GO / HOLD / NO-GO 사용하기

첫 Puppeteer 기능 테스트를 위해 저는 다음 결정 규칙을 사용할 것입니다:

• GO: 작업이 제어된 URL을 사용하고, 스크린샷이나 보고서를 생성하며, 기존 사용자 프로필을 피하고, 재실행될 수 있는 경우.
• HOLD: 브라우저는 열리지만, 설치 경로, 캐시 경로, 실행 파일 경로 또는 대상 URL이 불분명한 경우.
• NO-GO: 에이전트가 최소한의 브라우저 스모크 테스트를 증명하기 전에 프로덕션 로그인 상태, 개인 데이터 또는 외부 양식 제출이 필요한 경우.

핵심은 에이전트를 소극적으로 만드는 것이 아닙니다. 핵심은 브라우저 자동화를 검사 가능하게 유지하는 것입니다.

6. 더 안전한 첫 번째 지침

AI 코딩 에이전트에게

Puppeteer는 에이전트에게 브라우저라는 '손'을 부여합니다. 당신이 설정한 경계(boundary)는 그 손이 어디로 향해도 되는지에 대한 판단력을 부여합니다.

참조: 독립적인 Doramagic Puppeteer 프로젝트 페이지 및 매뉴얼은 여기에 있습니다: https://doramagic.ai/en/projects/puppeteer/manual/

업스트림 프로젝트 (Upstream project): https://github.com/puppeteer/puppeteer

고지 사항 (Disclosure): 본 내용은 Puppeteer를 위한 독립적인 Doramagic 기능 팩(capability pack)을 기반으로 합니다. 명시적으로 언급되지 않는 한, Puppeteer 또는 Google과 제휴하거나 승인받은 것이 아닙니다.