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. 명령 (이 명령들이 진실이다 — 추측하지 말 것)

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 → 증거 사이클로 개발해 왔다. 이 순서를 지킨다.

RED: 변경 전에 실패하는 테스트를 먼저 쓴다. 실패를 눈으로 확인한다.
GREEN: 최소 구현으로 통과시킨다. dotnet test 전체가 통과해야 한다.
증거: UI·플랫폼 동작을 바꿨다면 테스트만으로 부족하다. 실제 앱 실행/에뮬레이터/스크린샷으로 확인하고, 무엇을 어떻게 확인했는지 보고에 적는다.
문서 동기화: 계획 대비 구현 상태는 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 로 사용자 데이터 경로를 격리한다. 실제 사용자 폴더를 건드리지 않는다.

5.9 KiB Raw Blame History