Claude Code와 Playwright MCP로 AI 디자이너 만들기

"코드도 짜고, 직접 브라우저를 열어 바뀐 UI를 체크·수정까지 반복하는 AI 디자이너” 만들기

Claude Code + Playwright MCP 조합

---

1) 필수 준비물

• Claude Code (데스크톱/CLI 아무거나)
• Node.js(LTS) + npx
• Git, 브라우저 드라이버는 Playwright가 자동 관리

Playwright용 공식 MCP 서버는 Microsoft가 배포

---

2) Claude Code에 Playwright MCP 붙이기 (가장 쉬운 방법)

한 줄 설치

claude mcp add playwright npx '@playwright/mcp@latest'

이제 claude(또는 Claude Code)를 실행하면 “playwright” 도구가 떠. 위 커맨드는 신뢰할 만한 실전 가이드에서 확인된 방법

(대안) JSON으로 등록

claude mcp add-json playwright '{
  "type":"stdio",
  "command":"npx",
  "args":["@playwright/mcp@latest"]
}'
# 확인
claude mcp get playwright

Anthropic 공식 문서에 나오는 add-json 방식

참고: 커뮤니티/포크 서버들도 있지만, 처음엔 공식 microsoft/playwright-mcp를 권장.

---

3) Playwright MCP로 무엇을 할 수 있나?

브라우저 열기/닫기, 이동, 클릭, 타이핑, 스크린샷, 콘솔·네트워크 로그 확인, 뷰포트(모바일/태블릿/데스크탑) 전환 같은 시나리오를 Claude가 직접 실행할 수 있어. 공식 리포가 “LLM이 웹페이지와 상호작용”하도록 설계됐다고 명시.

---

4) “AI 디자이너” 워크플로 세팅

아래 3개 파일만 프로젝트 루트에 추가하면, 네 코드를 고치고 브라우저로 검증하고 다시 손보는 자체 수정 루프가 돈다.

A. design-principles.md (디자인 원칙)

• 간격/그리드/타이포/컬러/경계선/모션/반응형 단위(모바일 375px, 태블릿 768px, 데스크탑 1280px 이상) 명시
• 접근성(A11y) 체크리스트: 대비, 포커스, 키보드 탐색, ARIA

이 문서는 “Claude가 판단 잣대”로 쓰게 됨. (동영상에서도 원칙 문서를 맥락으로 넣어 상시 비교)
Playwright MCP로는 뷰포트 전환·스크린샷·상태 점검이 가능하니 원칙과 자동 비교 루틴을 엮기 좋다.

B. claude.md (작업 규칙 + 빠른 시각 체크)

# Visual Development & Testing (Quick Check)
1) 이번 변경으로 영향 받는 화면을 식별한다.
2) Playwright MCP로 해당 화면들에 진입한다.
3) 모바일(375), 태블릿(768), 데스크탑(1280) 뷰포트에서 스크린샷을 찍고 깨짐/오버플로우/잘림을 기록한다.
4) 콘솔/네트워크 에러가 없는지 확인한다.
5) `design-principles.md`와 비교해 수정 포인트 To-Do를 만든다.
6) 수정 후 다시 1)로 루프한다.

“빠른 체크”는 개발 중 수시 실행. “정식 리뷰”는 PR 직전(아래 C 항목).

C. agents/design-review.md (정식 디자인 리뷰 에이전트)

# Design Review Agent
목표: 인터랙션 상태·반응형·접근성·성능을 시스템적으로 점검한다.

## 테스트 범위
- 로그인 플로우 → 대시보드 → 주요 기능(검색/필터/폼/상세)
- 에러 상태, 로딩 상태, 비정상 입력

## 필수 명령(Playwright MCP)
- 페이지 열기/이동/대기, 클릭/입력/호버, 뷰포트 변경(375/768/1280), 스크린샷 저장
- 콘솔·네트워크 로그 수집

## 합격 기준(Checklist)
- 레이아웃: 겹침/잘림 없음, 그리드 정렬
- 타이포/간격: base/line-height 준수
- 반응형: 375/768/1280에서 핵심 요소 가시성 보장
- 접근성: 포커스링, 스킵링크, 명확한 레이블
- 성능: 초기 로드 합리적(이미지 지연 로딩 등)

---

5) Claude에게 시키는 “프롬프트(한글) 예시”

(개발 중) 빠른 시각 체크

Playwright MCP를 사용해 다음을 수행해줘:
1) http://localhost:3000 접속 → 로그인(email: test@example.com, pw: password)
2) Members 페이지 이동 후, 뷰포트를 375, 768, 1280으로 순차 변경
3) 각 뷰포트에서 스크린샷 저장: ./_artifacts/screens/{viewport}.png
4) 콘솔/네트워크 에러 수집
5) design-principles.md 기준으로 UI 개선 To-Do를 만들어줘 (우선순위 포함)

(PR 전) 정식 디자인 리뷰

"agents/design-review.md"를 지침으로 삼아 전체 시나리오를 점검해줘.
- 로그인→검색→필터→상세→폼 제출까지 흐름
- 반응형/접근성/에러·로딩 상태를 중점 확인
- 모든 증거 스크린샷을 ./_artifacts/review/** 에 저장
- 발견사항을 요약 표로 만들고, 수정 PR 체크리스트를 출력

이런 “자연어 → 브라우저 실동작”이 바로 MCP + Playwright의 핵심 가치.

---

6) 첫 실행 점검(문제 예방 체크리스트)

• 권한 팝업/로그인 2FA: 테스트용 계정 준비(2FA 해제 계정 권장)
• 고정 시드 데이터: UI가 매번 달라지지 않게 목/샘플 데이터 고정
• 경로·대기: 로딩 스피너가 사라질 때까지 wait 로직 사용
• 아티팩트 폴더: ./_artifacts 미리 만들어두기(스크린샷 저장 실패 방지)

---

7) CI에 녹이기(선택)

GitHub Actions 등에서 npm i → npx @playwright/test install → claude 워크를 돌려 시각 리그레션 스냅샷을 보관할 수 있다.

---

8) 더 살펴볼 레퍼런스

• 공식 Playwright MCP 리포(Microsoft): 서버 개요와 철학을 확인.
• Claude Code와 MCP 연동 가이드(Anthropic): add-json, 상태확인 명령어들.
• 빠른 시작 커맨드 사례(실전 팁): claude mcp add playwright npx '@playwright/mcp@latest'.
• 심화 학습/데모 글·영상: 자동 테스트 생성, 탐색형 에이전트 아이디어.

---

전체 요약

1. claude mcp add playwright npx '@playwright/mcp@latest'로 도구를 붙이고,
2. 디자인 원칙·체크리스트·리뷰 에이전트를 md로 정의,
3. “빠른 체크 ↔︎ 수정 ↔︎ 재검증” 루프를 Claude에게 시킨다.