데이터 파이프라인 문서에는 뭘 써야 할까 — architecture.md가 다루지 않는 것

아키텍처 문서만으로는 부족하다

이전 글에서 아키텍처 문서(architecture.md)에 담아야 할 핵심 항목을 정리했다. 레이어 구분, HLD, 데이터 모델, 외부 의존성, 설정 관리 — 이 다섯 가지가 프로젝트의 정적인 구조를 보여준다.

그런데 파이프라인 기반 프로젝트에서는 한 가지가 빠져있다. 데이터가 단계별로 어떻게 변환되며 흐르는가? 이건 HLD로는 표현하기 어렵다. HLD는 컴포넌트 간 의존 관계를 보여주지만, "A 모듈의 출력이 어떤 형태로 B 모듈에 전달되는지", "중간에 캐시가 언제 끼어드는지"는 알려주지 않는다.

이 간극을 메우는 것이 데이터 파이프라인 문서(data-pipeline.md)다. 이 글에서는 실제 사이드 프로젝트의 파이프라인 문서를 바탕으로, 어떤 내용을 담아야 하는지를 정리한다.

1. 전체 흐름도 (Pipeline Flow)

파이프라인 문서의 첫 번째 항목은 데이터가 어떤 순서로 변환되는지를 보여주는 흐름도다. HLD가 컴포넌트 간 "누가 누구를 호출하는가"를 보여준다면, 파이프라인 흐름도는 "데이터가 어떤 형태로 들어와서, 어떤 형태로 나가는가"에 집중한다.

예를 들어, 사진을 AI로 분석하여 포토북을 만드는 파이프라인은 이런 흐름이다:

핵심은 각 단계의 이름, 입력 형태, 출력 형태를 한눈에 보여주는 것이다. 세부 로직은 다음 섹션에서 다룬다.

왜 LLM에게 중요한가: AI 에이전트가 "3단계 그룹핑 로직을 수정해줘"라는 요청을 받으면, 흐름도에서 3단계의 입력(필터링된 사진 목록)과 출력(이벤트 그룹)을 즉시 파악할 수 있다. 입출력 형태를 모르면 에이전트가 수정 후 다음 단계와의 호환성을 깨뜨릴 위험이 있다.

2. 단계별 상세 (Step-by-Step Detail)

각 단계를 일정한 형식으로 기술한다. 아래 템플릿이 실용적이다:

항목	설명
파일	해당 단계의 소스 파일 (예: grouper.py)
입력	데이터 형태와 소스 (예: list[PhotoRecord], 이전 단계의 출력)
출력	데이터 형태와 저장 위치 (예: list[PhotoEvent], 메모리)
처리 로직	핵심 알고리즘 요약 (전체 코드가 아니라 판단 기준과 분기 조건)
설정값	이 단계에서 사용하는 주요 상수/환경변수

예를 들어, "그룹핑" 단계는 이렇게 기술할 수 있다:

### 3단계: 그룹핑 (grouper.py)
- 입력: 필터링된 list[PhotoRecord]
- 출력: list[PhotoEvent]
- 로직: 시간순 정렬 → 인접 사진 간 48시간 이상 간격이면 분리
         → 3장 미만 클러스터는 "일상"으로 병합
- 설정: EVENT_GAP_HOURS=48, MIN_EVENT_PHOTOS=3

왜 LLM에게 중요한가: "그룹핑 기준을 24시간으로 바꿔줘"라는 요청을 받으면, 에이전트는 단계별 상세에서 EVENT_GAP_HOURS=48을 찾아 정확히 어떤 값을 어디서 바꿔야 하는지 즉시 파악한다. 또한 "3장 미만이면 병합"이라는 규칙도 알고 있으므로, 기준을 바꿨을 때 부작용(클러스터 수 폭증 등)을 미리 경고할 수 있다.

3. 캐시 전략 (Cache Strategy)

파이프라인 프로젝트에서 캐시는 단순한 최적화가 아니라 아키텍처의 핵심이다. LLM 호출처럼 비용이 높은 단계, 외부 API 호출처럼 속도가 느린 단계에서 캐시가 파이프라인의 실행 전략을 좌우한다.

캐시 문서에는 다음을 정리한다:

캐시 파일	내용	생성 시점	갱신 조건
photo_records.json	추출된 전체 사진 레코드	추출 단계	새 사진이 추가되었을 때
narrative_cache.json	LLM 생성 내러티브	내러티브 단계	이벤트 구성이 바뀌었을 때
landmark_cache.json	GPS → 관광명소 매핑	태깅 단계	새 좌표가 추가되었을 때

왜 LLM에게 중요한가: 캐시 전략이 문서화되어 있지 않으면 두 가지 문제가 생긴다. 첫째, 에이전트가 매번 전체 파이프라인을 처음부터 실행하는 코드를 작성할 수 있다 — LLM 호출이 포함된 파이프라인이면 비용이 급증한다. 둘째, 캐시가 있는데 캐시를 무시하고 중복 데이터를 만드는 코드를 작성할 수 있다. "이 단계는 캐시가 있으면 건너뛴다"는 정보가 에이전트의 코드 품질을 결정적으로 바꾼다.

4. 에러 처리와 재시도 (Error Handling)

파이프라인에서 에러 처리는 단일 서비스와 다르다. 5단계 중 4단계에서 실패하면 어디서부터 다시 시작할 수 있는가?가 핵심이다.

문서에 정리할 것:

• 재시작 지점: 각 단계가 독립적으로 재실행 가능한지, 이전 단계부터 다시 해야 하는지
• 외부 API 실패 시 전략: 재시도 횟수, 폴백, 타임아웃
• GPU 선점 시 전략: 중간 결과 체크포인트 저장 여부
• 부분 실패 허용 여부: 한 이벤트의 내러티브 생성이 실패해도 나머지는 진행하는지

왜 LLM에게 중요한가: 에러 처리 전략이 명시되어 있지 않으면 LLM은 자기 나름의 에러 핸들링을 만들어버린다. "API 실패 시 무한 재시도"나 "한 건 실패하면 전체 중단" 같은 프로젝트 의도와 다른 패턴이 들어오면, 나중에 추적하기 어려운 버그가 된다.

5. 외부 자원 의존 (Resource Dependencies)

파이프라인의 각 단계가 어떤 외부 자원을 소비하는지를 명시한다. 이건 아키텍처 문서의 "외부 의존성" 표와 다르다 — 연결 방식이 아니라 실행 시 필요한 자원에 초점을 맞춘다.

단계	필요 자원	비용/제약
추출	Immich API	네트워크, API rate limit
필터링	없음 (로컬 연산)	-
그룹핑	없음 (로컬 연산)	-
내러티브	GPU, vLLM API	GPU 메모리 16GB, 이벤트당 ~10초
렌더링	ffmpeg (영상), Immich (썸네일)	디스크, 네트워크

왜 LLM에게 중요한가: 에이전트가 "파이프라인 전체를 실행해줘"라는 요청을 받았을 때, 어떤 단계에서 GPU가 필요하고 어떤 단계는 로컬에서 끝나는지를 알아야 적절한 실행 전략을 세울 수 있다. GPU가 필요한 단계만 별도로 스케줄링하거나, 로컬 단계만 먼저 테스트할 수 있다.

architecture.md vs data-pipeline.md

두 문서의 역할을 정리하면 이렇다:

관점	architecture.md	data-pipeline.md
초점	시스템의 구조 (무엇으로 구성되어 있는가)	데이터의 흐름 (어떻게 변환되는가)
다이어그램	컴포넌트 의존 관계 (정적)	단계별 입출력 흐름 (동적)
핵심 질문	"이 모듈을 수정하면 어디에 영향이 가나?"	"이 단계의 출력이 바뀌면 다음 단계가 어떻게 되나?"
대상 프로젝트	모든 프로젝트	파이프라인 기반 프로젝트

모든 프로젝트에 data-pipeline.md가 필요한 건 아니다. REST API 서버나 웹앱처럼 요청-응답 모델이면 아키텍처 문서만으로 충분하다. 하지만 데이터가 여러 단계를 거쳐 변환되는 프로젝트 — ETL, ML 파이프라인, 미디어 처리, 배치 작업 — 에서는 이 문서가 아키텍처 문서를 보완하는 핵심 문서가 된다.

마무리: 데이터의 여정을 문서화하라

코드는 "이 함수가 무엇을 하는가"를 보여준다. 아키텍처 문서는 "이 모듈들이 어떻게 연결되어 있는가"를 보여준다. 데이터 파이프라인 문서는 "이 데이터가 어디서 와서, 어떻게 변환되어, 어디로 가는가"를 보여준다.

AI 에이전트에게 파이프라인 작업을 맡길 때, 이 세 가지가 갖춰져 있으면 에이전트는 개별 파일이 아니라 데이터의 여정 전체를 이해한 상태에서 코드를 수정한다. 한 단계의 출력 형태를 바꿨을 때 다음 단계가 깨지는 실수를, 문서가 미리 막아준다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.