Claude Code로 투자 대시보드를 처음부터 만들어본 과정 — 기획부터 배포까지

Claude Code로 개인 투자 포트폴리오 대시보드를 직접 만든 전체 과정을 공개합니다. 기획 문서부터 GitHub Actions 자동화 배포까지, 코드를 몰라도 따라할 수 있는 방식으로 정리했습니다.

📋 3줄 요약

• 증권 앱 대신 "내가 보고 싶은 것만" 보여주는 대시보드를 Claude Code로 직접 만들었다.
• 기획 문서 → 정적 화면 → API 연동 → GitHub Actions 자동화 3단계로 진행했다.
• Claude Code에 지시할 때 "왜"를 포함한 맥락을 주면 결과물이 완전히 달라진다.

왜 직접 만들었나

투자 포트폴리오를 관리하다 보면 기존 증권 앱에서 불편한 게 있다. 내가 보고 싶은 화면이 없다는 것이다.

구체적으로는 이런 상황이었다. 마이너스통장으로 ETF 9종목에 분산 투자하는 포트폴리오를 운영 중인데, 매일 아침 확인해야 할 것들이 있었다.

• 대출 이자가 이번 달 얼마인지
• 현재 포트폴리오 손익이 이자를 커버하고 있는지
• 미사용 버퍼(한도에서 사용액 차감)가 얼마 남았는지
• 리스크 룰(-10% 도달 시 추가매수 중단 등)에 걸린 항목이 있는지

증권사 앱은 종목별 시세는 잘 보여주지만 "대출 이자 대비 손익"을 한 화면에서 보여주진 않는다. 그래서 직접 만들기로 했다.

Claude Code를 쓰기로 한 건 자연스러운 선택이었다. 이미 업무 자동화에 써오고 있었고, 코드를 직접 작성하는 것보다 "무엇을 원하는지 설명하는 것"에 더 익숙하다는 걸 알고 있었기 때문이다.

기획 단계 — 스펙 문서를 Claude Code와 함께 쓰는 법

아무것도 없는 상태에서 Claude Code를 켜고 "투자 대시보드 만들어줘"라고 하면 원하는 결과가 안 나온다. 경험상 먼저 스펙 문서를 작성하는 게 훨씬 빠르다.

스펙 문서는 복잡하게 생각할 필요 없다. 아래 3가지만 정리하면 된다.

1. 이 페이지에서 매일 무엇을 확인해야 하는가
2. 데이터는 어디서 오는가 (수동 입력 / API / CSV)
3. 어떤 화면으로 보고 싶은가

나는 세 가지 디자인 방향(A안/B안/C안)을 자연어로 설명하고 Claude Code에게 각각의 장단점을 정리해달라고 했다. 그 결과를 보고 A안(Executive Dashboard)을 선택했다.

💡 스펙 문서를 먼저 쓰는 이유
Claude Code는 지시가 모호할수록 "그럴듯하지만 내가 원하는 게 아닌" 결과를 낸다. 스펙 문서를 먼저 쓰면 Claude Code가 CLAUDE.md를 참조하면서 일관된 방향으로 코드를 작성한다. 수정 횟수가 크게 줄어든다.

기술 스택 — 왜 이걸 골랐나

최종 스택은 아래와 같다.

기술	선택 이유	대안과 비교
React + Vite	빌드 빠름, 컴포넌트 단위 수정 용이	순수 HTML/JS도 가능하나 규모 커질수록 불편
Vercel	GitHub push → 자동 배포, 무료 플랜 충분	GitHub Pages는 서버리스 함수 지원 안 됨
JSON 파일 기반 데이터	DB 없이 관리 가능, GitHub에 버전 이력 남음	Supabase는 이 규모에서 오버엔지니어링
GitHub Actions	무료, 매일 자동 실행, Python 스크립트 지원	cron 서버 별도 운영 불필요
pykrx + yfinance	한국 ETF(pykrx)와 미국 주식(yfinance) 동시 커버	Alpha Vantage 무료 플랜은 25 req/day 한계

구현 3단계 전략 — 한 번에 다 만들려다 실패하지 않는 법

처음에 "전부 다 만들어줘"라고 하면 Claude Code가 엄청난 양의 코드를 뱉어내는데, 실행해보면 절반은 안 된다. 이후 디버깅에 시간이 더 든다.

3단계로 나눠서 진행하는 게 훨씬 효율적이었다.

1단계: 정적 화면 먼저

시세 API 연동, GitHub Actions 전부 제쳐두고 샘플 데이터로 화면만 완성하는 것부터 시작했다. portfolio.json에 더미 데이터를 넣고, 화면이 내가 원하는 대로 나올 때까지 수정했다.

이 단계에서 Claude Code에 내린 지시 예시:

portfolio.json의 데이터를 읽어서 카드형으로 표시해줘.
카드마다 종목명, 목표금액, 기대수익률, 역할을 보여줘.
색상은 styles.css의 --primary, --accent 변수 사용해.
시세는 아직 연동 안 해도 되고, "시세 로딩 중" 텍스트만 표시해.

2단계: 시세 API 연동

화면이 완성된 다음에 update_prices.py를 붙였다. 한국 ETF는 pykrx, 미국 종목은 yfinance로 종가를 가져와 prices.json을 갱신하는 스크립트다.

여기서 가장 중요한 규칙 하나를 Claude Code에 명확히 전달했다.

"API 호출이 실패하면 기존 prices.json을 절대 덮어쓰지 마. 실패했다는 status만 남겨. 0으로 채우는 것도 금지."

이 규칙을 처음에 안 줬더니 API 오류 시 전체 데이터가 0으로 초기화됐다. 포트폴리오가 -100%로 표시되는 황당한 화면을 보고 나서 추가했다.

3단계: GitHub Actions 자동화

스크립트가 로컬에서 정상 작동하는 것 확인 후 GitHub Actions로 옮겼다. 매 평일 오전 6시 30분(한국 시간) 자동 실행, prices.json이 갱신되면 Vercel이 자동으로 재배포한다.

on:
  schedule:
    - cron: '30 21 * * 0-4'  # UTC 21:30 = KST 06:30, 일~목(다음날 월~금 아침)
  workflow_dispatch:           # 수동 실행 버튼

실제로 Claude Code에 내린 지시 — 좋은 예 vs 나쁜 예

Claude Code를 쓰면서 깨달은 게 있다. 지시의 품질이 결과물의 품질을 거의 결정한다.

❌ 나쁜 지시	✅ 좋은 지시
포트폴리오 카드 예쁘게 만들어줘	포트폴리오 카드를 수익률 기준 내림차순으로 정렬하고, 손실(-) 종목은 빨간 배경(--soft-red)으로 강조해줘
이자 계산해줘	settings.json의 loanRate와 plannedInvestment를 읽어서 월 이자를 계산하고, KPI 카드에 "월 이자: XXX원" 형식으로 표시해. 천 단위 콤마 포함.
API 오류 처리해줘	pykrx API 호출 실패 시 기존 prices.json을 보존하고, 해당 종목의 status를 "error"로, 에러 메시지를 error_message 필드에 저장해. 절대 0으로 채우지 마.

완성 후 실제 사용 소감

매일 아침 대시보드를 열면 6개 KPI 카드가 바로 보인다. 대출 이자가 이번 달 얼마인지, 현재 포트폴리오가 이자를 커버하고 있는지, 미사용 버퍼가 얼마인지.

가장 유용한 건 리스크 룰 알림이다. 추가 투자금 기준 -7% 이하 도달 시 경고 배너가 뜨도록 설정해뒀는데, 감정 없이 숫자로 상태를 알려준다. "지금은 추가 매수 타이밍이 아니다"를 화면이 알려주는 것이다.

제작 기간은 총 3일이었다. 코드를 처음부터 작성했다면 2~3주는 걸렸을 것이다. Claude Code 없이는 이 프로젝트를 혼자 완성하지 못했을 것 같다.

💡 핵심 포인트
Claude Code는 "처음부터 끝까지 다 맡기는 도구"가 아니다. 반복 작업과 보일러플레이트의 70%를 위임하는 도구다. 설계 결정(무엇을 만들지, 어떤 구조로)은 여전히 사람이 해야 하고, 그 결정을 문서화해서 넘겨줄수록 결과가 좋아진다.

전체 설계도

[기획 단계]
 요구사항 자연어 정리
        ↓
 Claude Code → spec.md 구조화
        ↓
 A/B/C안 검토 → A안(Executive Dashboard) 선택

[구현 단계 — 3단계]
 1단계: 정적 화면
   portfolio.json (더미 데이터)
          ↓
   React 컴포넌트 렌더링 → 화면 완성 확인
          ↓
 2단계: 시세 연동
   update_prices.py
     pykrx → 한국 ETF 종가
     yfinance → 미국 주식 종가
     ExchangeRate API → USD/KRW
          ↓
   prices.json 갱신 (실패 시 기존 유지)
          ↓
 3단계: 자동화
   GitHub Actions (cron: 매 평일 06:30 KST)
          ↓
   update_prices.py 실행
          ↓
   prices.json 변경 → git push
          ↓
   Vercel 감지 → 자동 재배포

[운영 구조]
 브라우저 접속 (Vercel URL)
   └─ KPI 카드: 대출 이자, 손익, 버퍼
   └─ 포트폴리오 테이블: 종목별 시세·손익
   └─ 리스크 룰 배너: 임계값 초과 시 경고
   └─ 매수 체크리스트: localStorage 저장

다음으로 읽으면 좋은 글

• GitHub Actions로 주식 시세를 매일 자동 업데이트하는 방법 (다음 편)
• Claude Code를 처음 쓰는 직장인을 위한 설치 및 시작 가이드

⚠️ 투자 관련 면책고지
이 글에서 언급되는 ETF 종목, 투자 금액, 수익률은 개인적인 학습과 자동화 기록입니다. 특정 종목의 매수·매도를 추천하지 않으며, 모든 투자 판단과 책임은 독자 본인에게 있습니다.