sec-rss-trace

미국 상장사는 중요한 일이 생기면 감독기관(SEC)†에 문서를 제출해야 하고, 그 문서는 누구나 볼 수 있습니다. 증시 뉴스도 마찬가지입니다. 문제는 양입니다 — 하루에도 수천 건이 쌓이고, 그중 주가를 움직일 만한 것은 극소수입니다. 낮에 일하는 사람은 그 극소수를 골라낼 시간이 없습니다.

그래서 두 가지를 원했습니다. 첫째, 내가 원하는 종류의 사건만 — 초거대 기업의 계약·투자, 인수합병, 정부 계약 같은 것 — 피드로 받기. 둘째, 그 알림이 실제로 의미가 있었는지 시장의 반응으로 되돌아가 확인하기. 알림을 보내는 것으로 끝나면 "내 판단이 맞았는지"를 영영 알 수 없기 때문입니다.

SEC 공시와 뉴스는 공개 정보이나 직장인은 제때 읽을 수 없습니다. 초거대 기업의 계약·투자 같은 원하는 사건을 피드로 받고, 시장이 실제로 반응했는지 확인하는 도구를 만들었습니다.

— 프로젝트를 시작한 문제의식

2024년 7월에 SEC 문서를 LLM으로 분류해 Slack으로 보내는 작은 봇으로 시작했고, 2년에 걸쳐 시세 수집 → 급등 알림 → 공시 보유 추적 → 사후 평가로 확장되었습니다. 지금은 아홉 개의 서비스가 한 호스트에서 상시 가동됩니다.

시스템은 왼쪽에서 오른쪽으로 읽으면 됩니다. 문서와 시세가 들어오고, 가운데에서 걸러지거나 계산되고, 사람에게는 Slack과 대시보드로, 시스템 자신에게는 사후 평가로 나갑니다.

서비스 구성

같은 Docker 이미지를 진입점만 바꿔 띄웁니다. 코드는 호스트에서 읽기 전용으로 마운트되어, 배포는 "재시작"입니다.

코드를 묶는 네 가지 원칙

• 봇은 뼈대를 공유한다. RSS 폴링 → 필터 → 본문 추출 → 분류 → 저장 → 알림의 순서는 한 기반 클래스가 정하고, 소스마다 단계만 바꿉니다(Template Method). 새 소스 추가는 클래스 하나입니다.
• LLM 공급자는 인터페이스 뒤에. ask / ask_json 두 메서드만 보이고 OpenAI·Gemini 구현이 그 뒤에 있어, 비용·한도·품질에 따라 바꿔 끼웁니다.
• DB 세션은 문맥이 나른다. 서비스 계층이 세션 객체를 들고 다니지 않도록, 비동기 문맥 변수(contextvars)에 현재 트랜잭션을 두고 @transactional이 있으면 재사용·없으면 새로 여는 전파 규칙을 구현했습니다 — Spring의 ThreadLocal 트랜잭션과 같은 발상을 asyncio에 옮긴 것.
• 핵심 로직은 I/O를 주입받는 순수 함수. 급등 판정·리미터·갭 선택 같은 결정은 시각과 데이터를 인자로 받아 토스·DB 없이 단위 테스트합니다.

분류기는 예시 데이터로 학습시킨 모델이 아니라, LLM에 판단 기준을 글로 주고 분류하게 하는 zero-shot 방식†입니다. 대신 대답은 자유 문장이 아니라 정해진 JSON 형식†으로만 받습니다 — article_type(사건 유형 번호), summary(한국어 요약), ticker. 형식이 계약이라 파싱이 깨지지 않고, OpenAI와 Gemini를 같은 인터페이스 뒤에 두고 바꿔 쓸 수 있습니다.

LLM은 비싸고 느리므로 그 앞에 값싼 1차 필터를 둡니다. 키워드가 없거나, 티커†가 없거나, 시가총액†이 극단적으로 작은 문서는 LLM에 보내지 않습니다.

사건 유형

"조용히 실패"하는 것을 붙잡기

이 파이프라인에서 가장 아팠던 장애는 오류가 나는 것이 아니라 아무 일도 안 일어나는 것이었습니다. 2025년에 SEC가 공시 양식 이름을 바꾸면서(SC 13D → SCHEDULE 13D) 일부 공시가 조용히 걸러졌고, 13F 알림 경로는 페이지 구조를 잘못 읽어 5개월간 한 건도 나가지 않았는데 DB는 다른 경로로 채워져 있어 누구도 눈치채지 못했습니다.

고친 방법은 코드 수정보다 테스트 방식의 전환이었습니다. 실제 SEC 응답을 그대로 저장해 두고 네트워크 없이 재생하는 record/replay 픽스처†로 장애를 재현했고, 같은 픽스처가 회귀 테스트로 남아 재발을 막습니다. 응답이 비어 있으면 픽스처 기록 자체를 거부합니다 — "영원히 통과하는 가짜 초록불"이 가장 위험하기 때문입니다.

"시장이 반응했는가"를 보려면 가격이 필요합니다. 토스증권 Open API를 쓰는데, 제약이 셉니다 — 클라이언트당 인증 토큰†이 하나(새로 받으면 이전 것이 무효)이고, 초당 3~10회가 한도입니다. 그래서 토스를 부르는 프로세스를 price-watch 하나로 못박았습니다. 대시보드 백엔드조차 토스를 직접 부르지 않고, price-watch가 저장해 둔 것만 읽습니다.

4.1버스트를 없애자 429가 사라졌다

한도를 지키려고 라이브러리의 속도 제한기를 썼는데도 429(요청 과다) 오류†가 3분에 118건씩 쏟아졌습니다. 원인은 제한기의 기본 동작이었습니다. 잠시 쉬었다 재개하면 1초 안에 한도의 두 배를 한꺼번에 내보내는 "버스트"가 허용되는데, 서버는 그 순간을 초과로 봅니다. 단서는 경로별 차이였습니다 — 순서대로 도는 확정봉 요청(/candles)의 429는 줄었는데, 4초마다 묶어 쏘는 현재가 요청(/prices)만 그대로였습니다. 버스트가 큰 쪽만 남는다는 뜻입니다. 제한기를 버스트 없이 1건씩 균등 간격으로 바꾸고 15%의 여유를 두자 429는 0건이 되었습니다.

4.2실시간성과 정확성을 분리한 하이브리드 수집

7,000종목의 1분봉†을 하나하나 요청하면 한 바퀴에 수십 분이 걸립니다. 그래서 두 경로를 겹칩니다. 현재가는 200종목씩 묶어 4초마다 전 종목을 훑고, 그 값으로 1분봉을 합성합니다(즉시 쓸 수 있지만 거래량이 없음). 그 뒤 확정봉 요청이 순서대로 돌며 거래량과 정확한 값으로 덮어씁니다. 같은 (시각, 종목) 키에 두 번 써도 마지막 값 하나만 남는 저장소의 upsert† 성질 덕에 순서가 꼬여도 결과가 같습니다. 합성과 보정을 합쳐 하루 약 1,000만 행을 쓰고, 보관되는 확정봉은 하루 약 140만 개(정규장+연장장)입니다. 시계열은 최근 365일을 보관합니다(2026-08-30 실측: 2025-08-29 ~ 2026-08-29, 최근 7일 활성 6,784종목).

알림은 두 방향으로 갑니다. 뉴스 → 반응: 빅뉴스가 들어오면 그 종목을 일정 시간 지켜보다 기준가 대비 X% 오르면 알립니다(원인은 이미 손에 있음). 반응 → 원인: 뉴스가 없어도 전 종목에서 급등을 잡고, 자체 뉴스 DB를 거꾸로 뒤져 원인을 붙입니다. 둘 다 "가격만으로 발사하면 오탐이 너무 많다"는 같은 문제를 만납니다.

5.1종목마다 다른 "평소"를 기준으로

어떤 종목은 하루 1%가 큰 움직임이고 어떤 종목은 5%가 평범합니다. 그래서 수익률을 그대로 쓰지 않고 종목별 평소 변동폭으로 나눈 z-score†를 씁니다. 평균과 변동폭은 지수이동평균으로 흐르듯 갱신하되, 방금 터진 급등이 자기 분모를 부풀리지 못하게 직전 값으로 채점하고 극단값은 잘라서 넣습니다. 개장·마감 무렵은 시장 전체가 출렁이므로 시간대별 변동성 프로파일로 나눠 보정†하고, 변동폭이 0에 가까운 종목의 z가 폭발하지 않도록 절대 수익률 하한을 AND로 겁니다.

5.2거래량은 나중에 온다 — 2단계 확인

현재가 응답에는 거래량이 없습니다. 그래서 가격으로 먼저 "잠정 급등"을 잡고(1단계), 그 종목의 확정봉을 우선 받아 상대 거래량 RVOL†이 임계 이상인 것만 "거래량 확인"으로 승격합니다(2단계). Slack은 2단계를 통과한 것만 받습니다. 실측으로 1단계 신호의 84%가 여기서 걸러졌습니다.

대형 운용사와 기업의 보유 종목은 분기마다 13F†로, 특정 회사 지분이 5%를 넘으면 13D/G†로 공개됩니다. 두 양식은 형식도 주기도 다르지만, 합치면 "이 운용사가 이 종목을 지난 공시 대비 얼마나 늘리거나 줄였는가"를 알 수 있습니다. 새 공시가 들어오면 SEC 문서 목록에서 XML 원본을 찾아 파싱하고, 직전 조립 상태와 비교해 수량 변화만 알립니다.

처음에는 HTML 표를 긁었는데 표 구조가 바뀔 때마다 깨졌습니다. XML 원본으로 바꾸면서 XSL 미리보기(겉은 XML 주소지만 실제로는 HTML)를 잘못 고르는 함정, 새 공시를 먼저 저장하고 나서 "직전 보유"를 조회해 변화가 항상 0으로 나오던 순서 버그를 함께 잡았습니다 — 모두 실제 SEC 페이지 픽스처로 재현한 뒤 고쳤습니다.

별도의 sec-watch는 반대편을 봅니다. 신주·전환사채 발행처럼 기존 주주 지분 가치를 줄이는 희석 위험, 상장폐지·회계 문제 같은 강한 악재를 8-K 항목 번호†와 양식 종류로 3단계 등급을 매겨 구독 종목에 즉시 알립니다.

분류기가 "중요"라고 한 기사 뒤에 주가가 실제로 움직였는가? 반대로 "잡음"이라고 버린 기사 뒤에 움직인 것은 없는가? 전 종목 1분봉을 갖고 있으니 이 질문에 모든 기사에 대해 답할 수 있습니다.

기사를 받은 시각의 직전 봉을 기준가로 잡고, 30분·2시간·1일·3일 뒤 종가로 수익률을 계산해 저장합니다. 같은 창의 나스닥 100 ETF(QQQ) 수익률도 함께 저장해, 시장 전체가 오른 날의 상승을 뉴스의 공으로 돌리지 않게 합니다. 24시간 안의 최고·최저(런업·드로다운)도 기록하는데, "30분 만에 +5% 갔다가 제자리"는 종가로 보면 0%지만 알림으로는 적중이기 때문입니다. 2026년 8월에는 gs-quant의 이벤트 스터디에서 관점을 빌려 수신 전 2시간 창도 추가했습니다 — 기사가 오기 전에 이미 오른 종목은 "새어 나간 뉴스"라 알림 가치가 낮습니다.

7.1주간 브리핑 — 숫자는 코드가, 해석은 LLM이

매주 4분면 원자료를 사람이 훑는 대신, 코드가 검증한 사실만 모은 블록(기간 집계, 임계별 정밀도·재현율, 시장 수익률과 등락 종목 비율, 섹터별 중앙값, 놓침·과잉 상위 10건과 그 맥락)을 LLM에 주고 "이번 주 분류기가 어디서 새는가"를 구조화된 형식으로 받습니다. LLM은 주입된 숫자만 인용하고 계산은 하지 않습니다. 프롬프트를 바꾼 전후 기간의 비교(A/B)도 같은 방식으로, 유의성은 코드가 두 비율 z-검정†으로 계산해 넣습니다.

7.2데이터가 틀리면 전략도 틀린다 — PEAD 검증

실적 발표 뒤 주가가 며칠간 같은 방향으로 표류한다는 현상(PEAD)†을 검증하려고 별도 서비스를 만들었습니다. 핵심은 "발표 시점에 사람들이 실제로 본 숫자"인데, 무료 벤더 데이터는 나중에 조용히 수정됩니다. 그래서 발표 시점 그대로를 보존한 아카이브†와 SEC 원본(XBRL)†으로 대조했더니, 어닝 서프라이즈의 방향 자체가 표본의 최대 21%에서 뒤집혔습니다(허용 2%). 벤더 데이터를 부적합으로 판정하고 원본 공시 기반 신호로 바꿨습니다. 가설과 판정 기준은 결과를 보기 전에 사전 등록해, 결과를 보고 기준을 옮기는 일을 스스로 막았습니다.

개인 프로젝트지만 상시 가동 시스템이라 장애는 실제로 납니다. 사건마다 증상·원인·증거(재현 쿼리와 수치)·조치·재발 방지를 한 문서로 남기는 장부를 두었습니다. 벤더 응답은 나중에 바뀌므로 "그때 그 값이 틀렸다"는 증거를 사고 시점에 남겨야 합니다.

품질 장치

• 테스트 717건(76파일) — 시세·급등·리미터의 핵심 로직은 I/O를 주입받는 순수 함수로 분리해 토스·DB 없이 회귀 검증. 실제 SEC 응답은 record/replay 픽스처로 재생.
• CI 게이트 — 테스트가 깨지면 이미지가 빌드되지 않습니다. 네트워크·LLM이 필요한 테스트는 마커로 분리해 CI가 항상 초록을 유지하도록 했습니다.
• 스키마 재현성 — 기동 시 자동 생성 + 컬럼 변경은 alembic 마이그레이션. 마이그레이션 전 코드가 돌아도 새 기능만 건너뛰는 fail-soft.
• 추적 가능한 로그 — RSS 항목 하나가 파싱→LLM→DB→Slack을 지나는 동안 한 상관관계 ID†를 달고 다닙니다. 웹 요청은 응답 헤더로 같은 ID를 돌려줍니다.
• 회복탄력성 — 수집 경로는 VPN 사이드카 10대로 송신 IP를 분산하고, 429를 받은 경로는 잠시 풀에서 빼두었다가 되돌립니다. 한 경로가 막혀도 전체가 멈추지 않습니다.
• 데이터 감사 — 2026년 8월 시세 계통 전수 감사(발견 6건 전부 해결), 그리고 "값이 틀렸다는 증거를 남기는" 보정 장부.

모든 결과는 React 대시보드에서 봅니다. 새 기사는 SSE†로 밀려오고, 연결이 끊긴 사이의 것은 재연결 때 DB에서 보충해 빠짐이 없습니다. 브라우저는 토스를 호출하는 서비스에 절대 닿지 않습니다 — 게이트웨이가 읽기 전용 백엔드만 노출합니다.

화면 목록

• 기사 피드 (미국 · 실시간) — 사건 유형별 트리, 검색(Meilisearch — 대문자로 치면 티커 모드), 북마크, 기사 카드 안 미니 차트(뉴스 수신 시각을 마커로, 확정 구간은 실선·미확정 합성봉 구간은 점선 — API 제약을 숨기지 않음)
• 가격 알림 — watch/글로벌 급등 피드, 거래량 확인 배지, 원인 뉴스 펼치기
• 후행평가 — 4분면 매트릭스, 임계 스윕(3/5/10% × 호라이즌), 지표 전환(원시·시장보정·런업·사전 창)
• 주간 브리핑 — 월 캘린더(일별 적중률), 브리핑 상세, A/B 비교 생성
• 13F 보유 현황 · SEC watch(희석·악재 스캔) · 시세 관리자(완전성 히트맵, 급등 임계 라이브 튜닝) · 키워드 · 알림 설정 · 기술 문서

• 확장의 상한이 토큰에 있다. 토스 토큰이 하나라 시세 수집은 단일 인스턴스여야 하고, 백필 처리량은 그 한도가 정합니다. 수평 확장은 구조적으로 막혀 있습니다.
• 합성봉은 거래가 없는 분을 채우지 못한다. 완전성은 보장이 아니라 관측·복구의 문제이고, 히트맵과 자가치유 큐가 그 한계를 다룹니다.
• 사후 평가의 시간은 거래일이 아니라 달력이다. 주말을 낀 3일은 실제로 하루치 거래일 수 있습니다. 상장폐지된 종목은 마지막 가용 봉으로 종결되어 생존 편향이 있습니다 — 학습용으로 쓸 때는 상태 필터가 필수입니다.
• 분류 정밀도는 낮다. 17%는 "읽을 가치" 필터로는 쓸모 있어도 매매 신호로는 부족합니다. 사전 창(−2h) 라벨을 알림 등급에 반영하는 것이 다음 실험입니다.
• 티커는 바뀐다. 티커 개명·재사용 이력이 없어 과거 기사와 종목의 매핑이 어긋날 수 있습니다. 식별자 유효 구간 테이블이 후보에 있습니다.

본문의 † 표시에 마우스를 올리거나 키보드로 초점을 맞추면 같은 설명이 뜹니다.