미국·한국 주식 분석 에이전트 만들기 2026, SEC·DART·FRED 연동 구조와 운영 체크리스트

주식 분석 에이전트 얘기는 자꾸 멋있게만 들린다.

공시 읽고, 재무제표 뽑고, 시나리오 만들고, 리포트까지 자동으로 써준다.

말은 늘 그럴싸하다.

근데 실전은 보통 여기서 갈린다.

숫자를 어디서 가져오나.

틀린 숫자를 안 지어낸다는 걸 어떻게 믿나.

미국주와 한국주를 한 흐름으로 묶을 때 어디서 삐끗하나.

2026년 4월 12일 기준으로 kipeum86/stock-analysis-agent 레포를 직접 클론해서 구조를 뜯어봤다.

README만 훑은 게 아니라 레포 트리, CLAUDE.md, .claude/skills, .claude/agents, 출력 모드 설명, API 의존성까지 같이 봤다.

첫인상은 꽤 좋았다.

특히 미국은 SEC 계열 구조화 데이터, 한국은 DART, 매크로는 FRED로 나눠서 데이터 신뢰도 층 자체를 먼저 설계한 점이 마음에 들었다.

괜히 AI가 똑똑해 보여서 믿으라는 구조가 아니라, 어떤 숫자가 어디서 왔는지를 등급으로 박아두려는 태도가 보였기 때문이다.

대신 바로 보이는 부담도 있었다.

API 키가 생각보다 많고, 미국 쪽 Grade A는 사실상 Financial Datasets API에 기대고, 한국 쪽은 DART가 필수고, 매크로까지 진하게 쓰려면 FRED도 챙겨야 한다.

즉, 에이전트 한 개 깔았다 끝 가 아니라 데이터 공급망을 세팅한 뒤에야 쓸만해지는 구조 에 더 가깝다.

이 글은 그 구조를 홍보 말투 말고 운영 말투로 다시 적어본 해설이다.

결론부터 짧게 적으면 이렇다.
이 레포는 한미 주식 리서치 자동화를 진짜로 해보려는 사람에게는 꽤 괜찮은 출발점이다.
특히 데이터 등급 체계,
출력 모드 분리,
한국 DART 지원은 매력적이다.
대신 그냥 가격 조회기나 가벼운 요약 봇이 필요하다면 과하다.
API 키와 검토 루프를 감당할 준비가 없으면,
멋있어 보여도 금방 운영 피로가 온다.

이런 운영자라면 특히 눈여겨볼 만하다

미국주와 한국주를 한 워크플로로 다루고 싶은 사람
Claude Code 기반으로 금융 리서치 에이전트를 직접 굴려보고 싶은 사람
숫자 출처를 적당히 덮지 않고 등급으로 관리하고 싶은 사람
HTML 대시보드와 DOCX 메모처럼 출력물을 분리하고 싶은 사람
그럴싸한 AI 분석보다 틀린 숫자를 비워두는 구조를 더 중요하게 보는 사람

반대로 이런 사람에겐 안 맞을 수 있다.

실시간 가격만 빨리 보고 싶은 사람
API 키 관리가 귀찮은 사람
검토 없이 바로 투자 판단에 쓰고 싶은 사람
증권사 리포트처럼 법적 책임까지 기대하는 사람

지금 결론

핵심만 먼저 보면 이렇다.

미국과 한국 주식을 한 에이전트 안에서 돌리는 구조는 이미 꽤 설득력 있다.
진짜 차별점은 모델이 아니라 데이터 공급망 분리에 있다.
미국 쪽 Grade A 품질은 Financial Datasets API 의존도가 높다.
한국 쪽은 DART OpenAPI를 필수로 박아둔 점이 실전적이다.
FRED는 옵션 같아 보여도 Mode C와 D의 설득력을 올리는 부품이다.
출력 모드 A/B/C/D가 분리돼 있어 누가 읽을 결과물인가를 먼저 정하기 좋다.
대신 운영자는 API 비용,
키 관리, 검토 시간, 법적 책임의 경계선을 따로 가져가야 한다.

직접 클론해보니 무엇이 먼저 보였나

레포를 직접 클론해보니 파일 구조가 생각보다 깔끔했다.

루트에는 CLAUDE.md, README.md, README.ko.md, references/, docs/, .claude/skills/, .claude/agents/ 가 있다.

특히 마음에 든 건 이 프로젝트가 그냥 프롬프트 한 장으로 끝나지 않는다는 점이다.

references/에 분석 프레임워크를 나누고, .claude/skills/에 query-interpreter, financial-data-collector, data-validator, dashboard-generator, quality-checker 같은 스텝형 구조를 둔 건 AI 에이전트를 진짜 파이프라인으로 보려는 흔적이다.

.claude/agents/ 밑에 analyst, critic, data-researcher 가 있는 것도 비슷하다.

이건 그냥 분석해줘 한 줄 던지고 예쁜 대답 받는 구조가 아니다.

최소한 설계 의도는 데이터 수집 -> 검증 -> 분석 -> 출력 을 분리하려고 한다.

이런 레포는 겉보기에 조금 무겁다.

하지만 금융 쪽은 원래 이 무거움이 필요한 영역이다.

가볍게 만들면 대부분 숫자 환각이나 출처 불명 문제가 튀어나오기 때문이다.

이 레포의 진짜 강점은 모델이 아니라 데이터 경로다

README를 읽어보면 레포가 계속 강조하는 문장이 있다.

Zero hallucinated numbers. Every figure traces back to its source.

이걸 문자 그대로 100% 믿을 필요는 없다.

AI 프로젝트 README는 원래 자신감이 약간 넘친다.

그래도 이 문장이 빈말만은 아닌 이유가 있다.

숫자 품질을 모델 크기나 프롬프트 감성으로 처리하지 않고, 애초에 데이터 소스 계층으로 나눴기 때문이다.

구조는 이렇다.

축	소스	역할
미국 주식	Financial Datasets API + SEC 계열 구조화 데이터	기본 재무와 공시 데이터
한국 주식	DART OpenAPI	재무제표와 공시 데이터
매크로	FRED API	금리, CPI, GDP, 실업률 등 상위 변수
보조 웹 리서치	Yahoo Finance, MarketWatch, FnGuide, 네이버금융 등	가격·컨센서스·정성 맥락

여기서 핵심은 미국, 한국, 매크로를 한 소스에 우겨넣지 않았다는 점이다.

다 따로 관리하니 신뢰도 등급도 따로 매길 수 있고, 빈 구멍이 생겨도 어디가 비는지 보인다.

이건 운영적으로 굉장히 중요하다.

실전에서는 AI가 틀렸다 보다 도대체 어디서 틀렸는지 모르겠다 가 더 치명적이기 때문이다.

미국 주식 파이프라인은 왜 생각보다 까다롭나

README 기준으로 미국 주식은 두 층으로 나뉜다.

첫째는 Financial Datasets API를 붙인 강화 모드다.

둘째는 웹 리서치와 스크래핑 위주의 표준 모드다.

강화 모드에서는 실시간 가격, 8개 분기 손익계산서, 대차대조표, 현금흐름표, 인사이더 거래, SEC filings 등을 구조화된 형태로 가져온다고 설명한다.

반면 API가 없으면 Yahoo Finance, Google Finance, MarketWatch, SEC EDGAR 직접 조회, TipRanks, MarketBeat, Reuters, Bloomberg 같은 웹 소스를 섞는다.

이 구조를 보면 바로 보이는 게 있다.

미국 쪽 Grade A는 사실상 Financial Datasets API를 붙일 때 성립한다.

즉 미국주 Grade A 자동 리서치 를 노린다면 이 프로젝트의 핵심은 Claude Code가 아니라 그 API를 붙일 의지가 있느냐에 달려 있다.

이건 장점이면서 동시에 부담이다.

장점은 정확도를 높일 수 있다는 것.

부담은 운영 비용과 키 관리가 늘어난다는 것.

README는 분석당 비용을 대략 $0.05–$0.28 범위로 적어뒀다.

이 숫자는 매력적으로 보이지만, 여기에 모델 비용과 검토 시간을 더하면 실제 체감비용은 더 올라간다.

특히 종목을 여러 개 비교하거나 반복 스캔을 걸기 시작하면 API 비용 + 모델 비용 + 검토 시간 이 같이 움직인다.

한국 주식 파이프라인은 왜 오히려 더 실전적이었나

한국 주식 쪽은 오히려 설계가 더 마음에 들었다.

이유는 단순하다.

필수 소스를 DART OpenAPI로 명확하게 박아뒀기 때문이다.

README는 한국 주식 지원을 DART OpenAPI + 네이버금융 + FnGuide/KIND 조합으로 설명한다.

연결 재무제표, 기업 기본정보, 최근 공시 목록은 DART에서 가져오고, 현재가와 PER/PBR, 외국인 지분율 같은 시장 데이터는 네이버금융, 애널리스트 컨센서스는 FnGuide나 웹 검색으로 보강한다.

이건 한국 시장 현실에 맞다.

한국 주식 리서치 자동화는 해외보다 오히려 데이터 공급망을 어디서 끌지 더 중요하다.

공시와 가격, 컨센서스와 수급이 예쁘게 한 API에 안 모여 있기 때문이다.

그런 점에서 DART를 Grade A의 중심 으로 두고 나머지를 Grade B로 배치한 건 꽤 현실적인 선택이다.

그리고 이 구조 덕분에 미국과 한국을 같은 프롬프트로 다뤄도 내부 데이터 경로는 다르게 설계할 수 있다.

이게 진짜 중요하다.

한미 주식을 한 화면에서 보고 싶다고 해서 데이터 구조까지 같아야 하는 건 아니다.

오히려 다르다는 걸 인정해야 리서치 품질이 버틴다.

FRED는 옵션처럼 보이지만 사실 설득력 부품이다

README는 FRED API를 옵션으로 적어뒀다.

겉보기엔 없어도 굴러갈 것 같다.

맞다.

없어도 굴러간다.

근데 Mode C와 D를 진지하게 쓸 거면 FRED는 꽤 중요한 부품이다.

이 프로젝트는 FRED를 10년물 금리, Fed Funds Rate, CPI, GDP, 실업률 같은 거시 변수에 연결한다고 설명한다.

그리고 이걸 WACC 정밀도나 macro sensitivity에 쓴다고 적었다.

이 말은 곧, 대시보드나 메모가 그냥 기업 내부 숫자만 보는 게 아니라 할인율과 매크로 환경까지 얹겠다는 뜻이다.

여기서 품질 차이가 꽤 난다.

매크로를 웹 뉴스 한두 줄로 적으면 있어 보이긴 해도 검토 가능한 리서치가 되진 않는다.

반대로 FRED를 붙이면 최소한 왜 지금 할인율을 이렇게 봤는지 설명이 가능해진다.

그래서 FRED는 기능 추가용 옵션보다 리서치 설득력 보강용 부품 에 더 가깝다.

출력 모드 A/B/C/D 분리는 꽤 영리하다

이 레포가 괜찮다고 느낀 또 하나의 이유는 출력 모드를 먼저 분리해둔 점이다.

README 기준으로 모드는 네 개다.

Mode A는 Quick Briefing HTML.

Mode B는 Peer Comparison HTML.

Mode C는 Deep Dive Dashboard.

Mode D는 DOCX 투자 메모다.

이 분리는 별거 아닌 것 같지만 운영 관점에선 아주 중요하다.

왜냐면 주식 분석 에이전트가 실패하는 이유 중 하나가 항상 같은 길이, 같은 밀도, 같은 산출물만 만들려고 하기 때문이다.

실무에선 훑어보는 화면과 비교하는 화면과 깊게 읽는 문서가 다 필요하다.

이 프로젝트는 그걸 애초에 모드로 나눠둔다.

특히 Mode C의 시나리오 카드, R/R Score, Variant View, Precision Risk, DCF sensitivity, Quarterly Financials, Strategy 가이드는 결정 지원용 HTML 을 꽤 선명하게 상정하고 있다.

반면 Mode D는 3,000단어 이상 DOCX 투자 메모로 Goldman Sachs 스타일을 지향한다고 적었다.

즉 이 프로젝트는 처음부터 분석 엔진 만이 아니라 출력물 제작기 를 같이 만들고 있다.

이건 꽤 실전적이다.

리서치 프로젝트는 결과를 어디에 붙일지까지 봐야 운영 가치가 생기기 때문이다.

직접 뜯어보며 바로 보인 운영 부담 5가지

좋은 점만 있으면 그건 대개 리뷰가 아니라 홍보다.

이 프로젝트를 직접 뜯어보며 바로 보인 부담도 적어두자.

1. API 키가 생각보다 많다

DART는 사실상 필수고, FRED는 있으면 좋고, 미국 Grade A를 원하면 Financial Datasets API도 붙여야 한다.

이 정도면 설치보다 운영이 먼저다.

키 발급, 보관, 갱신, 실수로 로그에 새지 않게 관리하는 것까지 다 따라온다.

2. 미국 품질은 MCP 미연결 시 급격히 흔들릴 수 있다

README도 이 부분을 꽤 솔직하게 적는다.

MCP 연결 시 Grade A와 구조화 데이터를 쓰고, 아니면 Grade B 웹 소스로 내려간다.

즉 같은 프롬프트라도 세팅 유무에 따라 결과 품질이 크게 달라질 수 있다.

이건 팀 운영에서 위험하다.

누구는 API 붙인 환경, 누구는 안 붙인 환경으로 쓰면 같은 분석인데도 신뢰도가 다르게 나온다.

3. Mode D는 문서 예쁘게 나온다고 끝이 아니다

DOCX 투자 메모는 보기엔 멋지다.

근데 Word 문서가 나온다고 그게 바로 배포 가능한 리서치가 되는 건 아니다.

오히려 이런 산출물이 더 위험할 때도 있다.

외형이 그럴싸하면 검토가 덜 엄격해질 수 있기 때문이다.

4. 가격 조회기 용도로는 과하다

README도 아예 적어놨다.

이 도구는 quick price lookup용이 아니라고.

즉 가볍게 AAPL 얼마야 가 필요한 사람에겐 Yahoo Finance나 Perplexity가 더 맞다.

이 프로젝트는 리서치 파이프라인이지 간이 시세 앱이 아니다.

5. 투자 판단 책임은 여전히 사람에게 남는다

README 마지막에는 정보 제공용이며 투자 자문이 아니고 모든 결과를 독립적으로 검증하라고 명시한다.

이건 형식 문장이 아니라 운영 핵심이다.

에이전트가 분석을 도와줘도 매수 버튼 책임은 여전히 사람 몫이다.

내가 보기엔 이런 팀에 제일 잘 맞는다

이 프로젝트는 누구에게나 맞는 범용 툴이 아니다.

대신 잘 맞는 팀은 꽤 선명하다.

상황	잘 맞는 정도	이유
한미 주식 리서치를 반복적으로 해야 함	높음	공급망 분리가 이미 설계돼 있음
결과를 HTML 대시보드와 문서로 남기고 싶음	높음	모드 분리가 선명함
API 키 관리와 검토 루프를 운영할 수 있음	높음	도구 가치가 살아남
그냥 종목 요약만 빨리 보고 싶음	낮음	구조가 너무 무거움
검토 없이 바로 투자에 쓰고 싶음	매우 낮음	책임 경계가 맞지 않음

특히 애널리스트 팀보다는 소규모 투자 리서치 자동화 실험팀 이나 개인 리서치 OS를 만드는 운영자 에게 더 잘 맞아 보였다.

이걸 그대로 따라 만들기 전에 체크할 것

만약 너도 비슷한 에이전트를 만들고 싶다면 모델보다 먼저 아래를 점검하는 편이 낫다.

미국 데이터는 어떤 공급망을 쓸지
한국 데이터는 DART를 중심으로 어떤 보조 소스를 붙일지
매크로 레이어를 넣을지 말지
출력물은 HTML인지 DOCX인지
숫자 등급과 빈칸 정책을 어떻게 둘지
검토자를 어디에 넣을지

여기서 내가 제일 마음에 든 건 Blank beats wrong 원칙이었다.

숫자를 못 검증하면 억지로 채우지 말고 비워두는 정책.

금융 에이전트에서 이건 멋보다 훨씬 중요하다.

숫자를 자신감 있게 틀리는 것보다 빈칸을 남기는 게 훨씬 낫다.

실수 TOP 5

1. 모델만 바꾸면 품질이 올라갈 거라 믿는 실수

이 프로젝트를 읽고 느낀 건 금융 에이전트 품질은 모델보다 데이터 경로에서 더 많이 갈린다는 점이다.

2. 미국과 한국 주식을 같은 소스 구조로 보려는 실수

시장은 다르고, 데이터 공급망도 다르다.

한쪽 로직을 다른 쪽에 그대로 복제하면 금방 억지스러워진다.

3. DOCX가 나오면 검토가 끝난 줄 아는 실수

예쁜 문서는 오히려 경계심을 낮춘다.

투자 메모처럼 보인다고 투자 검토가 끝난 게 아니다.

4. FRED를 장식으로만 붙이는 실수

매크로 레이어는 설득력 부품이지 배경 꾸미기용 텍스트가 아니다.

5. API 운영비와 사람 검토 시간을 빼먹는 실수

도구 가격표만 보고 싸다고 생각하면 나중에 진짜 비용 계산이 틀어진다.

언제는 안 만드는 편이 낫나

이런 상황이면 차라리 단순화하는 편이 낫다.

한 달에 종목 몇 개만 가볍게 보는 경우
미국주만 다루는데 굳이 한국과 한 파이프라인으로 묶을 필요가 없는 경우
DOCX나 대시보드 산출물이 실제로 쓰이지 않는 경우
숫자 검토를 해줄 사람이 없는 경우

이럴 때는 단일 시장, 단일 출력, 단일 데이터 공급망으로 작게 시작하는 편이 낫다.

크게 만들수록 멋있어 보이긴 한다.

하지만 운영은 멋보다 유지비를 먼저 낸다.

FAQ

Q1. 이 레포는 진짜 한미 주식을 같이 다룰 수 있나?

README와 레포 구조 기준으로는 그렇다.

미국은 Financial Datasets API 중심, 한국은 DART 중심, 매크로는 FRED로 나눠서 처리한다.

Q2. 제일 먼저 붙여야 할 키는 뭐냐?

한국 주식까지 다루려면 DART가 사실상 첫 번째다.

미국 Grade A 품질을 노리면 그다음이 Financial Datasets API다.

Q3. FRED는 없어도 되나?

기본 동작은 가능하다.

하지만 Mode C와 D의 매크로 설득력을 올리려면 있는 편이 낫다.

Q4. 그냥 가격 조회용으로 써도 되나?

추천하지 않는다.

이 프로젝트는 리서치 파이프라인에 더 가깝고, README도 quick price lookup용은 아니라고 적고 있다.

Q5. 바로 투자 의사결정에 써도 되나?

안 된다.

README도 정보 제공용이며 독립 검증이 필요하다고 명시한다.

도구가 도와줘도 최종 판단 책임은 여전히 사람 몫이다.

미국·한국 주식 분석 에이전트 만들기 2026 — SEC·DART·FRED 연동 구조와 운영 체크리스트