MCP 설정 — 스케줄러 아키텍처 문서화

이번 주는 기능 개발보다는 실제 코드와 문서 사이에 벌어진 간극을 좁히는 작업이 주를 이뤘다.

MCP 설정 정리

.mcp.json에서 aws-serverless 서버 항목을 완전히 제거했다. 이미 사용하지 않고 있었는데 설정 파일에만 남아 있던 상태였다.

동시에 npx -y로 실행되던 playwright, terraform, sentry 서버들을 pnpm dlx로 통일했다. 패키지 매니저를 섞어 쓰면 캐시도 따로 관리되고 버전 동작이 미묘하게 달라지는 경우가 있다. 한 번 겪고 나면 그냥 통일하게 된다.

shrimp-task-manager는 원격 패키지 실행 대신 로컬 빌드 결과물(dist/index.js)을 직접 참조하도록 바꿨다. 자주 수정하는 도구라 매번 원격에서 받아오는 게 비효율적이었다.

스케줄러 아키텍처 문서화

schedulerEnabled 플래그가 켜진 채널에 대해 매 분 자동으로 Job을 생성하는 NestJS 인-프로세스 스케줄러(@Cron)를 구현해 뒀었는데, 아키텍처 문서에 반영하지 않았었다. 이번에 project-structure.md에 scheduler/ 모듈을 추가하고, overview.md에 동작 방식을 설명했다.

로드맵에는 P2-10을 완료 처리하면서 P4-1에 EventBridge로 교체 예정이라는 내용도 함께 명시했다. 현재 인-프로세스 방식은 단일 인스턴스 환경에서 충분히 동작하지만, 스케일아웃 시 중복 실행 문제가 생기기 때문에 나중에 외부 스케줄러로 이전할 계획이다.

기타 문서 정확도 개선

파이프라인 문서에서 tts-worker가 생성하는 subtitle.vtt의 S3 출력 항목이 누락되어 있던 걸 .claude/rules/worker-pipeline.md와 docs/architecture/pipeline-flow.md 양쪽에 보완했다. 썸네일 생성 설명도 "3초 프레임"에서 "FFmpeg -vframes 1 첫 프레임"으로 정정했다.

모니터링 문서의 폴링 간격 설명도 단순 "2초"에서 적응형 동작으로 수정했다. 진행 중인 Job이 있으면 2초, 모두 완료·실패 상태면 30초로 전환되는 실제 동작인데, 문서에는 그냥 "2초"라고만 적혀 있었다.

문서 업데이트는 우선순위에서 계속 밀리는 경향이 있다. 그렇게 차이가 쌓이면 나중에 미래의 나 자신이 혼란스러워진다. 틈틈이 맞춰두는 편이 낫다.