diff --git a/docs/development/index.md b/docs/development/index.md
index 73c4c88..f22c0de 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -8,6 +8,7 @@
 - [document-category-classification.md](./document-category-classification.md) — 카테고리 분류 기준 (불필요한 카테고리는 프로젝트에 맞게 정리)
 - [agent-output-conventions.md](./agent-output-conventions.md) — 에이전트 출력 규약. 사용자 대면 의사결정 제시문엔 압축 비적용(배경+선택지+권장 풀어쓰기), 압축은 내부 산출물 한정
 - [git-workflow.md](./git-workflow.md) — 브랜치 분류(메인스트림 vs 비-메인스트림) · 비-메인스트림 브랜치 커밋 표준 승인 · push 명시 요청 한정 · Conventional Commits + `Co-Authored-By` 트레일러 규약. CLAUDE.md '작업 원칙' 커밋 정책의 정본.
-- [local-dev-setup.md](./local-dev-setup.md) — 로컬 구동 환경 설정. 업로드 저장 루트(`~/.bibimbap/uploads`, static 트리 밖) 경로 규약 · @Value 기본값 유지 근거 · 자산 이전 이력 · SSRF DNS 캐시 운영 참고.
+- [local-dev-setup.md](./local-dev-setup.md)
+- [screenshot-guide.md](./screenshot-guide.md) — Playwright 헤드리스 스크린샷. `python3 docs/development/screenshot-guide.py` → `/tmp/bibimbap-screenshots/*.png`. Claude Design 등 외부 디자인 툴 연동용. — 로컬 구동 환경 설정. 업로드 저장 루트(`~/.bibimbap/uploads`, static 트리 밖) 경로 규약 · @Value 기본값 유지 근거 · 자산 이전 이력 · SSRF DNS 캐시 운영 참고.
 
 > atp 플러그인 번들 레퍼런스(`agent-team-protocol.md`, `agent-catalog.md`, `documentation-guidelines.md`, `search-tool-matrix.md`)는 플러그인 캐시에 있으며 이 프로젝트로 복사되지 않는다. 에이전트가 `${CLAUDE_PLUGIN_ROOT}/docs/...` 로 직접 참조한다.
diff --git a/docs/development/screenshot-guide.md b/docs/development/screenshot-guide.md
new file mode 100644
index 0000000..1110d49
--- /dev/null
+++ b/docs/development/screenshot-guide.md
@@ -0,0 +1,65 @@
+# 페이지 스크린샷 가이드
+
+앱 실행 중 각 페이지를 파일로 저장하는 방법. Claude Design 등 외부 도구에 전달할 때 사용.
+
+## 전제 조건
+
+- 앱 실행 중 (`docker compose up`)
+- Python 3 + playwright 설치됨
+
+```bash
+pip3 install playwright
+# 브라우저 다운로드 불필요 — 로컬 Chrome 사용
+```
+
+## 스크립트
+
+```python
+import os
+from playwright.sync_api import sync_playwright
+
+CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+OUT_DIR = "/tmp/bibimbap-screenshots"
+BASE_URL = "http://localhost:8080"
+
+pages = [
+    ("/", "01-home.png"),
+    ("/login", "02-login.png"),
+    ("/signup", "03-signup.png"),
+    ("/posts", "04-posts-list.png"),
+    ("/recruit", "05-recruit-list.png"),
+    ("/game/3", "06-game-detail.png"),
+    ("/terms", "07-terms.png"),
+]
+
+os.makedirs(OUT_DIR, exist_ok=True)
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(
+        executable_path=CHROME,
+        headless=True,
+        args=["--no-sandbox"]
+    )
+    page = browser.new_page(viewport={"width": 1400, "height": 900})
+
+    for path, filename in pages:
+        page.goto(f"{BASE_URL}{path}", wait_until="networkidle")
+        page.screenshot(path=os.path.join(OUT_DIR, filename), full_page=True)
+        print(f"✓ {filename}")
+
+    browser.close()
+```
+
+## 실행
+
+```bash
+python3 docs/development/screenshot-guide.py
+# 결과: /tmp/bibimbap-screenshots/*.png
+```
+
+## 주의
+
+- 헤드리스 모드는 다크 테마 미적용 (시스템 prefers-color-scheme 무시)
+- 로그인 필요 페이지는 세션 없이 리다이렉트됨
+- `/tmp/bibimbap-screenshots/` 는 재부팅 시 삭제 — 영구 저장 필요하면 경로 변경
+- Claude Design에 넘길 때 "다크 테마로 리디자인" 프롬프트에 명시
diff --git a/docs/development/screenshot-guide.py b/docs/development/screenshot-guide.py
new file mode 100644
index 0000000..46f10ed
--- /dev/null
+++ b/docs/development/screenshot-guide.py
@@ -0,0 +1,35 @@
+import os
+from playwright.sync_api import sync_playwright
+
+CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+OUT_DIR = "/tmp/bibimbap-screenshots"
+BASE_URL = "http://localhost:8080"
+
+pages = [
+    ("/", "01-home.png"),
+    ("/login", "02-login.png"),
+    ("/signup", "03-signup.png"),
+    ("/posts", "04-posts-list.png"),
+    ("/recruit", "05-recruit-list.png"),
+    ("/game/3", "06-game-detail.png"),
+    ("/terms", "07-terms.png"),
+]
+
+os.makedirs(OUT_DIR, exist_ok=True)
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(
+        executable_path=CHROME,
+        headless=True,
+        args=["--no-sandbox"]
+    )
+    page = browser.new_page(viewport={"width": 1400, "height": 900})
+
+    for path, filename in pages:
+        page.goto(f"{BASE_URL}{path}", wait_until="networkidle")
+        page.screenshot(path=os.path.join(OUT_DIR, filename), full_page=True)
+        print(f"✓ {filename}")
+
+    browser.close()
+
+print(f"\n완료: {OUT_DIR}/")