국내 분배형 ETF, 손으로 세던 걸 대시보드로 만들었습니다
(파이썬 초보 + 클로드 코드)
────────────────────────────────────────
소개 — 시도하고자 했던 것과 그 이유
────────────────────────────────────────
파이썬 초보입니다. 코드를 못 읽는 상태에서 시작했습니다.
분배금(배당) 주는 국내 ETF에 나눠 담고 있는데, 늘 걸리는 게 있었습니다.
- 내가 가진 ETF가 월분배인지 분기분배인지 매번 헷갈린다
- 분배금을 받으려면 언제까지 사야 하는지(매수마감일) 매번 계산해야 한다
- 여러 계좌에 흩어져 있어서 "지금 내 분배금 총액이 얼마"인지 한 번에 안 보인다
- 계좌마다 세금이 다르다. 일반 계좌는 15.4% 떼는데 연금·ISA는 안 뗀다
특히 마지막이 컸습니다. 세전 분배금만 보고 있으면 실제로 손에 쥐는 돈을
계속 과대평가하게 됩니다.
그래서 "국내 분배형 ETF 전체를 모아서 분배주기로 분류하고,
내 보유 종목을 얹어서 세후 기준으로 보여주는 대시보드"를 만들기로 했습니다.
목표는 딱 하나였습니다.
→ 종목 이름으로 추측하지 말고, 데이터 값으로만 판단할 것.
이름에 "월배당"이 들어가도 실제 지급 이력이 연 1회면 연분배입니다.
이름을 믿으면 안 됩니다.
────────────────────────────────────────
진행 방법 — 어떤 도구를 어떻게 썼나
────────────────────────────────────────
■ 사용 도구
- 클로드 코드 (Claude Code) — VS Code 터미널에서 실행
- Python 3.11 + Streamlit (대시보드)
- 데이터: 세이브로(분배금 지급현황), 한국거래소 KRX(시세·영업일)
■ 가장 중요했던 건 첫 프롬프트였습니다
처음에 이것저것 물어보다 삼천포로 빠지는 걸 겪고,
프로젝트 규칙을 CLAUDE.md 파일에 아예 박아두는 방식으로 바꿨습니다.
이 파일은 클로드 코드가 매 세션 자동으로 읽습니다.
--- CLAUDE.md 전문 ---
# 프로젝트: 국내 분배형 ETF 수집·분류 도구
- 나는 파이썬 초보. 설명은 한국어로 짧게, 코드 주석 한국어
- 데이터는 data/raw에 CSV 저장. 확인용 출력은 상위 5행만, 전체 덤프 금지
- 종목 특성을 이름으로 추정 금지, 데이터 값으로만 판단
- 한 세션 = 한 단계만. 완료 시 PROGRESS.md에 결과 요약 기록
- 분배주기 판정: 최근 12개월 지급 횟수 / 매수마감일 = 기준일 2영업일 전
--- 여기까지 ---
이 다섯 줄이 프로젝트 전체를 굴러가게 했습니다. 특히 뒤의 세 줄이 핵심입니다.
"이름으로 추정 금지" → 엉터리 분류를 원천 차단
"한 세션 = 한 단계만" → 한 번에 다 하려다 산으로 가는 걸 방지
"PROGRESS.md에 기록" → 다음 세션이 이어받을 수 있게 됨
■ 실제로 던진 첫 프롬프트
--- 프롬프트 전문 ---
(프로젝트 폴더)에서 진행. CLAUDE.md 참고.
1단계: 국내 분배형 ETF 데이터 수집 + 분배주기 분류 (MVP)
[여기에 KRX F12 Copy as cURL 붙여넣기, 없으면
"cURL 없음, 엑셀 수동 다운로드 방식으로 진행" 이라고 적기]
산출물:
- 원본 데이터 → data/raw/*.csv
- 분류 결과 → output/분배ETF목록.xlsx (시트1: 전체, 시트2: 월·위클리만)
먼저 계획(수집 방식 + 분류 로직)만 제시하고, 내 확인 받은 뒤 진행해줘.
--- 여기까지 ---
마지막 줄 "먼저 계획만 제시하고 내 확인 받은 뒤 진행해줘"가 신의 한 수였습니다.
초보라 코드를 못 읽으니, 최소한 "무엇을 할 것인지"는 한국어로 먼저 받아보고
방향이 틀렸으면 그때 잡을 수 있었습니다.
한국 앱 대시보드 스크린샷
← 완성된 대시보드. 국내 분배형 ETF 955개를 모아 자동 분류했습니다
← 분배주기별 분포. 월분배가 164개, 연분배가 300개 넘습니다
중국사이트 스크린샷
← 종목 목록. 분배주기·분배율·총보수·수익률을 한 표에서 봅니다
한국사이트 스크린샷
← 분배 일정. 언제까지 사야 이번 분배금을 받는지 보여줍니다
■ 단계별로 이렇게 쌓아 올렸습니다
1단계 ETF 수집 + 분배주기 분류 (월/분기/반기/연)
2단계 매수마감일 계산 (기준일 2영업일 전 — 영업일 계산이 은근 까다로움)
3단계 분배 캘린더 .ics 내보내기 (구글 캘린더에 꽂으면 알림이 옵니다)
4단계 NAV 침식 분석 (분배금 많이 주는 대신 원금 까먹는 ETF 걸러내기)
5단계 수익률(YTD·1년) 붙이기
6단계 분류 체계 (투자지역·테마섹터·자산분류·전략)
7단계 내 포트폴리오 — 보유 종목 얹어서 평가
8단계 계좌유형별 과세 · 현금흐름 · 리밸런싱
9단계 계좌 캡처 → CSV 자동 변환
10단계 원본과 교차검증 + 표 가독성 정리
■ 제일 신기했던 기능: 계좌 캡처를 그냥 던지면 CSV가 됩니다
증권사 앱 잔고 화면을 캡처해서 대화창에 드래그해서 넣으면,
클로드가 읽어서 보유종목 CSV로 만들어 줍니다.
캡처 수십 장을 넣었더니 종목·수량·매수단가를 표로 정리해 줬습니다.
심지어 검산까지 해줬습니다 — 매입금액 합계가 화면의 계좌 총액과
±2원까지 맞는지 대조해서 알려줬습니다.
※ 개인 포트폴리오 화면은 자산 금액이 그대로 드러나서 블러 처리를 했습니다. 블러 처리도 클로드가 해줬습니다.
중국사이트 스크린샷
← 종목별로 평가손익·받은 분배금·세후 금액이 한 줄에 나오고
지역별·섹터별·계좌별 비중이 도넛 차트로 붙습니다.
────────────────────────────────────────
결과와 배운 점
────────────────────────────────────────
■ 결과
- 국내 분배형 ETF 955개 수집 · 분배주기 자동 분류
- 내 보유 종목을 세후 기준으로 한 화면에
- 분배 일정을 구글 캘린더로 내보내기
- pytest 134개 통과
■ 꿀팁 1 — CLAUDE.md에 "하지 말 것"을 적으면 훨씬 잘 듣습니다
"~해줘"보다 "~하지 마"가 효과가 좋았습니다.
"확인용 출력은 상위 5행만, 전체 덤프 금지"
이 한 줄로 터미널이 데이터로 뒤덮이는 일이 사라졌습니다.
초보한테는 화면이 깨끗한 게 생각보다 중요합니다.
■ 꿀팁 2 — "한 세션 = 한 단계만"
욕심내서 한 번에 여러 개 시키면 꼭 뭔가 어긋납니다.
한 단계 끝내고 PROGRESS.md에 기록하고 새 세션을 여는 리듬이 훨씬 빨랐습니다.
지금 PROGRESS.md가 500줄이 넘는데, 이게 그대로 프로젝트 문서가 됐습니다.
■ 꿀팁 3 — AI가 "틀렸다"고 스스로 정정하게 두세요
PROGRESS.md에 이런 기록이 남아 있습니다.
※ 정정: 처음에 "캡처에 날짜 구간이 빈다"고 적었으나 틀렸다.
캡처 20장을 전부 확인하니 경계가 연속으로 이어지고,
그 기간은 그냥 매매가 없던 기간이었다.
처음 판단이 틀렸을 때 덮지 않고 기록에 남겨두니,
나중에 같은 착각을 반복하지 않았습니다.
■ 시행착오 1 — 종가로 역산하면 안 맞습니다
거래내역에 거래금액만 있고 수량이 없어서, 종가로 나눠 수량을 역산했습니다.
결과가 실제 보유 수량과 어긋났습니다. 장중 체결가는 종가와 다르기 때문입니다.
결국 잔고 화면에 평균단가가 그대로 있는 걸 발견하고 해결했습니다.
→ 교훈: 계산으로 만들어내기 전에, 그 값이 이미 어딘가 있는지부터 찾아볼 것.
■ 시행착오 2 — 캡처를 수십 장 찍기 전에 엑셀 버튼을 봤어야 했습니다
모바일 앱 캡처를 31장 찍어서 판독했는데,
나중에 PC HTS 화면 오른쪽 위에 [엑셀] 버튼이 있는 걸 발견했습니다.
버튼 한 번이면 끝날 일이었습니다. 당시에는 노트북에 HTS도 안 깔았었기에 깔고 확인하는 과정 마저 귀찮았습니다.
→ 교훈: 데이터를 손으로 옮기기 전에 "내보내기 기능이 없나"부터 확인. 귀차니즘 타파.
■ 시행착오 3 — 한글은 칸 너비를 잡아먹습니다
Streamlit 표에서 종목명이 자꾸 잘렸습니다.
기본 옵션인 width="small"이 75px, "medium"이 200px인데
"TIGER 코리아AI전력기기TOP3플러스" 같은 이름은 250px가 필요했습니다.
영어 기준으로 만들어진 기본값이라 한글에는 좁습니다.
Streamlit 1.60부터 픽셀로 직접 지정할 수 있어서 이렇게 해결했습니다.
# 너비는 픽셀로 직접 준다. "small"(75px)은 한글 값이 잘려서 못 쓴다.
"종목명": st.column_config.TextColumn(width=250, pinned=True),
"계좌": st.column_config.TextColumn(width=115),
"수량": st.column_config.NumberColumn(width=65, format="%d"),
■ 도움이 필요한 부분
1. 데이터 출처가 웹 화면 의존이라 사이트가 바뀌면 깨집니다.
안정적인 공개 API를 쓰시는 분 계시면 조언 부탁드립니다.
2. 실현손익은 결국 포기했습니다.
중간에 거래내역 캡처가 빠진 부분이 있었는데 귀찮기도 하고, 앞으로의 손익이 중요하다고 생각해서 뺐습니다.
■ 앞으로의 계획
- 분배락 이후 주가 회복 패턴 분석 (NAV 침식과 묶어서)
- 해외 분배 ETF, 주식이나 펀드까지 살펴볼 예정
────────────────────────────────────────
도움 받은 글
────────────────────────────────────────
- 클로드 코드 공식 문서 (CLAUDE.md 설정 부분)
https://docs.claude.com/en/docs/claude-code
- Streamlit 공식 문서 — st.column_config
https://docs.streamlit.io/develop/api-reference/data/st.column_config
- 참고한 지피터스 글: -
