| name | kis-backtester |
| description | KIS 전략을 과거 데이터로 검증하거나 성과를 확인할 때 반드시 사용. '백테스팅', '백테스트 해줘', '전략 검증', '성과 분석', '파라미터 최적화', '수익률 확인', '과거 검증', '샤프 확인', '최대낙폭 보고 싶어', '이 전략 수익률이 어떻게 돼?'라고 할 때 자동 실행된다. backtester MCP 서버를 통해 10개 프리셋(sma_crossover, momentum 등) 또는 .kis.yaml 전략 실행, BacktestResult(총수익률·CAGR·최대낙폭·샤프) 해석, Grid/Random 파라미터 최적화, 배치 전략 비교, 포트폴리오 분석, HTML 리포트 생성을 수행한다. |
| model | sonnet |
[Step 2] KIS 백테스팅
Purpose
backtester 백테스팅 시스템으로 전략의 과거 성과를 검증한다.
10개 프리셋 또는 Step 1에서 만든 .kis.yaml을 실행해 수익률·샤프·최대낙폭을 확인하고,
파라미터 최적화와 HTML 리포트 생성까지 지원한다.
날짜 관련 사용자의 요청이 없으면 모든 end_date는 시스템 날짜로 오늘 날짜를 기본으로 하며(datetime.today()) start_date는 1년전을 기본으로 넣는다.
Prerequisites (필수 — 미충족 시 실행 불가)
- Docker 실행 중 (
quantconnect/lean:latest) — 백테스트 엔진이 Docker 컨테이너로 동작
- KIS 인증 완료 (
/auth vps 또는 /auth prod)
docker ps
docker pull quantconnect/lean:latest
서버 시작
cd $CLAUDE_PROJECT_DIR/backtester && bash scripts/start_mcp.sh
cd $CLAUDE_PROJECT_DIR/backtester && uv run uvicorn backend.main:app --reload --port 8002
cd $CLAUDE_PROJECT_DIR/backtester/frontend && pnpm dev
Workflow
0. 백테스트 조건 확인 (커스텀 YAML인 경우)
커스텀 YAML(프리셋이 아닌)로 백테스트 요청이 들어오면, 실행 전 사용자에게 조건을 확인받는다:
📋 백테스트 조건 확인
| 항목 | 값 |
|------|-----|
| 전략 | 삼성전자 스윙 전략 |
| 종목 | 005930 (삼성전자) |
| 기간 | 2024-02-25 ~ 2026-02-25 (1년) |
| 초기자금 | 10,000,000원 |
| 주요 지표 | EMA(20,60), RSI(14), ATR(14) |
| 진입 | EMA 골든크로스 AND RSI < 40 |
| 청산 | EMA 데드크로스 OR RSI > 70 |
| 손절/익절 | 4.0% / 12.0% |
이 조건으로 백테스트를 실행할까요? 변경할 항목이 있으면 말씀해주세요.
YAML 사전 검증:
validate_yaml_tool로 문법 검증- 조건의
value 필드에 $param_name 변수가 있으면 → 해당 파라미터의 default 값으로 치환 후 실행
value가 숫자가 아니면 사용자에게 알리고 수정
사용자가 확인하면 실행 단계로 진행한다.
1. 전략 선택
- 프리셋 ID:
"sma_crossover", "momentum" 등 10개
Tool: list_presets_tool # 전체 목록 + param 스키마 확인
Tool: get_preset_yaml_tool # { "strategy_id": "sma_crossover" }
- 커스텀 YAML: Step 1에서 생성한
.kis.yaml 사용
Tool: validate_yaml_tool # { "yaml_content": "..." } — 반드시 먼저 실행
# valid: false이면 errors 수정 후 재검증. valid: true 확인 후에만 실행
Tool: run_backtest_tool # yaml_content로 직접 실행
- 지표 목록 확인:
Tool: list_indicators_tool # 80개 지표 + 57개 캔들스틱 파라미터 정의
YAML 자동 생성
사용자가 "RSI+MACD 전략 백테스트 해줘"처럼 말할 경우 에이전트가 직접 YAML을 생성 후 파일로 저장해 실행한다.
생성 규칙
strategy.id: snake_case 영문+숫자+_ (고유값, 예: my_rsi_macd)strategy.indicators: 지표마다 고유 alias 필수. 같은 지표 중복 사용 시 다른 alias 사용- 다중 출력 지표(
macd, bollinger, stochastic)는 지표 정의에 output 필드로 분리하거나, 조건에서 output/compare_output 필드 사용
conditions: value(숫자) 또는 compare_to(alias) 중 하나만 — 동시 사용 금지risk: {enabled: true, percent: X.0} 형식version: "1.0" 고정
References 파일 요약
| 파일 | 내용 |
|---|
references/yaml-templates.md | 10개 YAML 기반 전략 템플릿 (golden_cross 등) — 커스텀 YAML 빠른 시작용 |
references/indicator-params.md | 21개 지표 id·params·다중출력 레퍼런스 (sma, ema, rsi, macd, bollinger 등) |
references/batch-optimize.md | run_batch_backtest_tool / optimize_strategy_tool 상세 입출력 명세 |
프리셋 → YAML 변환
references/yaml-templates.md 에서 해당 전략 복사 → alias/params 조정 → 파일 저장
커스텀 전략 → YAML 생성
references/indicator-params.md 에서 지표 id/params 확인 → 조건 조합 → 체크리스트 검증 후 저장
2. 파라미터 설정
Tool: list_presets_tool # 해당 전략의 params 스키마 확인 (type, min, max, default)
Tool: get_preset_yaml_tool # { "strategy_id": "sma_crossover", "param_overrides": {"fast_period": 50} }
각 프리셋별 주요 파라미터 (period, oversold, overbought, fast_period, slow_period 등)
3. 실행 옵션 설정
프리셋 실행 — start_date/end_date 생략 시 자동 설정 (1년 전 ~ 오늘):
Tool: run_preset_backtest_tool {
"strategy_id": "sma_crossover",
"symbols": ["005930", "000660"],
"initial_capital": 10000000,
"param_overrides": { "fast_period": 5, "slow_period": 20 }
}
→ { job_id, status: "running" }
커스텀 YAML 실행:
Tool: run_backtest_tool {
"yaml_content": "<.kis.yaml 내용>",
"symbols": ["005930"]
}
→ { job_id, status: "running" }
결과 조회 (기본: 완료까지 자동 대기, 폴링 불필요):
Tool: get_backtest_result_tool { "job_id": "<job_id>" }
→ 서버 내부에서 완료까지 대기 후 최종 결과 반환 (최대 5분)
→ 완료 시 : { status: "completed", result: { metrics, equity_curve, ... } }
→ 실패 시 : { status: "failed", error: "..." }
→ 타임아웃 : { status: "running", message: "타임아웃..." }
# 즉시 상태만 확인 (대기 없음):
Tool: get_backtest_result_tool { "job_id": "<job_id>", "wait": false }
4. 결과 해석
BacktestResult 필드:
| 필드 | 의미 |
|---|
total_return_pct | 총 수익률 (%) |
cagr | 연평균 복리 수익률 |
sharpe_ratio | 위험 대비 수익 (1.0+ 양호) |
sortino_ratio | 하락 위험 대비 수익 |
max_drawdown | 최대 낙폭 (낮을수록 좋음) |
win_rate | 승률 (%) |
profit_factor | 총이익/총손실 비율 |
total_trades | 총 거래 횟수 |
4b. 백테스트 재시도 (실패 시)
EGW00201(초당 한도 초과) 등 일시적 오류로 실패한 경우 재시도:
Tool: retry_backtest_tool { "job_id": "<실패한 job_id>" }
→ { new_job_id, status: "running" }
# 이후 get_backtest_result_tool { "job_id": "<new_job_id>" } 로 결과 조회
캐시된 데이터는 재다운로드하지 않으므로 빠르게 재실행됨.
충분히 대기(10~30초)한 뒤 호출할 것.
5. 파라미터 최적화 (선택)
→ 상세 입출력/동작 방식: references/batch-optimize.md
Tool: optimize_strategy_tool {
"strategy_id": "sma_crossover",
"symbols": ["005930"],
"parameters": [
{"name": "fast_period", "min": 2, "max": 20, "step": 3},
{"name": "slow_period", "min": 10, "max": 60, "step": 10}
],
"search_type": "grid", # 또는 "random" + "max_samples": 30
"target": "sharpe_ratio" # sharpe_ratio | total_return | max_drawdown | win_rate
}
→ { job_id, total_combinations: 12, status: "running" }
Tool: get_backtest_result_tool { "job_id": "<job_id>" }
→ { result: { best_params, best_metrics, all_runs, total_runs, successful_runs } }
# 실행 중 진행률:
Tool: get_backtest_result_tool { "job_id": "<job_id>", "wait": false }
→ { status: "running", progress: { done: 7, total: 12 } }
5b. 배치 백테스트 — 여러 전략 동시 비교 (선택)
→ 상세 입출력/동작 방식: references/batch-optimize.md
Tool: run_batch_backtest_tool {
"items": [
{"strategy_id": "sma_crossover", "symbols": ["005930"]},
{"strategy_id": "golden_cross", "symbols": ["005930"], "param_overrides": {"fast_period": 50}},
{"yaml_content": "<커스텀 YAML>", "symbols": ["000660"]}
]
}
→ { completed, comparison: { by_sharpe, by_return, by_drawdown }, runs, job_ids }
6. 포트폴리오 분석 (선택)
복수 종목을 단일 백테스트로 실행하면 포트폴리오 효과 확인 가능:
Tool: run_preset_backtest_tool {
"symbols": ["005930", "000660", "035420"],
"initial_capital": 30000000
}
# → 전체 포트폴리오 통합 성과 (equity_curve, 총수익률, 샤프)
7. HTML 리포트 생성
Tool: get_report_tool { "job_id": "<job_id>", "format": "html" }
# → 브라우저 자동 오픈 + 차트·거래 내역·통계 포함 리포트 경로 반환
Tool: get_report_tool { "job_id": "<job_id>", "format": "json" }
# → 핵심 지표 요약 JSON (총수익률, CAGR, MDD, 샤프 등)
10개 프리셋 ID 목록
| ID | 이름 | 카테고리 | 주요 파라미터 |
|---|
sma_crossover | SMA 골든/데드 크로스 | trend | fast_period, slow_period |
momentum | 모멘텀 | momentum | lookback, threshold |
trend_filter_signal | 추세 필터 + 시그널 | composite | trend_period |
week52_high | 52주 신고가 돌파 | trend | lookback, stop_loss_pct |
ma_divergence | 이동평균 이격도 | mean_reversion | period, buy_ratio, sell_ratio |
false_breakout | 추세 돌파 후 이탈 | trend | lookback |
short_term_reversal | 단기 반전 | mean_reversion | period, threshold_pct |
strong_close | 강한 종가 | momentum | close_ratio, stop_loss_pct |
volatility_breakout | 변동성 축소 후 확장 | volatility | atr_period, lookback |
consecutive_moves | 연속 상승·하락 | momentum | up_days, down_days |
결과 해석 기준
| 지표 | 기준 | 평가 |
|---|
| Sharpe Ratio | > 1.5 | 우수 / 1.0~1.5 양호 / < 1.0 개선 필요 |
| Max Drawdown | < 10% | 우수 / < 20% 권장 / > 20% 위험 |
| Win Rate | > 55% | 양호 (단, Profit Factor와 함께 해석) |
| Profit Factor | > 1.5 | 양호 / > 2.0 우수 |
Troubleshooting
- MCP 서버 미실행 →
curl http://127.0.0.1:3846/health 확인 후 bash backtester/scripts/start_mcp.sh
- Docker 미실행 →
docker ps 확인 후 Docker Desktop 시작 (필수)
- 데이터 없음 →
/auth 로 KIS 인증 상태 확인 (/auth vps or /auth prod)
- 포트 8002 충돌 →
lsof -i :8002 로 프로세스 확인 후 종료
- 최적화 느림 → 파라미터 범위 축소 또는 종목 1개로 먼저 테스트
다음 단계
- [Step 3]
/kis-order-executor — 검증된 전략으로 실전/모의 매매 실행
- [Step 1]
/kis-strategy-builder — 성과 부족 시 전략 수정
