파이프라인 연결(그래프화) 작업 가이드 — 자료집
작성일: 2026-08-17 첫 적용 사례: 주간 크레딧 브리핑에 자체 US IG/HY OAS 판단 연결 대상: 앞으로 파이프라인 간 "유기적 연결"을 시킬 때 이 문서를 먼저 참고해서 진행한다.
왜 이 문서가 있나
우리 시스템에는 스크립트가 120개 넘게 있고, 대부분 서로 남남처럼 따로 돕니다. 같은 주제(예: 크레딧)를 다루는 파이프라인 두 개가 있어도 서로의 데이터를 안 씁니다. 이 문서는 "이런 연결을 시킬 때 무엇부터 확인하고, 어떤 순서로 작업하고, 뭘로 검증하는지"를 정리한 절차서입니다.
언제 이 절차를 쓰나
해리가 "A 파이프라인에 B 자료를 녹여라", "A랑 B가 유기적으로 나오게 해라", "이 자료 참고해서 저기 반영해라" 같은 요청을 할 때 사용합니다.
절차 (5단계)
1단계 — 두 파이프라인의 실제 산출물 파일을 먼저 찾는다
코드를 고치기 전에 반드시 확인: - 소스 파이프라인이 최종적으로 어떤 파일(JSON 등)에 결과를 저장하는가 - 그 파일의 "최신성"이 보장되는가 (언제 마지막으로 갱신됐는지 실제로 확인) - 대상 파이프라인이 최종 메시지를 어느 함수에서 조립하는가
함정: 스크립트 이름만 보고 짐작하지 않는다. 실제로 read_file로 최근 갱신 시각(generated_at,
mtime)을 찍어봐야 한다. 이번 사례에서 소스 파일(us-ig-weekly-latest.json)이 겉보기엔 정상
경로였지만 실제로는 17일간 방치되어 있었다 — 코드만 보고는 못 잡는 문제였다.
2단계 — 연결 함수는 "실패해도 조용히 빈 값" 원칙으로 만든다
새로 만드는 연결 함수는 아래 규칙을 반드시 지킨다: - 소스 파일이 없거나, 파싱 실패하거나, 너무 오래됐으면(staleness 기준을 명시적으로 정한다) 빈 문자열/빈 값을 리턴하고 조용히 넘어간다. 예외를 던져서 전체 발송을 막지 않는다. - staleness 기준은 그 데이터의 갱신 주기를 보고 정한다 (예: 주간 데이터면 "8일 초과 시 stale"). - 왜: 대상 파이프라인(주간 브리핑)은 원래 이 연결 없이도 동작해야 하는 파이프라인이다. 새 연결이 고장난다고 기존 파이프라인까지 죽이면 안 된다 (Anthropic 패턴 문서의 "실패는 국소적이어야 한다" 원칙, 그리고 이미 이 코드베이스가 슬랙 발송 실패를 텔레그램 발송과 분리한 것과 같은 원칙).
3단계 — 데이터 파이프라인 자체가 죽어있는지 별도로 확인한다
연결 코드가 완벽해도 소스 데이터가 안 돌고 있으면 의미가 없다. 반드시 확인:
- 소스 파일을 누가, 언제, 무슨 크론으로 갱신하는지 (cronjob action=list로 관련 job 검색)
- 그 크론이 정말 "이 파일"을 갱신하는 옵션으로 실행되는지 (스크립트에 --weekly-only 같은
플래그가 있는데 크론이 기본 모드로만 도는 경우가 실제로 있었다 — 이번 사례가 그것)
- 필요하면 수동으로 한번 실행해서 파일이 진짜 갱신되는지 확인한다
이번 사례 실제 발견: 크레딧 OAS를 갱신하는 크론(d3f657fca25c, 매일 밤)은 존재했지만
--weekly-only 플래그 없이 돌고 있어서, 주간 브리핑이 읽는 us-ig-weekly-latest.json은 아무도
안 건드리고 있었다. → 별도 주간 갱신 크론(fi-credit-weekly-oas-refresh)을 새로 만들고, 발송
크론(토요일 08:00)보다 10분 먼저(07:50) 돌게 순서를 맞췄다.
4단계 — dry-run으로 실제 메시지를 눈으로 확인한다
코드가 컴파일된다고 끝난 게 아니다. 반드시:
python3 scripts/<발송스크립트>.py --mode weekly --date <다음 발송일>
# --send 를 붙이지 않으면 실제 발송 없이 messages 필드에 완성된 텍스트가 나온다
messages 필드를 직접 읽어서 연결한 섹션이 정확한 위치·형식으로 들어갔는지 확인한다. 숫자가
말이 되는지(bp 단위, 부호, 화살표 방향)도 같이 확인한다.
5단계 — 크론 순서를 확인한다
두 크론이 관련되면(데이터 갱신 크론 + 발송 크론) 반드시 갱신이 발송보다 먼저 끝나도록 시간을 벌려서 배치한다. 최소 10분 이상 여유를 둔다(둘 다 몇 분 안에 끝나는 배치 작업이라도, 실행 지연 가능성을 감안).
이번 작업 요약 (실제 사례 — 향후 유사 작업 템플릿으로 사용)
| 항목 | 내용 |
|---|---|
| 대상 파이프라인 | 주간 크레딧 브리핑 (research-brief-weekly-0800, 토요일 08:00) |
| 연결한 소스 | 자체 FRED 기반 US IG/HY OAS 주간 스냅샷 (fi_credit_refresh.py --weekly-only) |
| 새 함수 | research_learning_system.py::build_house_view_block() |
| 연결 지점 | deliver_research_link_brief.py::run() — weekly 모드 메시지 조립부, 맨 앞에 삽입 |
| 발견한 숨은 문제 | 소스 데이터가 17일간 방치 — 별도 주간 갱신 크론 부재 |
| 추가한 크론 | fi-credit-weekly-oas-refresh (토 07:50, 발송 10분 전) |
| 검증 방법 | --mode weekly --date 2026-08-22 dry-run으로 실제 메시지 텍스트 확인 |
다음에 시킬 연결 후보 (참고용, 미착수)
- 아침/저녁 브리핑(
morning_briefing.py)의 10개 수집 함수 — 서로 의존성 없음, 병렬 처리로 전환 가능 - 종목 인사이트 파이프라인 — 15개 노트가 볼트에서 고립 상태 (zk-link-audit 스킬로 정리 가능)
- 다른 주간 리포트(bond_weekly_review.py 등)에도 같은 house_view 패턴 적용 가능한지 검토