pip install vibe-trading-ai 한 줄로 깔린다. 중요한 전제: 실제 매매는 하지 않는다 — 리서치·시뮬레이션·백테스트 전용이다. (저장소: HKUDS/Vibe-Trading · Python+FastAPI 백엔드 + React 19 프론트 · MIT 라이선스 · MCP 서버 22개 툴 내장)한 문장으로 이 프로젝트가 뭘 하는지부터.
Vibe-Trading = "금융 질문 → 실행 가능한 분석" 변환기. 사람이 평소 말로 하는 금융 질문("애플 모멘텀 분석해줘", "RSI 평균회귀 전략을 비트코인에 6개월 백테스트")을 던지면, 내장된 에이전트가 어떤 스킬·도구·데이터·백테스트 엔진을 써야 할지 스스로 정하고 끝까지 실행해 리포트를 만든다.
보통의 트레이딩 봇은 "정해진 규칙대로 사고팔기"만 한다. 반면 Vibe-Trading은 질문을 이해 → 자료 수집 → 전략 코딩 → 백테스트 → 검증 → 리포트 작성까지, 사람 애널리스트가 하던 사고 과정을 통째로 흉내 낸다.
그래서 결과물도 "매수/매도 신호 한 개"가 아니라, 근거·지표·벤치마크 비교·재현 가능한 실행 카드가 담긴 리서치 보고서 한 편이다.
핵심 철학은 "실거래 없음(no live trading)"이다. 돈을 직접 주문하지 않고, 리서치·시뮬레이션·백테스트만 한다. 덕분에 "AI가 멋대로 내 계좌를 털까?" 하는 위험 없이, 전략을 마음껏 실험하는 연습장 + 분석 도구로 쓸 수 있다.
TrendShift 일간 6위까지 올라온 이유 — 트렌딩의 배경.
2025~2026년은 "에이전트가 전문직 업무를 대신하는" 흐름이 본격화된 해다. 코딩(Claude Code), 리서치(딥리서치)에 이어, 이번엔 "퀀트 애널리스트의 업무 흐름 전체"를 에이전트로 묶은 것이 Vibe-Trading이다. 트렌딩 이유를 넷으로 정리한다.
원래 백테스트를 하려면 pandas로 데이터 불러오고, 전략 로직을 직접 짜고, 성과 지표를 계산하는 코드를 며칠씩 붙잡아야 했다. Vibe-Trading은 이걸 vibe-trading run -p "..." 한 줄로 줄였다. 코드를 못 짜는 사람도 금융 아이디어를 즉시 검증할 수 있다는 점이 가장 큰 매력이다.
A주(중국)·홍콩/미국 주식·암호화폐·선물·외환까지 한 도구로 다룬다. 게다가 AKShare·yfinance·OKX·CCXT 덕분에 API 키 하나 없이도 대부분의 시세를 무료로 가져온다. 한 소스가 막히면 자동으로 다른 소스로 넘어가는 폴백(fallback)까지 들어 있다.
혼자 분석하는 게 아니라, 투자위원회·퀀트 데스크·크립토 데스크 같은 29개의 가상 팀(스웜)을 띄울 수 있다. 강세론자 vs 약세론자가 토론하고, 리스크 매니저가 검토한 뒤, PM(포트폴리오 매니저)이 최종 판단을 내리는 식이다. 한 LLM에게 "다 알아서 해"라고 맡기는 것보다 관점이 충돌하며 다듬어지는 효과가 있다.
학계·업계에서 검증된 퀀트 팩터(알파) 452개를 vibe-trading alpha bench 한 줄로 내 종목군에 돌려, 어떤 팩터가 아직 살아있고(alive) 어떤 게 죽었는지(dead) 즉시 채점한다. Microsoft Qlib 158개, Kakushadze 101개, 국태군안 191개 등을 미리 담아 둔 게 "알파 동물원(Alpha Zoo)"이다.
기존 퀀트 도구 = 비싼 전문가용 공작기계 — 다룰 줄 알면 강력하지만, 매뉴얼이 두껍고 배우는 데 몇 달 걸린다.
Vibe-Trading = 말로 주문하는 자동 공방 — "이런 거 만들어줘"라고 말하면, 기계 세팅·재료 준비·가공·검수까지 알아서 해주고, 도면(코드)과 검사서(리포트)를 함께 내준다.
이 도구는 실거래를 하지 않고, 백테스트가 좋아도 미래 수익을 보장하지 않는다(과거 성과 ≠ 미래 성과). 또 에이전트는 도구를 안 쓰고 학습 기억으로 '그럴듯하게 지어내는' 환각 위험이 있어, README도 "작은/증류 모델은 쓰지 말라"고 못 박는다. "트렌딩이라 믿을 만하다"가 아니라, 에이전트·백테스트·멀티마켓 데이터 구조를 공부하기 좋은 최신 사례로 보는 게 맞다. 투자 판단의 근거로 삼기 전엔 반드시 사람이 검증해야 한다.
pyproject.toml · README · 소스 트리에서 뽑아낸 실제 구성.
Vibe-Trading은 ⓐ 백엔드(에이전트·백테스트 두뇌) ⓑ 프론트엔드(웹 UI) ⓒ 인프라·배포 세 층으로 깔끔하게 나뉜다. 모놀리식 한 덩어리가 아니라, CLI·웹·MCP 세 입구가 같은 엔진을 공유하는 구조다.
| 구성요소 | 무엇 | 역할 |
|---|---|---|
| Python 3.11+ | 런타임 | 전체 백엔드 언어. PyPI 패키지명 vibe-trading-ai. |
| FastAPI | 웹 API 프레임워크 | runs·sessions·upload·swarm·SSE 엔드포인트 제공. /docs 자동 문서. |
| ReAct 에이전트 루프 | 자체 구현 | "생각→도구 호출→관찰" 반복. 5단계 컨텍스트 압축 + 읽기/쓰기 도구 배칭. |
| LangChain (ChatOpenAI 계열) | LLM 추상화 | 14개 공급자(OpenRouter·OpenAI·DeepSeek·Gemini·Qwen·Kimi·Ollama 등)를 한 인터페이스로. |
| pandas / numpy | 데이터 연산 | 시세 패널 처리, 팩터 계산, 백테스트 시뮬레이션의 토대. |
| JSONL + SQLite FTS5 | 세션 저장·검색 | 멀티턴 대화는 JSONL 파일에 저장하고, SQLite FTS5는 세션 간 전문(full-text) 검색 인덱스 전용이다. |
| 구성요소 | 무엇 | 역할 |
|---|---|---|
| 9개+ 데이터 로더 | tushare·baostock·mootdx·tencent·okx·yfinance·akshare·ccxt·futu | A주/홍콩/미국/암호화폐/선물/외환 시세. Registry + 자동 폴백 체인. |
| 7개 백테스트 엔진 | 주식·중국선물·글로벌선물·외환·옵션 등 | 시장별 규칙으로 백테스트. CompositeEngine이 여러 시장을 한 자본풀로 섞어 백테스트. |
| Alpha Zoo | 452개 퀀트 알파 | 19개 연산자(rank/ts_*/decay_linear 등) + AST 순수성 게이트 + 룩어헤드 차단. |
| 옵티마이저 | MVO·equal vol·max div·risk parity | 포트폴리오 비중 최적화 4종. |
| 검증 도구 | Monte Carlo·Bootstrap·Walk-Forward | 백테스트 과적합을 의심하는 통계 검증 + 재현용 run_card.json. |
| 구성요소 | 무엇 | 역할 |
|---|---|---|
| React 19 + Vite + TypeScript | 웹 UI | Home·Agent·AlphaZoo·RunDetail·Compare·Correlation·Settings 페이지. |
| Zustand | 상태 관리 | 가볍고 단순한 프론트 전역 상태 스토어. |
| ECharts | 차트 | 상관관계 히트맵·성과 곡선 등 시각화. |
| Docker (멀티스테이지) | 컨테이너 | docker compose up 한 줄 배포. 기본 비루트 사용자 + localhost 전용 포트. |
| MCP 서버 (stdio) | 도구 노출 | Claude Desktop·OpenClaw·Cursor 등에 36개 트레이딩 툴을 꽂는 다리. |
금융 데이터는 출처마다 형식·커버리지·요금이 다르다. Vibe-Trading은 DataLoader라는 공통 규격(Protocol)을 정하고, 각 소스를 그 규격에 맞춰 끼워 넣는다. 그래서 "A주는 Tushare가 막히면 AKShare로" 같은 자동 폴백이 가능하다. 데이터 출처가 바뀌어도 위쪽(전략·백테스트) 코드는 손댈 필요가 없다.
자연어 한 줄이 리포트가 되기까지 — 데이터의 여정.
Vibe-Trading의 모든 실행은 5단계 증거 경로를 따른다: 요청을 분류(Plan) → 시장 맥락 적재(Ground) → 도구 실행(Execute) → 출력 검증(Validate) → 산출물 전달(Deliver). 이걸 그림으로 보면 이렇다.
이름은 ReAct = Reason(추론) + Act(행동). LLM이 한 번에 답을 뱉는 게 아니라, "지금 뭘 알아야 하지?(추론) → 이 도구를 쓰자(행동) → 결과를 보니(관찰) → 다음은…"을 목표가 끝날 때까지 반복한다. loop.py가 이 루프를 돌리고, 대화가 길어지면 5단계 컨텍스트 압축으로 오래된 맥락을 요약해 토큰을 아낀다.
77개 금융 스킬은 각각 SKILL.md 파일이다. 에이전트는 필요할 때만 해당 스킬을 읽어 들이고(점진적 공개, progressive disclosure), 심지어 새 스킬을 스스로 만들고 고치고 지울 수도 있다(skill_writer 도구). 반복되는 리서치 루틴을 "재사용 가능한 스킬"로 굳히는 자기 진화 구조다.
스웜 프리셋은 여러 에이전트를 DAG(방향성 비순환 그래프)로 엮은 워크플로다. 예를 들어 investment_committee는 "강세론자 → 약세론자 → 리스크 검토 → PM 최종결정" 순서로 흐른다. 각 워커는 실제로 가져온 시장 데이터로 근거를 잡고, 진행 상황은 스트리밍으로 보여준다.
DataLoader Protocol + Registry 조합. 시장별로 "1순위 소스 실패 → 2순위 → 3순위" 폴백 체인을 등록해 둔다. 위쪽 코드는 "A주 일봉 줘"라고만 하면 되고, 어떤 소스가 응답할지는 Registry가 알아서 고른다. 관심사 분리(separation of concerns)의 교과서적 예시다.
레포를 클론하면 보이는 폴더들 — 어디에 뭐가 있나.
한눈에 정리하면: agent/src/agent/가 두뇌(에이전트 루프), agent/backtest/가 손발(데이터·백테스트), agent/src/skills/가 지식(스킬), frontend/가 얼굴(웹 UI)이다. 공부를 시작한다면 agent/src/agent/loop.py와 backtest/loaders/registry.py 두 파일이 구조를 이해하는 지름길이다.
agent/src/agent/ = 기획실(무엇을 할지 결정), backtest/ = 실행팀(데이터 가져와 돌리기), skills/ = 사내 매뉴얼 도서관(필요할 때 꺼내 보는 75권), swarm/ = TF팀 편성표(29개 프로젝트 조직도), frontend/ = 고객 응대 창구. 입구(CLI/Web/MCP)는 다르지만 모두 같은 기획실로 연결된다.
이 레포에서 무엇을, 어떻게 배울 수 있나.
loop.py를 읽으면 "LLM이 어떻게 도구를 골라 쓰고, 결과를 다시 추론에 넣는지"의 실전 구현을 볼 수 있다. 특히 5단계 컨텍스트 압축과 읽기/쓰기 도구 배칭은 긴 세션에서 토큰을 아끼는 실무 기법이다.
실습 아이디어: loop.py의 도구 호출 부분에 로그를 심어, 내 질문 하나가 몇 번의 "생각→도구" 루프를 도는지 직접 세어 본다.
Python의 Protocol(구조적 타이핑)로 "데이터 소스 갈아끼우기"를 어떻게 깔끔하게 만드는지 배운다. 새 데이터 소스를 추가하려면 Protocol만 만족시키면 되고, Registry에 등록하면 폴백 체인에 자동 합류한다. 확장에는 열려 있고 수정에는 닫혀 있는 설계(OCP)의 표본.
실습 아이디어: 가짜(mock) 로더를 하나 만들어 Registry에 등록하고, 폴백 체인에서 호출되는지 테스트한다.
여러 LLM 에이전트를 DAG로 엮어 "역할 분담 + 토론 + 합의"를 만드는 패턴. swarm/presets/*.yaml을 열어 보면, 복잡한 워크플로를 코드가 아니라 선언적 YAML로 표현하는 방식을 배울 수 있다.
실습 아이디어: 기존 프리셋을 복사해 "3명짜리 미니 토론 팀" YAML을 직접 만들어 /swarm run으로 돌려 본다.
Alpha Zoo의 base.py 19개 연산자(rank·ts_rank·delta·decay_linear…)는 퀀트 팩터의 기본 어휘다. 여기에 룩어헤드 차단·몬테카를로·Walk-Forward까지 보면, "백테스트를 어떻게 속이지 않고 정직하게 하는가"라는 실전 퀀트의 핵심을 익힐 수 있다.
실습 아이디어: vibe-trading alpha show gtja191_171로 한 알파의 수식을 꺼내, 종이에 직접 연산자 흐름을 풀어 본다.
에이전트의 진행 상황을 실시간으로 브라우저에 흘려보내는 SSE(Server-Sent Events) 패턴을 api_server.py에서 배운다. 긴 작업(백테스트·스웜)의 "멈춘 것처럼 보이는" 문제를 하트비트·진행 단계 마커로 푸는 실전 UX도 함께 들어 있다.
실습 아이디어: /sessions/{id}/events SSE 스트림을 curl -N으로 받아, 이벤트가 어떤 형식으로 오는지 관찰한다.
내 컴퓨터에서 돌리려면 뭐가 필요한가.
이건 거대한 음성/이미지 모델이 아니라 "LLM API를 호출하는 가벼운 에이전트"다. 그래서 무거운 GPU가 필요 없다 — 진짜 계산은 LLM 공급자 서버(또는 로컬 Ollama)가 한다. 내 컴퓨터는 데이터 정리·백테스트·웹 UI만 돌리면 된다.
| 항목 | 요구사항 | 비고 |
|---|---|---|
| Python | 3.11+ | 로컬 설치(Path B) 시 필요. |
| LLM | API 키 1개 또는 Ollama | OpenRouter·DeepSeek·Kimi·Qwen 등 13종 / Ollama는 키 불필요(로컬). |
| 시세 데이터 | 키 없이 무료 가능 | AKShare(A주)·yfinance(홍콩/미국)·OKX(암호화폐)·CCXT. Tushare 토큰은 선택. |
| GPU | 불필요 | 로컬 Ollama로 LLM을 직접 돌릴 때만 GPU/메모리가 영향. |
| Docker | 선택(Path A) | docker compose up --build → http://localhost:8899. |
| 설치 시간 | 1~5분 | ClawHub 1분 / Docker 2분 / 로컬 5분. |
Vibe-Trading은 도구를 많이 쓰는(tool-heavy) 에이전트라, 모델이 도구 호출을 제대로 못 하면 "스킬을 안 불러오고 기억으로 지어내는" 사태가 난다. README는 *-nano·*-flash-lite 같은 소형/증류 모델을 "에이전트 용도로 쓰지 말라"고 명시한다. 기본 추천은 DeepSeek·Kimi·Qwen·GLM 같은 "스위트 스폿" 모델이다.
localhost CLI/웹은 마찰 없이 쓰되, 네트워크로 API를 열면 API_AUTH_KEY Bearer 토큰을 요구한다. 셸 도구는 기본 비활성(VIBE_TRADING_ENABLE_SHELL_TOOLS=1로 명시 opt-in), 문서/저널 읽기는 허용 폴더로 샌드박스되며, Docker는 비루트 사용자 + localhost 전용 포트로 뜬다.
난이도별 5개 — 손으로 익히는 게 최고다.
pip install vibe-trading-ai → vibe-trading init 후, "BTC-USDT 20/50 이동평균 전략을 2024년으로 백테스트하고 수익률·낙폭 요약해줘"를 실행한다. 키 없이 OKX 데이터로 돌아간다. 목표: 에이전트가 데이터 적재 → 코드 생성 → 백테스트 → 요약을 어떻게 자동으로 잇는지 트레이스(/trace)로 관찰.
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20을 돌려, 어떤 팩터가 alive/reversed/dead로 나오는지 본다. 목표: "IC(정보계수)"가 무엇이고, 검증된 학술 팩터도 시대에 따라 죽는다는 사실을 체감.
vibe-trading --swarm-run investment_committee '{"topic":"엔비디아 지금 매수 적정한가?"}'를 실행해, 강세/약세/리스크/PM이 주고받는 흐름을 스트리밍으로 본다. 목표: 단일 LLM 답변과 "관점 충돌형" 답변의 질적 차이를 비교.
증권사 거래내역 CSV를 --upload한 뒤 "내 매매 행태를 분석하고 그림자 전략을 추출해 실제 거래와 비교해줘"를 실행. 목표: 처분효과·과잉매매·추격매수 같은 행동 편향이 데이터로 어떻게 진단되는지 확인.
backtest/loaders/base.py의 Protocol을 만족하는 가짜 로더를 만들어 Registry에 등록하거나, SKILL.md 한 장을 새로 써서 에이전트가 그 스킬을 불러 쓰게 한다. 목표: "확장에 열린" 플러그인 구조를 직접 손으로 확장하며 체득.
이 레포를 발판으로 4주 코스를 짠다면.
| 주차 | 주제 | 학습 내용 & 실습 |
|---|---|---|
| 1주차 | LLM 에이전트 기초 | ReAct 패턴, 도구 호출(function calling), 컨텍스트 관리. loop.py·context.py 정독 + 도구 호출 로그 분석. |
| 2주차 | 퀀트 & 백테스트 | 팩터 투자, 룩어헤드 편향, 샤프지수·최대낙폭, Walk-Forward 검증. Alpha Zoo 연산자 손으로 풀어 보기. |
| 3주차 | 멀티 에이전트 오케스트레이션 | DAG 워크플로, 역할 기반 협업, 스트리밍. 스웜 프리셋 YAML 직접 설계 + 실행. |
| 4주차 | 서비스화 (FastAPI+React+MCP) | SSE 스트리밍, Zustand 상태관리, MCP 서버/클라이언트, Docker 배포·보안 기본값. |
금융 지식이 약하면 2주차(퀀트)부터, 백엔드/에이전트가 궁금하면 1주차(에이전트)부터 시작하면 된다. 가장 빨리 흥미가 붙는 길은 "8번 실습 1·2번을 먼저 돌려 본 뒤, 그 트레이스를 보며 1주차 코드를 읽는" 역방향 학습이다.
레포 문서에 자주 나오는 용어 빠른 정리.
alpha bench가 이 IC로 alive/dead를 판정한다.run_card.json/run_card.md로 어떤 데이터·파라미터·결과였는지 기록해, 나중에 똑같이 재현하거나 신뢰성을 검증할 수 있게 한다(Trust Layer)./pine 한 줄로 세 곳에 동시 변환.더 깊이 파고들 곳.
| 리소스 | 주소 / 명령 | 용도 |
|---|---|---|
| GitHub 저장소 | github.com/HKUDS/Vibe-Trading | 소스코드 · README · 이슈 · 로드맵. |
| 공식 웹사이트 | vibetrading.wiki | 문서 · 튜토리얼 · Research Lab · Alpha Library. |
| PyPI 패키지 | pip install vibe-trading-ai | 한 줄 설치. |
| 한국어 README | README_ko.md (저장소 내) | 공식 한국어 안내 문서. |
| ClawHub | clawhub.ai/skills/vibe-trading | 에이전트 스킬 + MCP 원클릭 설치. |
| HKUDS 생태계 | NanoBot · AI-Trader · CLI-Anything · OpenSpace · ClawTeam | 같은 연구실의 자매 프로젝트들. |