AI에게 동영상 제작 파이프라인 설계시키기 — 프롬프트로 아키텍처까지

· shortsmaker · 0
#python#typescript

5,800줄 코드를 4번 커밋으로 만들었다. AI에게 영상 제작 파이프라인 전체를 설계하고 구현하게 한 결과다. 이 글에서는 복잡한 아키텍처를 AI에게 맡길 때 쓴 프롬프팅 전략과 구조화 패턴을 다룬다.

배경: 무엇을 만들고 있는가

ShortsMaker는 사주 데이터를 받아서 숏폼 영상을 자동으로 만드는 파이프라인이다. Python으로 데이터 처리하고, React + Remotion으로 렌더링한다. 사주 프로필 JSON을 넣으면 9:16 비율 영상이 나온다.

이번 작업의 목표는 전체 아키텍처를 밑바닥부터 구축하는 것이었다. CLI 인터페이스, 작업 큐 시스템, 다국어 지원, 렌더링 엔진까지 한번에 만들어야 했다.

아키텍처를 프롬프트로 끌어내는 법

복잡한 시스템을 AI에게 설계시킬 때 가장 중요한 건 제약 조건을 먼저 정의하는 것이다. 기능 요구사항만 던지면 AI는 과도하게 복잡하거나 현실성 없는 구조를 만든다.

효과적인 프롬프트는 이렇게 시작한다:

“Python CLI 도구로 영상 제작 파이프라인을 만들어. 제약 조건:

  • 단일 프로세스에서 작동 (분산 시스템 금지)
  • 외부 API 의존성 최소화
  • 5분 안에 설치 가능해야 함
  • 개발자가 아닌 사람도 쓸 수 있어야 함

입력: 사주 JSON 파일 출력: 9:16 비율 MP4 영상

기술 스택: Python 3.11+, React, Remotion, TypeScript”

이렇게 쓰면 안 된다:

“사주 영상 만드는 프로그램 만들어줘”

제약 조건이 없으면 AI는 Kubernetes, Redis, 메시지 큐 등 과한 기술을 제안한다. 단순함이 복잡함보다 어렵다. AI에게도 마찬가지다.

파일 구조 먼저 확정하기

아키텍처 설계에서 핵심은 파일 구조를 먼저 AI와 합의하는 것이다. 코드 작성 전에 이런 프롬프트를 썼다:

“이 파이프라인의 최적 디렉토리 구조를 제안해. 조건:

  • src/shortsmaker/에 Python 코드
  • renderer/에 React/Remotion 코드
  • input/, output/ 폴더로 데이터 분리
  • 테스트, 문서, 설정 파일 위치까지

각 파일의 역할을 한 줄로 설명해.”

AI가 제안한 구조를 보고 수정 요청한다:

“hooks.py 대신 pipeline.py로 바꿔. hook이라는 용어가 React와 혼동될 수 있어. languages.py는 i18n.py로 통합해.”

이렇게 구조를 먼저 확정하면 AI가 일관된 코드를 생성한다. 파일 간 의존성도 명확해진다.

Claude Code로 멀티 언어 스택 다루기

이 프로젝트는 Python과 TypeScript 두 언어를 쓴다. Claude Code에서 멀티 언어 프로젝트를 다룰 때 쓴 전략들이다.

CLAUDE.md 설정법

프로젝트 루트에 CLAUDE.md를 만들어서 컨텍스트를 통일했다:

# ShortsMaker

사주 데이터를 입력받아 숏폼 영상을 생성하는 파이프라인.

## 아키텍처

- `src/shortsmaker/`: Python CLI 및 비즈니스 로직
- `renderer/`: React + Remotion 렌더링 엔진
- 데이터 플로우: JSON → Python 처리 → TypeScript 렌더링 → MP4

## 기술 제약

- Python 3.11+, 외부 서비스 의존성 금지
- Remotion 4.x, 로컬 렌더링만
- 9:16 세로 영상, 30-60초 길이

## 현재 우선순위

1. CLI 인터페이스 완성
2. job 시스템 안정화  
3. 렌더링 파이프라인 연결

이 파일이 있으면 AI가 프로젝트 전체 맥락을 유지하면서 코드를 생성한다. 새로운 대화를 시작할 때마다 컨텍스트를 다시 설명할 필요가 없다.

언어별 작업 분리 전략

Python과 TypeScript를 한번에 작업하면 AI가 혼동한다. 언어별로 세션을 나눴다:

Python 세션:

“Python 파트만 집중해. src/shortsmaker/cli.py에서 job을 생성하고, job.py에서 처리하는 로직 완성해. TypeScript 렌더링은 신경쓰지 마.”

TypeScript 세션:

“이제 Remotion 렌더링 구현해. Python에서 넘겨받을 JSON 스키마는 이거야: [스키마 제공]. React 컴포넌트로 사주 정보를 시각화해.”

언어를 섞어서 작업하면 import 구문, 타입 시스템, 패키지 관리자를 AI가 헷갈린다. 분리하는 게 효율적이다.

job 시스템으로 복잡도 관리하기

영상 제작은 여러 단계로 나뉜다: 데이터 검증 → 스크립트 생성 → 렌더링 → 후처리. AI에게 이 전체를 한번에 시키면 실패한다. 대신 job 시스템으로 쪼갰다.

상태 기반 프롬프팅

각 job의 상태를 명확히 정의하고, AI에게 상태 전환 로직만 작성하게 했다:

“Job 상태는 5가지야: pending, processing, rendering, completed, failed.

job.py에서 각 상태별로 다음 단계를 실행하는 메서드 만들어:

  • process_pending(): 입력 데이터 검증
  • start_rendering(): Remotion 렌더링 시작
  • handle_completion(): 결과 파일 정리

실패 시 롤백 로직도 필요해.”

이렇게 쪼개면 AI가 각 단계에 집중할 수 있다. 전체 플로우는 사람이 설계하고, 구현 세부사항만 AI가 담당한다.

에러 처리 패턴

영상 렌더링은 실패할 확률이 높다. AI에게 견고한 에러 처리를 시키려면 구체적인 실패 시나리오를 제시해야 한다:

“이런 에러 상황들을 처리해:

  1. 입력 JSON에 필수 필드가 없을 때
  2. Remotion 렌더링이 중간에 멈출 때
  3. 디스크 공간이 부족할 때
  4. 권한 없는 디렉토리에 쓰려고 할 때

각각에 대해 명확한 에러 메시지와 복구 방법 제시해.”

막연하게 “에러 처리해줘”라고 하면 generic한 try-catch만 만든다. 구체적 시나리오를 주면 실용적인 코드가 나온다.

Remotion 컴포넌트를 프롬프트로 만들기

React 컴포넌트를 AI에게 시킬 때는 시각적 결과물을 글로 명확히 묘사하는 게 핵심이다.

레이아웃 중심 프롬프팅

UI 코드를 생성할 때 이런 식으로 접근했다:

“9:16 세로 화면에서 사주 정보를 보여주는 React 컴포넌트 만들어.

레이아웃:

  • 상단 1/4: 제목과 이름 (큰 폰트)
  • 중간 1/2: 사주 팔자표 (4x2 그리드)
  • 하단 1/4: 핵심 해석 (스크롤 텍스트)

컬러 스킴: 전통적인 한국 색감 (빨강, 파랑, 노랑) 폰트: 한글 가독성 최우선

Remotion의 spring() 애니메이션 적용해.”

이렇게 구체적으로 설명하면 AI가 실제 쓸 만한 컴포넌트를 만든다. “예쁘게 만들어줘”같은 주관적 요청은 효과가 없다.

타입 스키마 먼저 정의

TypeScript 컴포넌트를 만들 때는 props 타입을 먼저 확정했다:

“먼저 사주 데이터 타입 정의해:

interface SajuProfile {
  name: string;
  birthDate: string;
  gender: 'M' | 'F';
  elements: {
    year: string;
    month: string;
    day: string;
    hour: string;
  };
  fortune: {
    overall: string;
    career: string;
    love: string;
  };
}

이 타입 기준으로 컴포넌트 만들어.”

타입을 먼저 정의하면 AI가 일관된 데이터 구조를 사용한다. Python JSON과 TypeScript 인터페이스 간 불일치도 방지할 수 있다.

CLI 인터페이스 설계 전략

CLI 도구를 AI에게 만들게 할 때는 사용자 경험 시나리오를 구체적으로 제시해야 한다.

실제 사용 예시로 프롬프팅

“CLI 인터페이스 만들어. 실제 사용 예시:

# 기본 사용
shortsmaker create input/profiles/john.json

# 출력 디렉토리 지정
shortsmaker create input/profiles/john.json --output /tmp/videos/

# 작업 상태 확인
shortsmaker status

# 특정 job 모니터링
shortsmaker watch job_abc123

argparse로 구현하고, help 메시지도 친절하게 만들어.”

이렇게 실제 커맨드 예시를 주면 AI가 실용적인 CLI를 만든다. 옵션명, 인자 순서, 에러 메시지까지 일관성 있게 나온다.

진행상황 표시 패턴

영상 렌더링은 시간이 오래 걸린다. 사용자가 진행상황을 볼 수 있어야 한다:

“긴 작업에 대해 진행률 표시해. 요구사항:

  • tqdm 라이브러리 사용
  • 단계별 진행률 (검증 20%, 렌더링 70%, 후처리 10%)
  • 예상 완료 시간 표시
  • Ctrl+C로 깨끗하게 중단 가능

터미널에서 보기 좋게 포맷팅해.”

AI는 기본적으로 최소한의 피드백만 제공한다. 명시적으로 UX 요구사항을 줘야 사용자 친화적인 도구가 나온다.

더 나은 방법은 없을까

이번 작업에서 쓴 방법들보다 더 효율적인 접근법들이 있다.

MCP 서버 활용

현재는 각 언어별로 세션을 나눠서 작업했지만, MCP(Model Context Protocol) 서버를 쓰면 더 좋다. 프로젝트 전체 컨텍스트를 유지하면서 여러 언어를 동시에 다룰 수 있다.

특히 @codebase MCP 서버를 연결하면:

  • 파일 간 의존성을 AI가 자동으로 추적
  • 타입 불일치를 실시간으로 체크
  • 리팩토링 시 영향 범위를 정확히 파악

Cursor Composer 패턴

복잡한 아키텍처를 설계할 때는 Cursor의 Composer 기능이 더 적합할 수도 있다. 멀티 파일 편집과 코드 생성을 동시에 할 수 있어서, 파이프라인 같은 연결된 시스템을 만들 때 유리하다.

점진적 복잡도 증가

이번에는 처음부터 전체 아키텍처를 설계했지만, MVP부터 시작해서 점진적으로 확장하는 게 더 안전하다. AI에게 단순한 버전을 먼저 만들게 하고, 동작 확인 후 기능을 추가하는 방식이다.

테스트 주도 프롬프팅

AI에게 기능 구현을 시키기 전에 테스트 케이스를 먼저 작성하게 하면 더 견고한 코드가 나온다. 특히 파이프라인 같은 복잡한 시스템에서는 각 단계별 테스트가 중요하다.

정리

  • 복잡한 시스템을 AI에게 맡길 때는 제약 조건부터 명확히 하라
  • 파일 구조를 먼저 합의하고 코드를 생성하라
  • 멀티 언어 프로젝트는 언어별로 세션을 나눠라
  • job 시스템으로 복잡한 워크플로우를 상태 기반으로 쪼개라
  • UI 컴포넌트는 시각적 결과를 구체적으로 묘사하라
  • CLI 도구는 실제 사용 시나리오를 예시로 제시하라
이번 작업의 커밋 로그

6cc0e4f — gpt-5-codex: log sample short validation d6e1582 — gpt-5-codex: fix repo-relative cli paths
07e6f61 — gpt-5-codex: build saju shorts pipeline 65f233a — gpt-5-codex: bootstrap project workspace

댓글 0

0 / 1000