releases/AGENTS.md

# AGENTS.md — VideoDownloader 에이전트 작업 계약

이 파일은 도구 중립 표준(AGENTS.md)이다. Claude Code · Codex · Cursor 등 어떤 코딩 에이전트든
작업 시작 시 이 파일을 읽고, 여기 적힌 명령·규약·완료 기준을 따른다.
Claude Code 는 `CLAUDE.md` 가 이 파일을 `@AGENTS.md` 로 임포트해 함께 읽는다.

## 1. 프로젝트 개요

브라우저 내장 데스크톱 영상 다운로더 + 모바일 컴패니언. 앱 내 브라우저가 재생 중인 미디어
(HLS/DASH/MP4)를 감지 → 쿠키·Referer 를 물려받아 다운로드 → 내장 서버로 휴대폰에 스트리밍/전송.

| 프로젝트 | TFM | 역할 |
|---|---|---|
| `VideoDownloader.Core` | net8.0 | 다운로드 엔진 (HLS/DASH 파싱, AES-128, 병렬·이어받기, 감지, ffmpeg 리먹스) |
| `VideoDownloader.Browser` | net8.0-windows | WebView2 탭 컴포넌트 |
| `VideoDownloader.App` | net8.0-windows | 메인 WPF 앱 (브라우저 + 다운로드 UI + 서버 호스팅) |
| `VideoDownloader.Server` | net8.0 | ASP.NET 라이브러리. App 안에서 기동, 모바일/웹에 API 제공 |
| `VideoDownloader.Mobile` | net10.0-android (+ios on macOS) | MAUI 컴패니언 |
| `VideoDownloader.Mobile.Core` | net8.0 | 모바일 공용 로직 (UI 없이 테스트 가능하게 분리) |
| `VideoDownloader.Avalonia` | net8.0 | macOS/Linux 셸 (진행 중) |
| `VideoDownloader.Cli` | net8.0 | 엔진 검증용 개발 도구 |
| `VideoDownloader.Tests` | net8.0-windows | xUnit. Mobile 을 제외한 전 영역 + E2E |

## 2. 명령 (이 명령들이 진실이다 — 추측하지 말 것)

```powershell
dotnet test VideoDownloader.Tests            # 전체 검증. 증분 ~13초, 현재 180/180 통과
dotnet build VideoDownloader.App             # 데스크톱 빌드
dotnet run --project VideoDownloader.App     # 데스크톱 실행
dotnet build VideoDownloader.Mobile -f net10.0-android   # 모바일 (MAUI 워크로드 필요)
./build/publish.ps1 -Config Release -Version 1.0.0       # Windows 설치자 → out/
bash build/remote/build-remote.sh all                    # macOS/Linux 원격 빌드 → out/remote/
```

- 솔루션 전체 빌드(`dotnet build VideoDownloader.slnx`)는 MAUI 워크로드가 있어야 통과한다.
  워크로드 없이 작업할 땐 프로젝트를 개별 지정한다.
- 단위 테스트 하나만: `dotnet test VideoDownloader.Tests --filter "FullyQualifiedName~HlsMuxerWiring"`
- 환경: Windows 11 · .NET 8/10 SDK 공존 · ffmpeg PATH 필요 · 셸은 PowerShell 7 (Git Bash 도 사용 가능)

## 3. 작업 방식 — TDD 폐쇄루프

이 저장소는 **RED → GREEN → 증거** 사이클로 개발해 왔다. 이 순서를 지킨다.

1. **RED**: 변경 전에 실패하는 테스트를 먼저 쓴다. 실패를 눈으로 확인한다.
2. **GREEN**: 최소 구현으로 통과시킨다. `dotnet test` 전체가 통과해야 한다.
3. **증거**: UI·플랫폼 동작을 바꿨다면 테스트만으로 부족하다. 실제 앱 실행/에뮬레이터/스크린샷으로
   확인하고, 무엇을 어떻게 확인했는지 보고에 적는다.
4. **문서 동기화**: 계획 대비 구현 상태는 `docs/IMPLEMENTATION_AUDIT.md`, 작업 항목은
   `docs/BACKLOG.md` 체크박스에 반영한다.

## 4. 완료 기준 (Definition of Done)

아래를 모두 만족하기 전에는 "완료"라고 보고하지 않는다.

- [ ] `dotnet test VideoDownloader.Tests` — **실패 0건**. 테스트 수는 줄지 않는다(180 이상).
- [ ] 빌드 **오류 0**. 새로 만든 경고를 남기지 않는다.
      (기존 경고: `MainWindow.xaml.cs`·테스트의 CS8602 몇 건, xUnit 분석기 경고 — 늘리지 말 것)
- [ ] 동작을 바꿨으면 그 동작을 검증하는 테스트가 있다.
- [ ] UI/플랫폼 변경이면 실행 증거가 있다.
- [ ] 관련 문서(`docs/`)를 갱신했다.

실패한 것을 통과한 것처럼 보고하지 않는다. 막혔으면 막혔다고 쓴다.

## 5. 코드 규약

- **C#**: file-scoped namespace, 4스페이스, Allman 중괄호, `_camelCase` private 필드, nullable enable.
  세부는 `.editorconfig` 가 강제한다. 공통 빌드 속성은 `Directory.Build.props`.
- **주석·커밋 메시지·문서는 한국어.** 기존 코드가 한국어 주석이므로 섞지 않는다.
- **테스트**: xUnit. 파일은 `VideoDownloader.Tests/<영역>/<대상>Tests.cs`.
  영역 = `Browser` · `E2E` · `Infrastructure` · `Mobile` · `Platform` · `Server`.
- 에러를 삼키지 않는다. 근본 원인을 고친다. 빈 `catch`, 가짜 폴백 데이터 금지.

## 6. 경계 — 하지 말 것

- `.env` 를 커밋하거나 그 값을 출력·로그·문서에 남기지 않는다. 실제 Cloudflare 토큰과
  빌드머신 SSH 비밀번호가 들어 있다. 템플릿은 `.env.example` 만 추적한다.
- `out/`, `publish/`, `bin/`, `obj/` 는 산출물이다. 커밋하지 않고, 내용을 소스로 참조하지 않는다.
- `VideoDownloader.App/Assets/*.min.js`(hls/dash/readability)는 서드파티 번들이다. 수정 금지.
- 사용자가 요청하지 않은 커밋·푸시·배포를 하지 않는다.
- 대규모 리팩터링을 임의로 시작하지 않는다. `MainWindow.xaml.cs` 는 86KB 로 비대하지만,
  분할은 별도 승인 후 진행한다.

## 7. 알아둘 함정

- **WebView2**: 탭마다 인스턴스, Environment 는 공유. dispose 순서를 어기면 UI 스레드에서 죽는다.
- **MAUI**: 링커가 안 싣는 타입은 런타임 `FileNotFoundException` 으로만 드러난다
  (실제 사례: 모달 NavigationPage → `Xamarin.AndroidX.LocalBroadcastManager` 명시 참조로 해결).
- **ffmpeg**: stderr 를 읽지 않으면 파이프 버퍼가 차서 hang 한다. 취소 시 `Kill(entireProcessTree)`.
- **Avalonia 12.1** 은 .NET 10 SDK 를 요구한다. 8만 있으면 CS0103 으로 실패한다.
- 테스트는 `VD_DATA_DIR` 로 사용자 데이터 경로를 격리한다. 실제 사용자 폴더를 건드리지 않는다.