소개
스터디에 영감을 얻어 시작한 프로젝트입니다.
"정부 정책 공고, 심리지수, 경제지표를 매번 따로 찾아보는데...
AI가 이걸 한 번에 통합 분석해주면 어떨까?"
그래서 Claude Code(claude.ai/claude-code)를 활용해서
부동산 시세 예측 AI 에이전트 시스템을 직접 만들어봤습니다.
핵심 아이디어:
- 공공 API 7개 이상을 연동해서 데이터 자동 수집
- Claude AI가 데이터를 분석하고 시세 예측
- Streamlit 대시보드로 누구나 쉽게 조회
진행 방법
【 사용 도구 】
- Claude Code (CLI) : 코드 전체 설계 및 구현
- Ralph Loop 플러그인 : 자동 반복 개선 루프
- Python 3.12
- Streamlit : 대시보드 UI
- Plotly : 차트 시각화
- httpx : API 통신
【 연동한 공공 API 】
1. 한국부동산원 R-ONE API → 아파트 가격지수, 심리지수
2. 국토부 실거래가 API → 아파트 실거래가 (공공데이터포털)
3. 한국은행 ECOS API → 기준금리, M2, CPI, 주담대금리
4. 통계청 KOSIS API → 미분양 현황, 건축허가
5. 브이월드 API → 국가공간정보 (용도지역, 좌표)
6. 나라장터 G2B API → 입찰공고 (택지개발, 도시계획)
7. 지자체 공고 크롤러 → 서울시, 경기도, 정비사업온누리
【 사용한 프롬프트 전문 】
--- 첫 번째 프롬프트 ---
나는 부동산 전문가야 정부정책 심리지표 그리고 경제 지표를 통해
부동산 시세를 예측할거야 일단 agent skill 등등 을 만들고 계획을 작성해줘
(참고한 데이터 소스 목록)
- 공공데이터포털 / API / 온비드
- 상권정보시스템 / 오픈API
- 브이월드
- 지자체 자료 공고추적 / 열람공고 결정고시 승인
- 도시관리계획
- 정보몽땅/정비사업온누리
- 전략환경영향평가/환경영향평가/소규모환경영향평가
- 조달청 나라장터 검색 입찰공고 과업지시서
- 통계청
- 아파트 - 한국부동산원 부동산테크 API 심리지표 그리고 경제 지표를 통해 부동산 시세를 예측
📁 만들어진 결과물 구조
budonsan2/
├── agents/
│ ├── orchestrator.py ← 메인 통합 에이전트 (Claude Tool Use)
│ ├── policy_agent.py ← 정책 모니터링 전문 에이전트
│ └── market_agent.py ← 시장 분석 전문 에이전트
├── skills/ ← Claude가 호출하는 도구 모음
│ ├── skill_policy.py ← 나라장터 공고, 공간정보 분석
│ ├── skill_market.py ← 실거래가, 심리지수
│ ├── skill_economic.py ← 금리, M2, CPI 분석
│ └── skill_supply.py ← 미분양, 정비사업 현황
├── collectors/ ← 각 API 수집기
│ ├── kab_collector.py
│ ├── molit_collector.py
│ ├── ecos_collector.py
│ ├── kosis_collector.py
│ ├── vworld_collector.py
│ ├── naramarket_collector.py
│ └── local_gov_crawler.py
├── models/
│ ├── price_predictor.py ← 시세 예측 모델
│ ├── feature_engineering.py
│ └── backtester.py ← 백테스트 검증
├── dashboard/
│ └── app.py ← Streamlit 대시보드 (4탭)
├── config/
│ └── api_keys.env.example
├── run.py ← 통합 실행 스크립트
└── setup.py ← 의존성 자동 설치
총 29개 파일 자동 생성
【 핵심 코드 - Agent Tool Use 구조 】
```python
# orchestrator.py 핵심 로직
# Claude가 스스로 어떤 데이터가 필요한지 판단하고 도구를 호출
ALL_TOOLS = (
skill_policy.POLICY_TOOLS # 정책: 나라장터, 브이월드
+ skill_market.MARKET_TOOLS # 시장: 실거래가, 심리지수
+ skill_economic.ECONOMIC_TOOLS # 경제: 금리, M2
+ skill_supply.SUPPLY_TOOLS # 공급: 미분양, 정비사업
)
while iteration < max_iterations:
response = client.messages.create(
model="claude-opus-4-6",
tools=ALL_TOOLS, # 11개 도구 제공
messages=messages,
)
# Claude가 필요한 도구를 선택해서 호출
# → 데이터 수집 → 재분석 → 최종 예측
```
```python
# 예측 모델 - 4가지 지표 종합
def predict(price_mom_3m, sentiment_index, rate_change, economic_score):
scores = {
"가격 모멘텀": weights["price"] * tanh(price_mom_3m / 5),
"시장 심리": weights["sentiment"] * (sentiment_index - 100) / 20,
"금리 환경": weights["rate"] -tanh(rate_change 2),
"경제 여건": weights["eco"] * economic_score / 10,
}
composite = sum(scores.values())
direction = "상승" if composite > 0.2 else ("하락" if composite < -0.2 else "보합")
return direction, composite
```
【 대시보드 실행 방법 】
1. 의존성 설치: python setup.py
2. API 키 설정: .env 파일에 키 입력
3. 대시보드 실행: python run.py dashboard
4. 브라우저 접속: http://localhost:8501
대시보드 4개 탭:
[시세 예측] 낙관/기본/비관 시나리오 + 리포트 다운로드
[시장 현황] 가격지수, 심리지수 차트, 지역별 테이블
[정책 모니터링] 지자체 공고 호재/악재 분류, 나라장터 공고
[경제지표] 기준금리, M2, CPI 대시보드
💡 결과와 배운 점
【 배운 점 & 꿀팁 】
1. Claude Code는 도메인 지식을 주면 줄수록 결과물이 달라진다
→ 막연하게 "부동산 앱 만들어줘"가 아니라
사용하는 데이터 소스, API, 분석 프레임워크를 구체적으로 알려줄수록
전문가 수준의 코드가 나온다.
2. Ralph Loop로 반복 개선이 효과적
→ "계속해봐" 한 마디로 Claude가 스스로 이전 작업을 보고
다음 단계를 이어서 구현한다.
Phase 1(수집기) → Phase 2(스킬) → Phase 3(모델) → Phase 4(대시보드)
자동으로 진행됨.
3. 자체 검증 요청이 코드 품질을 높인다
→ "자체 검증을 통해 완벽할때까지 계속 해봐"라고 하니
Claude가 직접 python -m py_compile 로 구문 검사,
FutureWarning 수정, import 체인 검증, 로직 테스트까지 수행.
4. Tool Use (함수 호출) 패턴이 핵심
→ Claude에게 도구 목록만 주면, 어떤 데이터가 필요한지
스스로 판단해서 API를 호출하고 분석한다.
GPT의 함수 호출과 동일한 개념인데 훨씬 자연스럽다.
【 시행착오 】
- Ralph Loop에 긴 텍스트를 넣으니 bash 파싱 오류 발생
→ 짧고 명확한 프롬프트로 분리해서 해결
- pandas FutureWarning: fillna(method='ffill') deprecated
→ df.ffill().fillna(0) 으로 수정
- plotly, anthropic 패키지 미설치 시 import 오류
→ try/except로 graceful fallback 처리
- Windows 환경에서 한글 출력 시 cp949 인코딩 오류
→ 검증 스크립트를 ASCII로 작성해서 우회
【 앞으로의 계획 】
Phase 3b: ML 모델 고도화
- XGBoost: 피처 중요도 기반 예측
- LSTM: 시계열 딥러닝
- Prophet: 계절성 분석
Phase 5: 알림 시스템
- 정책 호재/악재 감지 시 Slack/카카오톡 알림
- 급등/급락 조기 경 보
Phase 6: 실 데이터 연동 완성
- 현재는 일부 샘플 데이터
- 실제 API 키 발급 후 라이브 데이터 연동
【 도움이 필요한 부분 】
API가 병목이다.....
🔗 도움 받은 글 (옵션)
- 지피터스 Claude Code 스터디 자료
- Anthropic 공식 문서: Tool Use (함수 호출)
https://docs.anthropic.com/en/docs/tool-use
- 공공데이터포털 API 목록: https://www.data.go.kr
- 한국부동산원 R-ONE: https://www.reb.or.kr/r-one
- 한국은행 ECOS: https://ecos.bok.or.kr
- 브이월드: https://www.vworld.kr
