문서 동기화 — 아키텍처·온보딩·운영 현행화

5월 중순부터 6월 초까지 파이프라인 변경이 꽤 쌓였는데, 문서가 따라가지 못한 상태였다.

faster-whisper 제거, Gemini 2.0 → 2.5 Flash 업그레이드, Pexels+zoompan 통합, subtitle-worker 메모리 증설. 실질적인 변경들이었는데, 문서에는 여전히 구버전 내용이 남아 있었다.

ADR 업데이트

ADR 001에서 subtitle-worker를 Fargate에 유지하는 근거가 "모델 메모리"로 적혀 있었는데, faster-whisper를 제거했으니 이 이유는 틀린 말이 됐다. "SQS Long Polling 상시 실행"이 정확한 이유라서 그렇게 수정했다. ADR 008은 whisper-model이 Superseded 상태임을 명시했다.

아키텍처 문서

docs/architecture/pipeline-flow.md에서 썸네일 추출 설명이 "3초 프레임"으로 되어 있었는데, 실제 구현은 FFmpeg -vframes 1 첫 프레임이다. 이런 작은 오류들이 쌓이면 나중에 코드 읽는 사람이 혼란스러워진다. overview.md에는 GET /jobs/:id/thumbnail 엔드포인트도 누락된 항목으로 추가했다.

온보딩 정리

faster-whisper를 제거했으니 local-setup.md에서 python3 요구사항도 삭제했다. env-vars.md에서는 PYTHON_PATH를 미사용 변수로 주석 처리하고 API_INTERNAL_SECRET 설명을 보완했다.

운영 문서

monitoring.md에서 SQL 쿼리 컬럼명이 failure_reason으로 되어 있었는데, Prisma 네이밍 때문에 실제 PostgreSQL 컬럼은 fail_reason이다. 모니터링 쿼리 직접 실행하면 바로 에러가 나는 부분이라 우선순위를 높여 수정했다.

-- 수정 전
SELECT failure_reason, COUNT(*) FROM jobs ...
-- 수정 후
SELECT fail_reason, COUNT(*) FROM jobs ...

루트 README는 302줄에서 48줄로 줄이고 상세 내용은 docs/ 하위로 옮겼다. 신규 입사자가 README만 보고 전체를 파악하려다가 오래된 내용에 혼란스러워하는 상황을 줄이기 위한 목적이었다.

앱별 CLAUDE.md도 소스 기준으로 맞췄다. subtitle-worker 메모리가 Terraform 실제값 기준 8GB인데 4GB로 적혀 있던 부분, script 필드 최대 길이가 260자 → 350자로 늘어난 부분 등 AI 에이전트가 잘못된 스펙을 보고 작업하는 일이 없도록 정확한 값으로 수정했다.

코드가 바뀌면 문서도 같이 바뀌어야 한다. 당연한 말이지만, 실제로 지키기가 제일 어렵다.