UI 복잡 버전 234 RED→GREEN 완료(docs/UI_USECASES.md §A~§J): 라이브 테마 전환(DynamicResource 전환+ThemeResolver+HighContrast 테마, 재시작 없음), 디자인 토큰 체계·WCAG 대비 결함 5건 수정, 설정창 카테고리 내비/검색 재구성+AppConfig 40여 속성, 다운로드 관리자(속도/ETA/세그먼트맵/전체 일시정지-이어받기/CSV 내보내기/예약 게이트/중복 확인), 라이브러리·아카이브·작업공간·재생목록·즐겨찾기 편집 뷰, 접근성(자동화 속성 30여 개·커스텀 피어·docs/ACCESSIBILITY.md), 인터랙션(휠 클릭 새 탭·XButton 탐색·F12·영역 캡처·프로필 전환), 상태/알림(토스트·알림센터·온보딩·CrashReportDialog). 보강 테스트 35건+실창 E2E 4건(StaDispatcher 기반 — 프록시 설정이 기시작 핸들러를 건드리는 크래시 실결함 수정 포함) — 453/453 GREEN. 이전 미커밋 작업(CI 워크플로·Mdns·QueueHub·UpdateChecker·AGENTS/CLAUDE·빌드 스크립트) 일괄 포함

2026-08-17 15:54:53 +09:00 · 2026-08-17 15:54:53 +09:00 · 17f2f91152
commit 17f2f91152
parent 5a0ce730b2
88 changed files with 9463 additions and 1127 deletions
--- a/.claude/hooks/session-brief.sh
+++ b/.claude/hooks/session-brief.sh
@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# SessionStart 훅 — 폐쇄루프의 "state layer".
+#
+# 세션 시작 시 저장소의 현재 상태를 요약해 컨텍스트에 넣는다.
+# 에이전트가 매번 git status/log 를 따로 물어보지 않아도 지금 상황을 알고 시작한다.
+# stdout 이 그대로 컨텍스트로 들어가므로 짧게 유지한다.
+set -uo pipefail
+
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$ROOT" ]; then
+    ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+fi
+cd "$ROOT" || exit 0
+
+echo "## 저장소 현재 상태 (SessionStart 자동 브리핑)"
+echo
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "?")
+echo "- 브랜치: \`$BRANCH\`"
+
+LAST=$(git log -1 --format='%h %s' 2>/dev/null | cut -c1-110)
+echo "- 마지막 커밋: $LAST"
+
+CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+if [ "$CHANGED" = "0" ]; then
+    echo "- 작업트리: 깨끗함"
+else
+    echo "- 작업트리: 변경 $CHANGED 건"
+    git status --porcelain 2>/dev/null | head -10 | sed 's/^/    /'
+    if [ "$CHANGED" -gt 10 ]; then
+        echo "    … 외 $((CHANGED - 10))건"
+    fi
+fi
+
+# 마지막 검증 이후 소스가 바뀌었는지 (Stop 훅이 쓰는 스탬프와 같은 기준)
+STAMP=".claude/.verify-stamp"
+NEWEST=$(find ./VideoDownloader.* -type f \
+    \( -name '*.cs' -o -name '*.csproj' -o -name '*.xaml' -o -name '*.axaml' \) \
+    -not -path '*/bin/*' -not -path '*/obj/*' \
+    -printf '%T@\n' 2>/dev/null | sort -rn | head -1)
+
+if [ -f "$STAMP" ] && [ "$(cat "$STAMP" 2>/dev/null)" = "$NEWEST" ]; then
+    echo "- 검증: 마지막 \`dotnet test\` 이후 소스 변경 없음 (GREEN 상태)"
+else
+    echo "- 검증: **미검증 변경 있음** — 작업 전에 \`dotnet test VideoDownloader.Tests\` 로 기준선을 확인할 것"
+fi
+
+# 미완료 백로그
+if [ -f docs/BACKLOG.md ]; then
+    OPEN=$(grep -c '^- \[ \]' docs/BACKLOG.md 2>/dev/null) || OPEN=0
+    echo "- 백로그 미완료: ${OPEN}건 (\`docs/BACKLOG.md\`)"
+fi
+
+echo
+echo "작업 계약은 \`AGENTS.md\`, 하네스 운영법은 \`docs/HARNESS.md\` 참고."
+exit 0
--- a/.claude/hooks/verify-on-stop.sh
+++ b/.claude/hooks/verify-on-stop.sh
@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Stop 훅 — 폐쇄루프의 "checker" 층.
+#
+# 소스(.cs/.csproj/.xaml/.axaml)가 마지막 성공 검증 이후 바뀌었으면 테스트를 돌린다.
+# 실패하면 exit 2 로 턴 종료를 막고, 실패 내용을 에이전트에게 돌려준다.
+# 변경이 없으면 즉시 통과하므로 대화만 하는 턴은 지연이 없다.
+#
+# 무한 루프 방지: stop_hook_active 가 true 면(=이미 이 훅 때문에 재개된 상태) 바로 통과.
+set -uo pipefail
+
+INPUT=$(cat)
+
+# ── 1. 재진입 가드 ────────────────────────────────────────────────────
+if command -v jq >/dev/null 2>&1; then
+    ACTIVE=$(printf '%s' "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo false)
+else
+    case "$INPUT" in
+        *'"stop_hook_active"'*[Tt]rue*) ACTIVE=true ;;
+        *) ACTIVE=false ;;
+    esac
+fi
+if [ "$ACTIVE" = "true" ]; then
+    exit 0
+fi
+
+# ── 2. 프로젝트 루트 ──────────────────────────────────────────────────
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$ROOT" ]; then
+    ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+fi
+cd "$ROOT" || exit 0
+
+STAMP=".claude/.verify-stamp"
+
+# ── 3. 변경 감지 (소스 최신 수정시각) ─────────────────────────────────
+NEWEST=$(find ./VideoDownloader.* -type f \
+    \( -name '*.cs' -o -name '*.csproj' -o -name '*.xaml' -o -name '*.axaml' \) \
+    -not -path '*/bin/*' -not -path '*/obj/*' \
+    -printf '%T@\n' 2>/dev/null | sort -rn | head -1)
+
+# 소스를 못 찾으면(경로 이상 등) 훅이 개발을 막지 않도록 통과시킨다.
+if [ -z "$NEWEST" ]; then
+    exit 0
+fi
+
+if [ -f "$STAMP" ] && [ "$(cat "$STAMP" 2>/dev/null)" = "$NEWEST" ]; then
+    exit 0
+fi
+
+# ── 4. 검증 ───────────────────────────────────────────────────────────
+LOG=$(mktemp 2>/dev/null || echo "${TMPDIR:-/tmp}/vd-verify.$$")
+dotnet test VideoDownloader.Tests/VideoDownloader.Tests.csproj \
+    --nologo -v quiet >"$LOG" 2>&1
+CODE=$?
+
+if [ $CODE -eq 0 ]; then
+    printf '%s' "$NEWEST" > "$STAMP"
+    rm -f "$LOG"
+    exit 0
+fi
+
+# ── 5. 실패 → 종료 차단 ───────────────────────────────────────────────
+{
+    echo "검증 실패: dotnet test 가 통과하지 않았다. 테스트를 GREEN 으로 만들기 전에는 턴을 끝낼 수 없다."
+    echo "테스트를 삭제하거나 Skip 처리해서 통과시키지 말 것. 근본 원인을 고칠 것."
+    echo "---- dotnet test 출력 (마지막 60줄) ----"
+    tail -60 "$LOG"
+} >&2
+
+rm -f "$LOG"
+exit 2
--- a/.claude/rules/desktop-wpf.md
+++ b/.claude/rules/desktop-wpf.md
@ -0,0 +1,40 @@
+---
+paths:
+  - "VideoDownloader.App/**"
+  - "VideoDownloader.Browser/**"
+---
+
+# WPF · WebView2 영역 규칙
+
+## UI 스레드
+
+- WebView2·엔진 이벤트는 백그라운드 스레드에서 온다. UI 를 만지려면
+  `Dispatcher.BeginInvoke` 로 마샬링한다 (`MainWindow.xaml.cs` 전반의 기존 패턴).
+- 백그라운드에서 갱신되는 컬렉션은 `BindingOperations.EnableCollectionSynchronization`
+  으로 락을 등록한다 (`Core/DownloadManager.cs:58` 참조). 이걸 빼면 랜덤하게 죽는다.
+
+## dispose 이후 이벤트
+
+WebView2 가 dispose 된 뒤에도 이벤트 콜백이 도착한다. 콜백 안에서 `CoreWebView2` 를 만질 때는
+로컬 변수로 받아 null 을 확인하고 try 로 감싼다 — `UpdateNavState`(`MainWindow.xaml.cs:453`)가
+기준 패턴이다. 탭을 닫는 경로를 건드렸다면 이 방어를 반드시 확인한다.
+
+## 탭
+
+- Environment 는 전 탭 공유, WebView2 인스턴스는 탭마다. 이 구조를 바꾸지 않는다.
+- 팝업(`NewWindowRequested`)은 deferral 패턴으로 새 탭에 붙인다. 앱 통제를 벗어나게 두지 않는다.
+
+## 거대 파일
+
+`MainWindow.xaml.cs`(86KB) · `MainWindow.xaml`(55KB)은 통째로 읽지 않는다.
+Grep 으로 심볼 위치를 찾고 해당 구간만 Read 한다. 분할 리팩터링은 별도 승인 사항이다.
+
+## 프로세스 실행
+
+외부 프로세스는 문자열 인자 연결로 실행하지 않는다. `ProcessStartInfo` 에 인자를 배열로 넘긴다
+(과거 `explorer.exe` 인자 인젝션 취약점이 있었다).
+
+## 테스트 접근
+
+`VideoDownloader.App` 은 `InternalsVisibleTo("VideoDownloader.Tests")` 가 걸려 있다.
+테스트를 위해 멤버를 `public` 으로 승격하지 말고 `internal` 로 두면 된다.
--- a/.claude/rules/engine-core.md
+++ b/.claude/rules/engine-core.md
@ -0,0 +1,44 @@
+---
+paths:
+  - "VideoDownloader.Core/**"
+  - "VideoDownloader.Server/**"
+---
+
+# 엔진 · 서버 영역 규칙
+
+## 플랫폼 중립
+
+`Core` 는 `net8.0` 이다. WPF·Windows 전용 API 를 끌어들이지 않는다.
+Avalonia/MAUI 가 같은 엔진을 쓰므로 여기 들어간 Windows 의존은 크로스플랫폼 이관을 막는다.
+OS별 경로는 `Platform/CorePaths.cs` 를 통한다.
+
+## 외부 프로세스 (ffmpeg 등)
+
+`Platform/ProcessModels.cs` 의 실행 헬퍼를 쓴다. 직접 `Process.Start` 를 새로 쓰지 않는다.
+그 헬퍼가 보장하는 것들을 우회하면 과거 버그가 재발한다:
+
+- stdout/stderr **동시 드레인** — 안 읽으면 파이프 버퍼가 차서 ffmpeg 가 hang 한다
+- 취소·실패 시 `Kill(entireProcessTree: true)` — 안 하면 좀비 프로세스가 남는다
+- 인자는 배열 전달 — 문자열 연결 금지
+- exit code ≠ 0 이면 예외 — 조용히 넘어가면 실패가 `.ts` 잔재로만 드러난다
+
+## 취소
+
+모든 장기 작업은 `CancellationToken` 을 끝까지 전달한다. 중간에 삼키지 않는다.
+`Parallel.ForEachAsync` 는 `ParallelOptions.CancellationToken` 에 넣는다
+(`Hls/HlsDownloader.cs:77` 패턴).
+
+## 동시성
+
+세그먼트 병렬도는 `AppConfig.Concurrency`, 동시 다운로드 수는 `MaxConcurrentDownloads`(기본 3)로
+제어한다. 하드코딩된 병렬도를 새로 만들지 않는다 — 소켓 고갈로 이어진다.
+
+## 데이터 경로
+
+사용자 데이터는 `CorePaths` 를 통해서만 접근한다. `VD_DATA_DIR` 환경변수 오버라이드가
+E2E 테스트 격리의 공식 후크이므로, 경로를 직접 조립하면 테스트가 실사용자 폴더를 오염시킨다.
+
+## 서버
+
+`Server` 는 App 안에서 호스팅되는 라이브러리다. 포트 0 이면 빈 포트를 자동 할당한다.
+LAN 노출 API 이므로 인증·경로 검증을 우회하는 엔드포인트를 추가하지 않는다.
--- a/.claude/rules/mobile-maui.md
+++ b/.claude/rules/mobile-maui.md
@ -0,0 +1,40 @@
+---
+paths:
+  - "VideoDownloader.Mobile/**"
+  - "VideoDownloader.Mobile.Core/**"
+---
+
+# MAUI 모바일 영역 규칙
+
+## 로직은 Mobile.Core 로
+
+`VideoDownloader.Mobile` 은 `net10.0-android`(macOS 에서는 +`net10.0-ios`)이라
+`VideoDownloader.Tests`(net8.0-windows)가 참조할 수 없다. **테스트 가능한 로직은
+`VideoDownloader.Mobile.Core`(net8.0)에 둔다.** UI 프로젝트에는 화면 결선만 남긴다.
+
+새 기능을 UI 프로젝트에 통째로 넣으면 검증할 방법이 사라진다.
+
+## 링커 함정
+
+Release/링커 트리밍에서 참조가 정적으로 안 보이는 타입은 통째로 잘려나가고,
+**런타임 `FileNotFoundException` 으로만** 드러난다. 빌드는 통과한다.
+
+실제 사례: 모달 `NavigationPage` 가 크래시 → `Xamarin.AndroidX.LocalBroadcastManager` 를
+csproj 에 명시 참조해 해결. 리플렉션·XAML 로만 참조되는 타입을 쓸 때 이 함정을 의심한다.
+
+## 플랫폼 분기
+
+TFM 조건은 `$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'`
+형식으로 쓴다(csproj 기존 패턴). Windows 개발머신에는 iOS 워크로드가 없으므로
+iOS TFM 은 macOS 조건부로만 켠다 — 이 조건을 무조건부로 바꾸면 Windows 빌드가 깨진다.
+
+## 빌드 · 검증
+
+```powershell
+dotnet build VideoDownloader.Mobile -f net10.0-android
+```
+
+- MAUI 워크로드가 없으면 실패한다. 없는 환경이면 `Mobile.Core` 만 고치고
+  UI 결선은 워크로드가 있는 환경에서 확인하도록 사용자에게 알린다.
+- 화면 동작을 바꿨으면 에뮬레이터에 배포해 확인한 내용을 보고에 적는다.
+  단위 테스트만으로 "됐다"고 하지 않는다.
--- a/.claude/rules/tests.md
+++ b/.claude/rules/tests.md
@ -0,0 +1,44 @@
+---
+paths:
+  - "VideoDownloader.Tests/**"
+---
+
+# 테스트 영역 규칙
+
+## 배치
+
+`VideoDownloader.Tests/<영역>/<대상>Tests.cs` — 영역은
+`Browser` · `E2E` · `Infrastructure` · `Mobile` · `Platform` · `Server`.
+새 영역을 만들기 전에 기존 영역에 맞는지 먼저 본다.
+
+## 격리 (필수)
+
+사용자 데이터 경로를 건드리는 테스트는 `VD_DATA_DIR` 을 임시 디렉터리로 지정하고
+끝나면 `null` 로 되돌린다. `E2E/MainWindowSmokeE2ETests.cs:17` 이 기준 패턴이다.
+이걸 빼면 테스트가 실사용자의 설정·세션·프로필을 덮어쓴다.
+
+## WPF 테스트
+
+테스트 프로세스에는 `App.xaml` 리소스가 없다. WPF 요소를 만드는 테스트는
+`Infrastructure/WpfTestApp.Ensure(dispatcher)` 를 먼저 호출해 테마 사전을 로드한다.
+직접 `new Application()` 을 만들지 않는다.
+
+## 금지
+
+- 통과시키려고 테스트를 **삭제하거나 `Skip` 처리하지 않는다.** 회귀를 숨기는 것이다.
+- 실제 네트워크에 의존하는 단정을 새로 만들지 않는다. 외부 사이트가 바뀌면 무작위로 깨진다.
+  (`Cli` 의 `--dashparse` 같은 수동 검증 도구는 예외 — 테스트가 아니다.)
+- 시간·순서에 의존하는 `Thread.Sleep` 기반 단정을 쓰지 않는다.
+
+## 알려진 경고
+
+이 프로젝트에 남아 있는 경고: CS8602(null 역참조) 몇 건, xUnit1031(블로킹 대기),
+xUnit2013(`Assert.Equal` 로 개수 확인). **개수를 늘리지 않는다.**
+새 테스트에서는 `Assert.Single`/`Assert.Empty` 와 `async` 대기를 쓴다.
+
+## 실행
+
+```powershell
+dotnet test VideoDownloader.Tests                                        # 전체 (~13초)
+dotnet test VideoDownloader.Tests --filter "FullyQualifiedName~<이름>"   # 단건
+```
--- a/.claude/settings.json
+++ b/.claude/settings.json
@ -0,0 +1,52 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-brief.sh"],
+            "timeout": 30,
+            "statusMessage": "저장소 상태 브리핑…"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/verify-on-stop.sh"],
+            "timeout": 420,
+            "statusMessage": "dotnet test 검증 중…"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(dotnet build *)",
+      "Bash(dotnet test *)",
+      "Bash(dotnet restore *)",
+      "Bash(dotnet run *)",
+      "Bash(dotnet format *)",
+      "Bash(dotnet --*)",
+      "Bash(git status *)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git show *)",
+      "Bash(git branch *)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Edit(.env)",
+      "Write(.env)"
+    ]
+  }
+}
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@ -0,0 +1,53 @@
+---
+name: release
+description: VideoDownloader 배포 절차. Windows 설치자(x64/arm64) 생성과 macOS/Linux 원격 빌드머신 빌드를 수행한다. "배포", "설치자 만들어", "릴리스", "publish" 요청에 사용.
+---
+
+# 배포
+
+배포는 되돌리기 어렵다. **각 단계 전에 사용자 확인을 받는다.** 요청받지 않은 배포를 임의로 하지 않는다.
+
+## 0. 사전 점검 (필수)
+
+```powershell
+dotnet test VideoDownloader.Tests
+git status --short
+```
+
+- 테스트 실패가 있으면 배포하지 않는다.
+- 커밋되지 않은 변경이 있으면 사용자에게 알린다. 원격 빌드는 `git archive HEAD` 로 소스를 보내므로
+  **커밋되지 않은 변경은 원격 빌드에 반영되지 않는다.**
+
+## 1. Windows 설치자
+
+```powershell
+./build/publish.ps1 -Config Release -Version <버전>
+```
+
+- 하는 일: `VideoDownloader.App` 을 `win-x64`/`win-arm64` self-contained 로 publish (`publish/<arch>/`)
+  → Inno Setup 으로 설치자 컴파일 → `out/VideoDownloader-Setup-<arch>.exe`
+- 필요: **Inno Setup 6** (`winget install --id JRSoftware.InnoSetup -e`).
+  없으면 스크립트가 명시적으로 throw 한다.
+- 특정 아키텍처만: `-Archs x64`
+- arm64 첫 빌드는 yt-dlp/WebView2 런타임 관련으로 실패할 수 있다. 실패 메시지를 그대로 사용자에게 전달한다.
+- 완료 시 스크립트가 산출물 크기를 출력한다. **그 출력을 인용해 보고한다.**
+
+## 2. macOS / Linux 원격 빌드
+
+```bash
+bash build/remote/build-remote.sh all      # 또는 linux | mac
+```
+
+- 하는 일: `git archive HEAD` 로 현재 커밋 소스를 빌드머신에 SSH 전송 →
+  `Cli` + `Avalonia` 를 RID별 self-contained publish → `out/remote/<rid>/artifacts-<rid>.tar.gz` 수집
+- 자격 증명은 `.env` 의 `MAC_OS_HOST`/`LINUX_OS_HOST` 등을 쓴다.
+  **`.env` 내용을 읽어서 출력하거나 로그에 남기지 않는다.**
+- 빌드머신이 절전이면 SSH 가 끊긴다. 재연결 후 재시도한다.
+- Avalonia 12.1 은 빌드머신에 .NET 10 SDK 가 있어야 한다. 8만 있으면 CS0103 으로 실패한다.
+
+## 3. 배포 후
+
+- 산출물 경로와 크기를 보고한다.
+- `out/`, `publish/` 는 gitignore 대상이다. 커밋하지 않는다.
+- 릴리스 배포처(GitHub Releases 등)에 올리는 것은 **별도 승인 사항**이다. 임의로 업로드하지 않는다.
+- 배포 체계 전반은 `docs/DEPLOYMENT_PLAN.md` 참고.
--- a/.claude/skills/tdd/SKILL.md
+++ b/.claude/skills/tdd/SKILL.md
@ -0,0 +1,72 @@
+---
+name: tdd
+description: VideoDownloader 에서 기능을 추가하거나 버그를 고칠 때 쓰는 RED→GREEN→증거 폐쇄루프 절차. 실패 테스트를 먼저 만들고, 최소 구현으로 통과시키고, 실행 증거까지 남긴다. "기능 추가", "버그 수정", "TDD로", "테스트부터" 같은 작업에 사용.
+---
+
+# TDD 폐쇄루프
+
+이 저장소는 RED→GREEN→증거로 개발해 왔다. 이 순서를 건너뛰지 않는다.
+
+## 0. 기준선 확보 (건너뛰지 말 것)
+
+```powershell
+dotnet test VideoDownloader.Tests
+```
+
+지금 몇 개가 통과하는지 **숫자를 기록**한다. 이미 깨져 있다면 그것부터 사용자에게 알린다.
+내 변경으로 깨진 것과 원래 깨져 있던 것을 섞지 않기 위해 반드시 먼저 한다.
+
+## 1. RED — 실패를 먼저 본다
+
+고칠 동작을 **재현하는 테스트**를 쓴다.
+
+- 위치: `VideoDownloader.Tests/<영역>/<대상>Tests.cs`
+  (영역 = `Browser` · `E2E` · `Infrastructure` · `Mobile` · `Platform` · `Server`)
+- 순수 로직이면 `Core`/`Mobile.Core` 쪽으로 밀어 넣어 UI 없이 테스트되게 만든다.
+  WPF 의존이 꼭 필요하면 `Infrastructure/WpfTestApp.cs` 패턴을 따른다.
+- 사용자 데이터 경로를 건드리는 테스트는 `VD_DATA_DIR` 로 격리한다.
+
+```powershell
+dotnet test VideoDownloader.Tests --filter "FullyQualifiedName~<새테스트이름>"
+```
+
+**실패하는 것을 눈으로 확인한다.** 여기서 통과해 버리면 테스트가 대상을 못 잡고 있는 것이다.
+테스트를 고쳐서 진짜 실패하게 만든 다음 진행한다.
+
+## 2. GREEN — 최소 구현
+
+- 테스트를 통과시키는 가장 작은 변경만 한다. 겸사겸사 리팩터링하지 않는다.
+- 에러를 삼키지 않는다. 빈 `catch`, 가짜 폴백 금지. 근본 원인을 고친다.
+- 거대 파일(`MainWindow.xaml.cs` 86KB)은 Grep 으로 위치를 찾아 필요한 구간만 읽고 고친다.
+
+```powershell
+dotnet test VideoDownloader.Tests
+```
+
+**전체**가 통과해야 한다. 기준선보다 테스트 수가 줄면 무언가를 지운 것이다 — 되돌린다.
+
+## 3. 증거 — 테스트로 부족한 것
+
+UI·플랫폼 동작을 바꿨다면 테스트 GREEN 만으로는 "된다"는 근거가 아니다.
+
+| 바꾼 것 | 확인 방법 |
+|---|---|
+| WPF 화면·상호작용 | `dotnet run --project VideoDownloader.App` 로 실제 창을 띄워 확인 |
+| WebView2 감지·쿠키 | 실제 사이트를 열어 미디어가 목록에 잡히는지 확인 |
+| 서버 API | 앱 기동 후 해당 엔드포인트 호출 |
+| MAUI 화면 | Android 에뮬레이터에 배포해 확인 |
+| 다운로드 엔진 | `dotnet run --project VideoDownloader.Cli -- <검증 옵션>` |
+
+무엇을 어떻게 확인했는지 보고에 쓴다. "확인했습니다"만 쓰지 말고 관측한 내용을 쓴다.
+
+## 4. 마무리
+
+- `docs/BACKLOG.md` 해당 항목 `- [ ]` → `- [x]`
+- 계획 대비 구현 상태가 바뀌었으면 `docs/IMPLEMENTATION_AUDIT.md` 갱신
+- 보고에는 **실제 테스트 출력의 숫자**를 인용한다 (예: "164/164 통과"). 기억으로 쓰지 않는다.
+
+## 막혔을 때
+
+- 원인을 모르겠으면 추측으로 코드를 바꾸지 말고, 먼저 재현 범위를 좁히는 테스트를 더 쓴다.
+- 그래도 안 되면 무엇을 시도했고 무엇이 관측됐는지 정리해 사용자에게 보고한다.
+  통과하지 못한 것을 통과한 것처럼 쓰지 않는다.
--- a/.claude/skills/verify/SKILL.md
+++ b/.claude/skills/verify/SKILL.md
@ -0,0 +1,78 @@
+---
+name: verify
+description: VideoDownloader 변경사항이 완료 기준(Definition of Done)을 만족하는지 전수 점검한다. 빌드·테스트·경고·문서 동기화·산출물 오염까지 확인하고 통과/미통과를 판정한다. "다 됐나 확인", "검증해줘", "완료 기준 점검", 작업을 마무리하기 직전에 사용.
+---
+
+# 완료 검증
+
+작업을 "완료"로 보고하기 전에 아래를 순서대로 실행하고, 각 항목의 **실제 출력**을 근거로 판정한다.
+하나라도 실패하면 완료가 아니다. 고치거나, 못 고치는 이유를 명시한다.
+
+## 1. 테스트
+
+```powershell
+dotnet test VideoDownloader.Tests
+```
+
+- 실패 0건인가?
+- 통과 수가 작업 전보다 줄지 않았는가? (현재 기준선 164)
+- 새로 추가한 동작을 실제로 검증하는 테스트가 있는가? 없으면 지금 쓴다.
+
+## 2. 빌드 · 경고
+
+```powershell
+dotnet build VideoDownloader.App
+```
+
+- 오류 0인가?
+- **내가 새로 만든 경고가 있는가?** 기존 경고(`MainWindow.xaml.cs`·테스트의 CS8602 몇 건,
+  xUnit 분석기 경고)는 알려진 것이다. 개수가 늘었으면 내가 늘린 것이다 — 고친다.
+
+모바일을 건드렸다면 (MAUI 워크로드가 설치돼 있을 때):
+
+```powershell
+dotnet build VideoDownloader.Mobile -f net10.0-android
+```
+
+## 3. 실행 증거
+
+UI·플랫폼 동작을 바꿨는데 실행해 보지 않았다면 여기서 멈추고 실행한다.
+`/tdd` 스킬의 "3. 증거" 표를 따른다. 무엇을 관측했는지 기록한다.
+
+## 4. 저장소 위생
+
+```powershell
+git status --short
+```
+
+- 산출물(`out/`, `publish/`, `bin/`, `obj/`)이 변경 목록에 보이는가? → `.gitignore` 가 뚫린 것이다.
+- `.env` 가 보이는가? → **즉시 멈추고 사용자에게 알린다.** 실제 자격 증명이 들어 있다.
+- 의도하지 않은 파일이 섞였는가?
+
+```powershell
+git diff --stat
+```
+
+- 변경 규모가 작업 범위와 맞는가? 요청하지 않은 리팩터링이 섞이지 않았는가?
+
+## 5. 문서 동기화
+
+- `docs/BACKLOG.md` — 완료 항목 체크박스 반영했는가?
+- `docs/IMPLEMENTATION_AUDIT.md` — 계획 대비 구현 상태가 바뀌었으면 갱신했는가?
+- 명령·구조·규약이 바뀌었으면 `AGENTS.md` 와 `README.md` 도 갱신했는가?
+
+## 6. 판정 보고
+
+아래 형식으로 사용자에게 보고한다. **실제 출력에서 숫자를 인용한다.**
+
+```
+검증 결과
+- 테스트: <통과>/<전체> 통과, 실패 <n>건
+- 빌드: 오류 <n>, 신규 경고 <n>
+- 실행 증거: <무엇을 어떻게 확인했는지 / 해당 없음>
+- 저장소: 변경 <n>건, 산출물 오염 없음
+- 문서: <갱신한 파일 / 갱신 불필요>
+판정: 완료 | 미완료(사유: …)
+```
+
+미통과 항목을 숨기거나 완곡하게 쓰지 않는다.