AI 배당·절세 에이전트 만들기 — 계획과 설계, 그리고 방향 전환
2026.07.26

소개 (작업내용을 클로드로 문서화 해서 작성)
배당 투자와 절세계좌 관리를 AI 에이전트로 자동화하는 개인 프로젝트의 1주차 기록입니다.
"매달 배당이 들어오는 포트폴리오를, 세금까지 고려해서, 에이전트가 관리해 주면 어떨까?"에서 시작했습니다. 1주차 목표는 코드를 짜는 게 아니라 제대로 된 설계도를 만드는 것이었어요.
전체 로드맵 확정: 무엇을, 어떤 순서로, 어디까지 자동화할지
한국 세금·절세계좌 제도 조사 (이게 이 프로젝트의 핵심 차별점)
증권사 API 조사와 데이터 구조 설계
처음은 반드시 모의투자 계좌로 시작 (실전은 검증 후에)
진행 방법
로드맵을 3단계로 확정했습니다.
1차 (4주): 국내상장 ETF × 키움 모의투자 계좌 — 배당 캘린더, 자동 매수, 텔레그램 리포트
2차: 미국 주식 직접투자 확장 + 실계좌(일반 위탁계좌) 전환
3차: 절세계좌(ISA → 연금저축 → IRP) 연동 + 실계좌 자동주문 (승인 게이트 필수)
1주차 산출물 — 문서 6종 + 설정/코드/데이터:
프로젝트 계획서 v2.1 (3페이즈 로드맵, 주차별 계획)
세금 매트릭스: 계좌 4종(일반/ISA/연금저축/IRP) × 상품 유형별 세율표. 모든 수치에 출처 명기
절세 체크리스트: 납입 순서, 공제 한도, 임계점 경고 등 실행 항목화
데이터 스키마 설계 (SQLite/CSV), 키움 REST API 조사 가이드
tax_rules.yaml: 세율을 코드에 하드코딩하지 않고 설정 파일로 분리 + 검증 날짜 기록세금 시뮬레이터 프로토타입(Python): 계좌별 세후 결과 계산 로직 검증 완료
1주차 대시보드(HTML): 조사 결과를 "결정 가이드"로 만든 인터랙티브 화면 — ① 여유자금 배분 순서 ② ETF별 계좌 배치 ③ 세후 금액 검증 ④ ISA 만기 처리, 4가지 결정을 질문→결정→근거→체크리스트 흐름으로 안내
결과와 배운 점
작업중 수정사항
① 증권사를 중간에 바꿨습니다 (KIS → 키움). 처음엔 한국투자증권 API 기준으로 문서를 다 썼는데, 제가 실제 쓰는 계좌가 키움이라는 현실적인 이유로 전환했어요. API 가이드·데이터 스키마를 다시 작성하는 비용을 치렀습니다. 처음부터 "내가 실제로 쓸 계좌"를 기준으로 조사할 것.
② 키움 REST API에는 배당 일정 API가 없습니다. 배당 캘린더가 이 프로젝트의 심장인데, 정작 증권사 API로는 못 가져와요 (KIS에는 있음). 결국 배당 일정은 공개 데이터(운용사 공시 등)를 주 소스로 하고 수동 보정하는 구조로 설계를 바꿨습니다.
③ 세법은 "알고 있던 지식"으로 쓰면 틀립니다. 2026년 시행 변경사항(고배당기업 분리과세 신설, 종신연금 세율 인하 등)을 웹 검색으로 재검증하면서 여러 수치를 고쳤어요. 그래서 세율은 전부 설정 파일로 빼고, 항목마다 검증 날짜와 미확인 표시를 달았습니다.
④ 대시보드를 한 번 갈아엎었습니다. 처음 만든 버전은 조사 결과를 보여주는 "정보 나열형"이었는데, 다시 보니 정작 "그래서 나는 뭘 해야 하지?"에 답을 안 해주더라고요. 선택하고 결정하도록 돕는 가이드형으로 재설계했습니다. 화면의 목적은 정보 전달이 아니라 의사결정 지원이라는 걸 다시 확인했어요.
배운점
같은 ETF라도 어느 계좌에 담느냐로 세율이 15.4% → 9.9% → 3.3~5.5%까지 달라집니다. 종목 선정보다 계좌 배치가 먼저라는 게 1주차의 가장 큰 결론.
연금저축·IRP 세액공제(합산 900만, 13.2~16.5%)는 시장 상황과 무관한 확정 수익. 납입 순서(연금저축 600 → IRP 300 → ISA)가 사실상 공식처럼 정리됨.
제약도 명확해졌어요: 연금/IRP/ISA에서는 미국 주식 직접투자 불가(국내상장 ETF로 우회), IRP는 위험자산 70% 한도, 연금계좌 중도 인출 시 16.5% 페널티.
AI와의 협업 방식: 요구사항을 먼저 정제하고 → 설계를 확정하고 → 승인 후 구현하는 순서가 재작업을 크게 줄여줍니다 (증권사 전환 때 뼈저리게 느낌).
돈·세금이 걸린 수치는 AI 답변을 그대로 믿지 말고 출처 확인 + 검증 날짜 기록이 필수.
계획
2주차 — 인프라 구축: 키움 모의투자 API 연동(토큰 발급·캐싱, 잔고/예수금 조회), 초당 1건 rate limit 대응, ETF 종목 마스터 수집, SQLite 초기화, 텔레그램 봇 연결
3주차 — 배당 캘린더 & 자동화 로직: 배당 일정 데이터 파이프라인(공개 데이터 + 수동 보정), 배당락·지급일 캘린더, 모의계좌 자동 매수 로직과 주간 리포트
4주차 — 모의 운용 검증 & 1차 마무리: 모의투자 실운용 점검, 세후 수익 리포트, 오류·엣지케이스 정리, 2차(미국 직투) 진입 조건 평가
사용툴
Claude (Cowork 모드, 데스크톱 앱)
협업 규칙을 프롬프트로 고정: 개인 설정에 아래 지침을 넣어두니, 매번 "바로 구현"으로 달리지 않고 요구사항 정제 → 설계 → 승인 → 구현 순서를 지켜줍니다. 증권사 전환 같은 방향 수정 비용이 확 줄었어요.
먼저 나의 요구사항을 잘 이해하고 분석해서, 보다 정제되고 명확한 요구사항이 되도록해. 요구사항 검토시, 필요하면 구현방안도 같이 검토하고, 정리가 되면 설계하고, 그게 큰 틀이 잡히면 나에게 구현을 시작할지 물어봐. 허락을 받으면 그때 구현을 시작해.
내장 웹 검색으로 수치 검증: 2026년 세법 변경사항(분리과세 신설, 연금 세율 인하 등)과 키움 REST API 스펙을 검색으로 재확인하고, 문서에 출처와 검증 날짜를 남기게 했습니다.
프로젝트 메모리: 세션이 바뀌어도 "키움 기준, 모의계좌 먼저, 세율 하드코딩 금지" 같은 확정 사항이 유지되도록 기록해 둡니다.
Python — 세금 매트릭스의 계산 로직을 시뮬레이터 프로토타입으로 만들어 수치를 교차 검증했습니다. 문서의 세율표와 코드 계산 결과가 일치하는지 확인하는 용도예요.
HTML + JavaScript (Cowork 아티팩트) — 1주차 대시보드는 단일 HTML 파일로 만들어 사이드바 아티팩트로 등록했습니다. 서버 없이 열리고, 세율 값은 tax_rules.yaml 검증값을 그대로 옮겨 담았습니다. 만들고 나서는 헤드리스 크롬(Playwright)으로 각 화면을 캡처해 실제 렌더링을 확인한 뒤 전달받는 방식으로 검수했어요.
로그인하고 댓글을 남겨 주세요




키움 계좌를 실제 사용 환경에 맞춰 전환하고, 그 과정에서 API 가이드와 데이터 스키마까지 다시 정리하신 점이 특히 인상적입니다. 세율을 코드에 하드코딩하지 않고 출처와 검증 날짜를 함께 관리하도록 설계한 데다, 정보 나열형 대시보드를 질문→결정→근거→체크리스트 흐름의 가이드로 재설계하신 과정이 정말 꼼꼼하네요. 1주차에 설계와 검증의 기준을 이 정도로 구체화하신 덕분에 이후 자동화도 훨씬 탄탄하게 이어질 것 같습니다.