---
title: "v3 브라우징 보고서 작성 설명서 (다음 컨텍스트용 가이드)"
notion_id: "3672296208688127965bc70d82fd6ba5"
notion_url: "https://app.notion.com/p/3672296208688127965bc70d82fd6ba5"
category: "report-version"
parent: "MCP브라우징 보고서"
updated: "2026-05-21"
priority: "Low"
purpose: "v3 MCP 브라우징 보고서 작성자용 가이드 — Playwright MCP 환경점검 시나리오, 캡처 절차, catbox 업로드 스크립트, 이슈 트래킹"
---

> 이 페이지는 v2(2026-05-21 시각 검증 완료) 이후 v3 브라우징 보고서를 작성할 다음 컨텍스트 작업자(Claude Code 또는 [Claude.ai](http://Claude.ai))에게 전달하는 설명서이다.
>
> v2 작성과정에서 시행착오로 습득한 "하면 안 되는 것 / 이렇게 해야 하는 것"을 정리해서, v3은 시행착오 최소화.
---
## 0. 도구 레퍼런스
| 도구 | 용도 |
|---|---|
| Playwright MCP | 시각 캐프처, 픽셀 측정, 콘솔 수집 |
| Notion MCP (fabb...) | 보고서 페이지 교체 / 하위 페이지 보관 / 갤러리 임베드 |
| PowerShell | [catbox.moe](http://catbox.moe) 자동 업로드, 캐프처 무결성 검증 |
| git | **사용자 별도 지시 이전 금지** |

---
## 0.5. Playwright MCP 환경 점검 (작업 시작 전 필수)
> v2 작성 세션은 이미 Playwright MCP가 설치되어 있어 즉시 진입했다. 그러나 v1 작성 시점(2026-05-20 집 환경)에서는 Playwright MCP 미설치로 "시각 검증 미수행” 점을 받았다. v3 작성자는 **먼저 환경 점검을 1분 안에 끝내고**, 문제가 있으면 아래 시나리오에 따라 사용자에게 표준 가이드를 전달한다.
### 0.5-1. 1분 환경 체크 (작업 시작 직전)
아래 3단계를 순서대로 실행. 한 명이라도 실패 시 0.5-2 시나리오 매칭으로.
**[체크 1] 도구 노출 확인** — ToolSearch 또는 초기 system message의 deferred tools 목록에서 `mcp__playwright__browser_navigate` 등이 나타나는지.
```javascript
✅ 조건: 아래 7개 도구가 deferred tools 목록에 존재
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_resize
  - mcp__playwright__browser_take_screenshot
  - mcp__playwright__browser_snapshot
  - mcp__playwright__browser_click / browser_type / browser_fill_form
  - mcp__playwright__browser_console_messages / browser_network_requests
  - mcp__playwright__browser_evaluate
❌ 노출 안 됩 → 시나리오 A (전면 미설치)
```
**[체크 2] 도구 로딩 테스트** — ToolSearch로 스키마 로드 후 about:blank 장치 호출.
```javascript
browser_navigate({url: 'about:blank'})
  → 성공 (응답: "### Ran Playwright code...")
    → 체크 3으로
  → 실패 (양상: timeout / "browser not available" / connection refused)
    → 시나리오 B·C 중 한남 (에러 메시지로 구분)
```
**[체크 3] resize + navigate + screenshot 원라운드** — 실제 캐프처 경로까지 도달하는지.
```javascript
1) browser_resize(1440, 900)
2) browser_navigate('https://example.com')
3) browser_take_screenshot(filename: 'test.png')
  → .playwright-mcp 폴더에 PNG 생성 성공이면 완전 정상
  → "browser binary not found" / "Executable doesn't exist" → 시나리오 D (chromium 누락)
  → 그 외 에러 → 시나리오 E·F 매칭
```
### 0.5-2. 시나리오별 진단·해결
#### 시나리오 A. **전면 미설치** (deferred tools 목록에 mcp__playwright__* 완전 부재)
- 증상: ToolSearch `select:mcp__playwright__browser_navigate`의 결과가 비어 있거나 "not found"
- 원인: Claude Code의 `claude.json` 또는 설정 파일에 Playwright MCP 서버 등록 자체가 안 됩
- **사용자에게 요청할 명령 (첨부 테플릿)**:
```javascript
🚫 Playwright MCP가 설치되어 있지 않아 시각 검증 작업을 시작할 수 없습니다.
아래 명령을 PowerShell에서 실행해 주세요 (사용자 scope로 설치):

  claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest

설치 후 Claude Code를 완전히 종료·재시작해 주세요 (탭 닫음 또는 프로세스 종료).
재시작 후 이 세션으로 돌아와 "설치 완료”라고 알려주세요. 이어서 계속 진행하겠습니다.
```
- 검증: 재시작 후 다시 체크 1을 실행.
#### 시나리오 B. **등록됨 + 서버 기동 실패** (도구는 보이는데 호출 시 에러)
- 증상: ToolSearch로 스키마 로드는 되는데 `browser_navigate('about:blank')` 실행 시 "connection refused" / "server not running" / timeout
- 원인 후보:
	1. claude.json은 있지만 npx가 서버를 기동 못함 (npm cache 손상, node 버전 불일치)
	2. 방화벽 / 안티바이러스가 npx 자식 프로세스 차단
	3. 이전 세션의 좌비 프로세스가 포트 점유
- **사용자에게 요청할 명령**:
```javascript
⚠ Playwright MCP는 등록되어 있으나 서버 기동에 실패하고 있습니다.
아래 명령을 PowerShell에서 실행해 진단·대응해 주세요:

  # 1단계: MCP 등록 상태 확인
  claude mcp list

  # playwright 항목이 보이면 OK. 보이지 않으면 시나리오 A로 이동.

  # 2단계: npx 수동 실행으로 서버 기동 테스트
  npx -y @playwright/mcp@latest --help

  # 정상: usage 메시지 출력 / 비정상: 에러 메시지 (다음 항목 제공)

  # 3단계: Claude Code 완전 종료 후 재시작
  # (좌비 프로세스 정리를 위한 가장 확실한 방법)

흔한 명령 에러 메시지 악리면 그대로 알려주세요.
```
#### 시나리오 C. **scope 불일치** (project scope에만 설치, 다른 경로에서는 미노출)
- 증상: 이전에 다른 디렉토리에서는 절을 쓰던 Playwright MCP가 현재 작업 경로에서 안 보임
- 원인: `claude mcp add playwright`를 `--scope user` 없이 실행해서 현재 프로젝트 .mcp.json에만 등록됨
- **사용자에게 요청할 명령**:
```javascript
⚠ Playwright MCP가 현재 작업 경로에서는 안 보입니다 (scope 불일치 추정).
사용자 전역 scope로 재설치해 주세요:

  # 현재 등록 상태 확인
  claude mcp list
  claude mcp list --scope user

  # 이전 등록 제거 (충돌 방지)
  claude mcp remove playwright

  # user scope로 재설치
  claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest

  # Claude Code 종료 · 재시작
```
#### 시나리오 D. **Chromium 바이너리 누락** (도구 호출은 되는데 navigate 실패)
- 증상: `browser_navigate` 에러 메시지에 "Executable doesn't exist" / "browser binary not found" / "chromium" 키워드 포함
- 원인: @playwright/mcp가 내부적으로 playwright-core를 쓰는데 chromium·webkit 등 바이너리가 다운로드되지 않음
- **사용자에게 요청할 명령**:
```javascript
⚠ Chromium 브라우저 바이너리가 다운로드되지 않았습니다.
PowerShell에서 아래 명령을 실행해 주세요:

  # Chromium 설치 (수 분 소요)
  npx playwright install chromium

  # 설치 경로 확인
  npx playwright install --dry-run chromium

완료 시 알려주세요. 다시 캡처 경로로 진행하겠습니다.
```
#### 시나리오 E. **버전 outdated** (도구는 동작하는데 일부 기능 누락)
- 증상: snapshot은 되는데 take_screenshot이 fail / fill_form이 unknown command / network_requests 파라미터 mismatch
- 원인: @playwright/mcp 가 구 버전으로 고정됨 (npm cache 해속 안 됨)
- **사용자에게 요청할 명령**:
```javascript
⚠ Playwright MCP의 일부 도구가 구 버전으로 동작 중입니다. 최신으로 갱신해 주세요:

  # 현재 버전 확인
  npx -y @playwright/mcp@latest --version

  # 강제 최신 갱신 (npm cache 우회)
  npm cache clean --force
  npx -y @playwright/mcp@latest --version

  # Claude Code 종료 · 재시작
```
#### 시나리오 F. **좌비 브라우저 context** (이전 세션의 프로세스 잔존)
- 증상: 첫 navigate는 성공 같은데 snapshot이 계속 빌 상태, 또는 "target page already detached" 에러
- 원인: Claude Code 비정상 종료 시 playwright-core node 프로세스 잔존
- **사용자에게 요청할 명령**:
```javascript
⚠ 이전 세션의 브라우저 프로세스가 남아있을 가능성이 있습니다. 좌비 정리:

  # node 프로세스 목록 확인
  Get-Process node -ErrorAction SilentlyContinue | Select-Object Id, ProcessName, StartTime

  # Playwright/chromium 관련 프로세스 강제 종료 (주의: 다른 node 작업 중이면 단독으로)
  Get-Process -Name node, chrome, chromium, msedge -ErrorAction SilentlyContinue | Where-Object { $_.MainWindowTitle -eq '' } | Stop-Process -Force

  # Claude Code 종료 · 재시작
```
### 0.5-3. 자가진단 1줄 스크립트 (의심스러울 때)
제일 아래 한 줄로 대부분의 이상을 검출:
```javascript
browser_evaluate(() => ({
  ua: navigator.userAgent.slice(0, 60),
  viewport: { w: innerWidth, h: innerHeight },
  url: location.href
}))
```
- ua에 "HeadlessChrome” 포함 + viewport 정상 + url이 의도한 경로이면 OK.
- timeout 또는 에러 → 시나리오 D·F 재확인.
### 0.5-4. 세션별 체크리스트 (작업 시작 전 1회)
- [ ] mcp__playwright__* 7개 도구 노출 확인
- [ ] browser_navigate('about:blank') 성공
- [ ] browser_take_screenshot 성공 (.playwright-mcp/ 폴더 PNG 생성)
- [ ] [dallog.pages.dev/login](http://dallog.pages.dev/login) 진입 → 로그인 폼 정상 렌더링 확인
- [ ] mster/qwer1234 로그인 → 대시보드 진입 확인
4개 이상 핵시 되면 §1 이후로 진행. 높은 확률로 자동 진행 가능.
### 0.5-5. 사용자에게 보고할 표준 포맷
환경점검 결과는 아래 표준 메시지로 알린다 — 작업 자동 대기/재시작 흐름이 매끄러워짐:
```javascript
Playwright MCP 환경 점검 결과:
  • 도구 노출: 7/7 ✅
  • about:blank 테스트: 성공 ✅
  • 로그인 → 대시보드: 성공 ✅
  ——
  작업 시작 가능 → §1 작업 흐름 진입합니다.
```
또는 이상 시:
```javascript
Playwright MCP 환경 점검 결과:
  • 도구 노출: 0/7 ❌ → 시나리오 A 감지

아래 명령을 PowerShell에서 실행해 주시고, 완료되면 Claude Code를 재시작해 주세요:
  claude mcp add playwright --scope user -- npx -y @playwright/mcp@latest
```
---
## 1. 작업 흐름 요약 (v2 경험 기반)
```javascript
1) 자산 경로 준비 (mcp_reports/_assets/v3_ui_comparison/current/)
2) Playwright MCP 로그인 → 대시보드 진입 확인 (Supabase API 응답 결젔)
3) 데스크탑 1440×900 캡처 → 모바일 390×844 캡처
4) 캐프처 무결성 검증 (파일 해시 중복 체크) → 재캐프처
5) catbox 자동 업로드 → URL 매핑 JSON 저장
6) v3 MD 출액 (로컬)
7) 사용자 컴펌
8) v2 페이지 본문 압축해 이전버전 하위로 보관 → 메인을 v3로 교체
```
---
## 2. 하지 말 것 (v2에서 시간 낭비한 실수)
### 2-1. `navigate → wait 2초 → 캡처` ×
- Playwright `browser_navigate` 직후의 page snapshot이 React mount 전 빈 상태일 수 있음.
- 특히 **모바일 viewport(390×844)으로 전환 직후 navigate**는 splash 화면(아이콘 + "달록" 텍스트만 있는 9050 bytes 짜리 고정 PNG)이 캡처될 가능성 높음.
### 2-2. 캐프처 무결성 검증 생략
- v2에서 **5개 모바일 캡처가 모두 9050 bytes 동일 PNG**임을 다 업로드한 후에야 발견. catbox에서 동일 hash 파일을 동일 URL로 반환하면서 알게 됨.
- 컬러닝 이전에 반드시 Get-FileHash로 중복 없는지 확인.
### 2-3. 메인 페이지 replace_content만 하고 이미지 생각 안 함
- Notion MCP의 image embed는 외부 URL만 지원. "자리표시자 했다 쪼”로 끝내지 말고 catbox 업로드 → ![alt](url) 임베드 일괄 진행.
### 2-4. \`\`\`json 코드블록 본문 삽입
- Notion API 마크다운 파서가 ` `json `을 잘못 처리해서 표 셀 안 코드블록이 깨짐. **코드블록 장치는 표 셀 밖 또는 일반 문단으로만**.
- v2 본문은 `json` 워딩만으로 우회함.
### 2-5. 메인 보고서의 이전버전 보관 절차 생략
- replace_content만 하면 v2 본문이 증발. 반드시 "이전버전 — ... (v2)” 하위 페이지 생성 후 replace.
---
## 3. 이렇게 해야 하는 것 (v3 권장 절차)
### 3-1. Playwright 로그인 (프롬프트 템플릿)
```javascript
1. browser_resize → 1440×900
2. browser_navigate → https://dallog.pages.dev/login
3. browser_take_screenshot (login-desktop.png)
4. browser_resize → 390×844 → 재캐프처 (login-mobile.png)
5. browser_resize → 1440×900
6. browser_snapshot → 아이디 필드 / 비밀번호 필드 / 로그인 버튼 ref 확보
7. browser_type mster / qwer1234
8. browser_click "로그인" 조심: 로그인 직후 snapshot은 일시적으로 빈 상태일 수 있음.
9. browser_network_requests static=true → Supabase /rest/v1/body_records, running_logs, strength_logs 응답 200 확인
10. 확인되면 캡처 시작
```
### 3-2. React mount 검증 (캡처 전 필수)
매번 캐프처 직전에:
```javascript
browser_evaluate(() => ({
  rootChildren: document.getElementById('root').children.length,
  bodyTextLen: document.body.innerText.length
}))
```
- `rootChildren >= 1` 그리고 `bodyTextLen >= 100` 일 때만 캡처.
- 조건 불충족 시 browser_wait_for time=3~5 추가.
### 3-3. 캡처 매트릭스 (v2 참고)
v2 대비 v3 추가/수정 필요 항목:
- `/coach`의 렌더링 수정 결과 재캡처 (P1-3 적용 후)
- `/strength-log` 리다이렉트 적용 후 재캡처 (P1-5)
- `/settings` 수정로그 Supabase 400 해소 확인 (P1-7)
- `/login` 세션 재진입 가드 검증 (P1-6) — 로그인 후 다시 /login 진입 시 대시보드로 리다이렉트되는지
### 3-4. catbox 자동 업로드 스크립트 (PowerShell)
v2에서 검증된 스크립트:
```powershell
function Upload-ToCatbox($filePath) {
  $fileBytes = [System.IO.File]::ReadAllBytes($filePath)
  $fileName = [System.IO.Path]::GetFileName($filePath)
  $boundary = [System.Guid]::NewGuid().ToString()
  $LF = "`r`n"
  $bodyStart = (
    "--$boundary",
    "Content-Disposition: form-data; name=`"reqtype`"",
    "",
    "fileupload",
    "--$boundary",
    "Content-Disposition: form-data; name=`"fileToUpload`"; filename=`"$fileName`"",
    "Content-Type: image/png",
    ""
  ) -join $LF
  $startBytes = [System.Text.Encoding]::UTF8.GetBytes($bodyStart + $LF)
  $endBytes = [System.Text.Encoding]::UTF8.GetBytes($LF + "--$boundary--$LF")
  $combined = New-Object byte[] ($startBytes.Length + $fileBytes.Length + $endBytes.Length)
  [Array]::Copy($startBytes, 0, $combined, 0, $startBytes.Length)
  [Array]::Copy($fileBytes, 0, $combined, $startBytes.Length, $fileBytes.Length)
  [Array]::Copy($endBytes, 0, $combined, $startBytes.Length + $fileBytes.Length, $endBytes.Length)
  $r = Invoke-WebRequest -Uri 'https://catbox.moe/user/api.php' -Method POST -ContentType "multipart/form-data; boundary=$boundary" -Body $combined -UseBasicParsing -TimeoutSec 120
  return $r.Content.Trim()
}
```
워크플로우:
```powershell
# 1. 전체 업로드 + JSON 저장
$dir = 'C:\!claude_home_worksapce\claude_code\dallog\mcp_reports\_assets\v3_ui_comparison\current'
$files = Get-ChildItem -Path $dir -Filter *.png | Sort-Object Name
$map = [ordered]@{}
foreach ($f in $files) {
  $url = Upload-ToCatbox $f.FullName
  $map[$f.Name] = $url
}
$map | ConvertTo-Json | Out-File ($dir + '\..\catbox_urls.json') -Encoding utf8

# 2. 해시 중복 검증 (수동 또는 스크립트)
Get-ChildItem $dir -Filter *.png | ForEach-Object {
  [PSCustomObject]@{File=$_.Name; SizeKB=[math]::Round($_.Length/1KB,1); Hash=(Get-FileHash $_.FullName).Hash.Substring(0,16)}
} | Group-Object Hash | Where-Object {$_.Count -gt 1}
# 결과가 비어 있으면 OK. 안은 중복 한 세트 → 재캐프처 필요.
```
### 3-5. Notion 페이지 교체 절차
```javascript
1. notion-fetch → 메인 페이지 현재 본문 확보 (v2)
2. notion-create-pages → "이전버전 — v2 보관본 (260521)" 하위 페이지 생성. 내용은 v2 본문 압축 요약 (원본 MD는 로컬 보관 명시).
3. notion-update-page command=replace_content → v3 본문 + 부록 A-갤러리 (32개 ![alt](url) 임베드) + 이전버전 하위 페이지 참조 보존:
   <page url="...">이전버전 v2 보관본 (260521)</page>
   <page url="#/doc/archive-report-04">이전버젠 v1 보관본 (260520)</page>
   <page url="#/doc/archive-report-03">[Claude.ai](http://Claude.ai) MCP브라우징보고서_260520_1</page>
4. notion-fetch 재검증 → 하위 3개 보관 + v3 본문 + 갤러리 임베드 확인
```
---
## 4. 캡처 매트릭스 증분/신규 항목 (v3 작성 시 공백)
v2 모든 항목 재캡처 + 아래 항목 수정/추가:
| 라우트/섹션 | v3 확인 포인트 |
|---|---|
| /coach Markdown 렌더링 | react-markdown 적용 후 `## 헤더`가 `<h2>`로 렌더링되는지 시각 확인 |
| /coach 코드블록 | ` `json ` 블록이 `<pre><code>` 또는 syntax highlight되는지 |
| /strength-log | 리다이렉트 적용 후 진입 시 URL이 /log로 이동하는지 |
| /settings 수정로그 | Supabase 400 에러 사라지고 수정로그 표 정상 렌더링 |
| /login 재진입 | 로그인된 상태에서 /login 진입 시 /dashboard로 리다이렉트 |
| 대시보드 max-width | 1440에서 축소된 폭 (1000~1200)으로 렌더링되는지 |
| 모바일 하단 탭바 active 색 | 은 색이 라임(#c8f135)으로 통일되었는지 |
| 신규: 세션 재진입 테스트 | localStorage `dallog.masterSession` 존재 상태에서 /login 진입·행동 캡처 |
| 신규: 1920+ viewport | P1-2 검증을 위해 1920×1080 viewport 추가 캐프처 |

---
## 5. v2 이슈 트래킹 표 (v3 적용 상황 확인용)
v2 P1 이슈 7개 상태 추적. v3에서 각 항목 결과 업데이트:
| ID | 항목 | v2 상태 | v3 업데이트 (작성 시 기입) |
|---|---|---|---|
| P1-3 | AI 브리프 Markdown 렌더링 | 노출 확인 ✓ | (v3에서 기입: 해소/미해결) |
| P1-7 | /settings 수정로그 Supabase 400 | 2건 발견 ✓ | (v3에서 기입: 해소/미해결) |
| P1-5 | /strength-log 빈 라우트 | splash 화면 확인 ✓ | (v3에서 기입: 리다이렉트/제거/컴포넌트 구현) |
| P1-6 | /login 재진입 가드 | v2 검증 미수행 | (v3 필수 검증) |
| P1-2 | 대시보드 max-width 축소 | 1920+ 가중치 | (v3에서 기입) |
| P1-4 | 컬러 토큰 정리 | 76건 일관 적용 | (v3에서 기입) |
| P1-1 | 모바일 탭바 마감 보강 | 3-탭 존재 확인 | (v3에서 기입: active 색 / safe-area) |

---
## 6. 파일 경로 규칙
```javascript
mcp_reports/
  v2 관련:
    달록_UI_목업비교_적용우선순위_v2_260521.md
    _assets/260521_ui_comparison/current/  (PNG 32개)
    _assets/260521_ui_comparison/catbox_urls.json
  v3 권장:
    달록_UI_브라우징_v3_YYMMDD.md  (작성일 기준)
    _assets/YYMMDD_ui_comparison/current/  (PNG 생성)
    _assets/YYMMDD_ui_comparison/catbox_urls.json
```
사무실 환경 이전 zip 시 폴더 구조 그대로 유지.
---
## 7. 알아두어야 할 v2 사실 관계
- v2 작업자: Claude Code (Opus 4.7, 1M context), 자기충족 프롬프트 수행
- v2 작업 환경: 집 C:!claude_home_worksapceclaude_codedallog\\
- v2 소요 시간: 약 30분 (P2 수행 + P1 문서화)
- v2 그래프·표·츘팅 세부 수치 원본: 로컬 MD 파일에만 존재. Notion 본문은 요약.
- v2 P1 우선순위 재정렬 근거: 3-탭 이미 존재 발견 + /coach 코드블록까지 노출 심각도 상향
---
## 8. 참조 URL
- [v2 보고서 메인 페이지](#/doc/research-01)
- [이전버전 v1 보관본](#/doc/archive-report-04)
- [Claude.ai](http://Claude.ai)[ MCP브라우징보고서_260520_1](#/doc/archive-report-03)
- [260521 S-문서 (v2 Claude Code 작업보고)](#/doc/workreport-45)
- [이번 세션 핸드오프 26-05-21_1](#/doc/handoff-08)
- [2026-05-21 개발일지](#/doc/devlog-09)
- 달록 배포: [dallog.pages.dev](http://dallog.pages.dev)
- 계정: mster / qwer1234