GPT-5-codex로 Python-React 파이프라인 만들기 — 큰 작업을 쪼개는 프롬프팅 전략

사주 데이터를 받아서 쇼츠 영상으로 만드는 파이프라인을 4일 만에 구축했다. Python CLI에서 Remotion React 컴포넌트까지, 5800줄이 넘는 코드를 GPT-5-codex와 함께 작성했다. 이 글에서는 대규모 프로젝트를 AI에게 맡길 때 어떤 프롬프팅 패턴이 효과적인지, 어떻게 컨텍스트를 유지하면서 일관성 있는 코드베이스를 만들 수 있는지 다룬다.

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

ShortsMaker는 사주 분석 데이터를 입력받아서 틱톡/유튜브 쇼츠용 세로 동영상을 자동 생성하는 도구다. Python으로 데이터 처리와 CLI를 만들고, Remotion으로 React 기반 비디오 렌더링을 한다.

이번 작업의 목표는 명확했다. 프로젝트 초기 셋업부터 실제 동작하는 파이프라인까지 한 번에 구축하는 것. 단순히 코드만 생성하는 게 아니라, 확장 가능한 아키텍처와 테스트까지 포함해서.

프로젝트 구조를 먼저 정의하게 하기

대규모 작업을 AI에게 시킬 때 가장 중요한 건 구조부터 잡는 것이다. 바로 코딩에 들어가면 나중에 꼬인다.

효과적인 프롬프트:

"사주 데이터를 받아서 쇼츠 영상을 생성하는 파이프라인을 만들어야 한다. Python CLI + Remotion React 구조로. 먼저 전체 아키텍처를 설계하고, 디렉토리 구조와 핵심 모듈들의 역할을 정의해줘. 코드는 아직 쓰지 마."

이렇게 하면 안 된다:

"사주 쇼츠 만드는 앱 코딩해줘"

첫 번째 프롬프트의 결과로 ARCHITECTURE.md와 PROJECT_BRIEF.md가 나왔다. 28줄이 추가되고 15줄이 수정된 걸 보면, AI가 기존 구조를 검토하면서 더 나은 설계로 개선한 것을 알 수 있다.

핵심은 "코드는 아직 쓰지 마"라는 제약이다. AI는 바로 구현하려는 성향이 있는데, 설계 단계에서는 이를 막아야 한다.

모듈별 구현을 순차적으로 진행하는 법

전체 구조가 잡히면, 이제 각 모듈을 하나씩 구현한다. 여기서 중요한 건 의존성 순서를 지키는 것이다.

내가 사용한 순서:

1. models.py - 데이터 구조 정의
2. config.py - 설정 관리
3. languages.py - 다국어 처리
4. job.py - 작업 로직
5. hooks.py - 확장 포인트
6. cli.py - 사용자 인터페이스

각 모듈을 만들 때 사용한 프롬프트 패턴:

"models.py를 구현해줘. 사주 데이터 구조는 다음과 같다: [샘플 데이터]. Pydantic을 사용하고, validation 로직도 포함해. 다른 모듈은 건드리지 마."

"다른 모듈은 건드리지 마"가 핵심이다. AI는 연관된 파일을 함께 수정하려 하는데, 이렇게 하면 컨텍스트가 꼬인다. 한 번에 하나의 모듈만 집중하게 만들어야 한다.

TypeScript 컴포넌트 생성 시 스타일 가이드 강제하기

React 컴포넌트를 만들 때는 더 구체적인 제약이 필요했다. Remotion은 특별한 API를 사용하기 때문이다.

효과적인 프롬프트:

"Remotion용 ShortsComposition.tsx 컴포넌트를 만들어줘. 9:16 세로 비율, 1080x1920 해상도. 사주 데이터를 받아서 텍스트 애니메이션으로 표시한다. 다음 규칙을 지켜:

1. useCurrentFrame(), useVideoConfig() 사용
2. 애니메이션은 interpolate() 함수로
3. 컴포넌트는 5초 길이
4. 폰트는 시스템 기본 사용
5. 타입 정의는 별도 types.ts에"

이 프롬프트로 194줄의 완전한 컴포넌트가 나왔다. 타입 정의도 37줄로 별도 파일에 깔끔하게 분리됐다.

규칙을 번호로 나열하는 게 포인트다. AI가 각 조건을 체크리스트처럼 확인할 수 있다.

테스트 코드를 함께 작성하게 하는 법

기능 구현과 동시에 테스트도 만들어야 한다. 하지만 테스트를 나중에 추가하라고 하면 대충 만든다.

좋은 방법:

"CLI 명령어를 구현할 건데, 먼저 테스트 케이스를 정의해줘. pytest 사용하고, 다음 시나리오들을 커버해:

1. 유효한 사주 파일 처리
2. 잘못된 파일 형식 에러 핸들링
3. 출력 디렉토리 생성
4. 로그 검증

테스트 코드를 먼저 보여준 다음에 CLI 구현해."

이렇게 하면 TDD 방식으로 진행된다. test_cli.py에 25줄이 추가된 것을 보면, 각 기능에 대한 테스트가 제대로 만들어진 걸 알 수 있다.

파일 경로 처리의 함정과 해결법

Python과 Node.js가 섞인 프로젝트에서 가장 까다로운 부분이 경로 처리다. 커밋 메시지 fix repo-relative cli paths에서 보듯이, 이 부분에서 문제가 생겼다.

AI에게 경로 관련 코드를 시킬 때 반드시 포함해야 할 제약:

"파일 경로 처리할 때 다음 원칙을 지켜:

1. 절대 하드코딩하지 마
2. pathlib.Path 사용 (Python)
3. path.resolve() 사용 (Node.js)
4. OS별 경로 구분자 고려
5. 현재 작업 디렉토리 기준으로 상대 경로 계산"

이런 제약 없이 그냥 "경로 처리해줘"라고 하면 십중팔구 하드코딩한다. AI는 컨텍스트 없이는 최단 경로로 동작하려 한다.

validation 로직을 점진적으로 강화하기

log sample short validation 커밋에서 보듯이, 검증 로직은 한 번에 완성되지 않는다. 점진적으로 강화해야 한다.

1단계 프롬프트:

"사주 데이터의 기본 구조만 검증해. 필수 필드가 있는지만 체크"

2단계 프롬프트:

"이제 데이터 범위도 검증해. 생년월일이 유효한지, 시간 형식이 올바른지 체크"

3단계 프롬프트:

"로그 샘플을 만들어서 실제 검증이 동작하는지 테스트해. 성공/실패 케이스 모두"

한 번에 완벽한 validation을 만들어달라고 하면 오히려 복잡하고 버그 많은 코드가 나온다. 단계적으로 요구사항을 늘려가는 게 효과적이다.

더 나은 방법은 없을까

이번 작업에서 아쉬웠던 부분과 개선 방안들을 살펴본다.

CLAUDE.md 활용 부족: 프로젝트 루트에 CLAUDE.md를 두고 코딩 컨벤션, 아키텍처 원칙, 자주 쓰는 패턴을 정리해두면 매번 프롬프트에 반복 설명할 필요가 없다. 특히 TypeScript/React 컴포넌트 작성 시 Remotion API 사용법을 미리 정의해두면 일관성이 높아진다.

MCP 서버 연동 고려: 파일 시스템 작업이 많은 프로젝트에서는 filesystem MCP 서버를 활용하면 더 효율적이다. 현재는 각 파일을 개별적으로 생성하라고 지시했는데, MCP를 통해 디렉토리 구조를 한 번에 만들고 템플릿 파일들을 배치하는 방식이 더 빠르다.

커밋 메시지 패턴 개선: 모든 커밋이 gpt-5-codex: 접두사로 시작하는데, 더 구체적인 분류가 있으면 좋겠다. feat:, fix:, test: 같은 conventional commits 패턴을 AI에게 미리 알려주면 더 의미 있는 커밋 히스토리를 만들 수 있다.

단위 테스트 자동화: 현재는 테스트를 수동으로 요청했는데, 각 모듈 구현 시 자동으로 테스트도 함께 생성하도록 프롬프트 템플릿을 만들면 더 체계적이다. pytest fixture와 mock 패턴도 미리 정의해두면 일관된 테스트 구조를 유지할 수 있다.

정리

대규모 프로젝트를 AI와 함께 진행할 때 핵심 포인트는 4가지다.

구조를 먼저 잡고 코드는 나중에 — 바로 구현하려 하지 말고 아키텍처부터 설계하게 만든다.

한 번에 하나의 모듈만 집중 — "다른 파일 건드리지 마" 제약으로 컨텍스트 혼선을 방지한다.

구체적인 제약 조건 명시 — 번호로 나열된 규칙을 주면 AI가 체크리스트처럼 확인한다.

점진적 개선 방식 채택 — 완벽한 코드를 한 번에 요구하지 말고 단계적으로 기능을 늘려간다.

이번 작업의 커밋 로그

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