strategy-backtester

name	strategy-backtester
description	퀀트 전략 아이디어를 질문으로 정제하고 백테스트를 수행하여 시각화·통계·트레이딩 내역을 생성한다. 파라미터 튜닝을 반복하며 전략을 개선할 수 있다. '전략 아이디어', '전략 만들어줘', '백테스트', '전략 테스트', '투자 전략', '퀀트 전략', '매매 전략', '파라미터 튜닝', 'strategy idea', 'backtest', 'trading strategy' 등 요청 시 사용.

strategy-backtester

퀀트 전략 아이디어 → 질문 정제 → 백테스트 결과물(시각화 + 통계 + 트레이딩 내역) → 파라미터 튜닝 루프.

지원 파일

파일	역할	로드 시점
references/question-framework.md	전략 유형별 질문 + Period 제안 + 기본값	Phase 2 진입 시
references/output-components.md	시각화·통계·트레이드로그 구성 상세 + DataFrame 스키마	Phase 4 진입 시
references/evaluation-criteria.md	결과 평가 기준 + 의견 제시 프레임워크 + Run 비교 지표	Phase 5 진입 시
references/streamlit-templates.md	Streamlit 대시보드 패턴 + 위젯 연결 + 환경 체크	Streamlit 요청 시
references/python-templates.md	Python 스크립트 패턴 + Universe→데이터 소스 매핑	Phase 4 (Python) 진입 시
references/sheets-guide.md	Sheets 구조 + Drive 연동 가이드	Sheets 요청 시

Phase 0 — 모드 감지

사용자 요청을 3가지 모드로 분류:

모드	트리거	흐름
A. 신규 아이디어	"전략 아이디어가 있어", "이런 전략 어때"	Phase 1 → 2 → 3 → 4 → 5 → 6
B. 파라미터 튜닝	"lookback을 6개월로 바꿔봐", "손절을 -15%로"	Phase 4 → 5 → 6 (기존 스펙 기반)
C. 결과물 형식 변경	"Sheets로도 만들어줘", "Streamlit으로 바꿔"	Phase 4 (출력 형식만 변경)

모드 B/C 컨텍스트 확인 (2단계):

1. local/strategies/ 디렉토리를 Glob으로 탐색 → 저장된 전략 스펙 파일 확인
2. 파일 없으면 → 현재 세션 대화에 전략 스펙이 있는지 확인
3. 스펙 없으면 → "먼저 전략 아이디어를 알려주세요"로 모드 A 안내
4. 스펙 있으면 → 스펙 요약 보여준 뒤 해당 모드 진행

Phase 1 — 아이디어 캡처

사용자의 자유 형식 설명에서 8개 전략 차원을 자동 추출:

차원	설명	예시
Universe	거래 대상 자산	KOSPI 200, S&P 500, BTC
Signal	진입/청산 신호	20일 모멘텀, PER < 10
Timeframe	리밸런싱 주기	일간, 주간, 월간
Risk	리스크 관리 규칙	종목당 5%, 손절 -10%
Data	필요 데이터 소스	주가, 재무제표, 거시 지표
Period	백테스트 기간	2015-01 ~ 2024-12
Benchmark	성과 비교 대상	KOSPI, SPY
Constraints	제약 조건	자본금, 거래 비용, 공매도 불가

추출 후 표로 요약하고 빈 차원을 명시 → Phase 2로 진입.

Phase 2 — 구조화 질문

진입 시: references/question-framework.md Read tool로 로드하여 전략 유형별 맞춤 질문 참조.

질문 규칙:

• 빈 차원에 대해 한 번에 2-3개씩 제안형으로 질문
  • Good: "모멘텀 전략에서 룩백 기간은 3/6/12개월이 일반적입니다. 12개월부터 시작해볼까요?"
  • Bad: "룩백 기간을 정해주세요"
• 필수 3개(Universe, Signal, Timeframe) 충족 시 나머지는 기본값 제안 후 진행
• 최대 3라운드, "됐어"/"이 정도면 충분해" 시 즉시 Phase 3
• 3라운드 초과 + 필수 미충족 시: question-framework.md의 전략 유형별 기본값 자동 적용 + 명시적 안내

Period는 전략 유형별로 제안 (상세 기준은 question-framework.md 참조):

• 모멘텀: "10년 이상이 좋습니다. 2015-01 ~ 2024-12로 시작할까요?"
• 페어트레이딩: "3-5년이 적정합니다. 2020-01부터 해볼까요?"

Phase 3 — 전략 스펙 + 튜닝 파라미터 정의

전략 명세서를 생성하고 튜닝 가능 파라미터 테이블 포함:

# 전략: {전략 이름}

## 전략 스펙
| 차원 | 내용 |
| Universe | ... |
| Signal | ... |
...

## 튜닝 파라미터
| 파라미터 | 현재값 | 범위 | 설명 |
| lookback_months | 12 | 1-24 | 모멘텀 측정 기간 |
...

> 파라미터를 바꾸고 싶으면 "lookback을 6개월로 바꿔봐" 같이 말해주세요.

스펙 저장: 완료 시 local/strategies/<전략명>.json에 저장:

{
  "strategy_name": "...",
  "spec": { "universe": "...", "signal": "...", ... },
  "tuning_params": { "lookback_months": 12, ... },
  "run_history": []
}

파라미터 변경 시마다 파일 업데이트 → 세션 간 지속성 보장.

Phase 4 — 결과물 생성

진입 시: references/output-components.md + 형식에 따라 해당 references 파일 Read tool로 로드.

4-1. 출력 형식

기본 흐름: Python 스크립트로 먼저 실행 → 에이전트가 stats JSON 수치 확보 → Phase 5 평가 완료 후 Streamlit 제안.

형식	설명	에이전트 역할
Python 스크립트 (기본)	.py 파일. Bash로 직접 실행 + 결과 파싱	생성 + 실행 + 수치 수집
Python + Streamlit (2단계)	Phase 5 후 "인터랙티브 탐색하시겠어요?" 제안	생성만 (실행은 사용자)
Google Sheets	로컬 xlsx 또는 Drive 연동	생성 + (Drive는 MCP 경유)

• 사용자가 처음부터 Streamlit 요청 시: 백그라운드용 Python 스크립트도 함께 생성해 에이전트가 수치 확보
• 다른 프레임워크(Dash, Jupyter) 요청 시 그것을 사용

4-2. 데이터 소스 자동 선택

Universe 기반 자동 결정 (상세 매핑은 references/python-templates.md 참조):

Universe 키워드	데이터 소스
KOSPI, KOSDAQ, 한국 종목	pykrx
S&P, NASDAQ, 미국 종목, BTC, ETF	yfinance
혼합	pykrx + yfinance

자동 판단이 불확실하면 사용자에게 확인.

4-3. 결과물 3종

references/output-components.md 기준으로 구성. 각 구성은 제안 후 사용자 의견 반영:

• 시각화: Equity Curve, Drawdown, Monthly Heatmap, Rolling Sharpe
• 통계: CAGR, MDD, Sharpe, Sortino, Win Rate, Profit Factor 등
• 트레이드로그: date, ticker, action, quantity, price, pnl, cumulative_pnl, holding_days

4-4. Google Sheets 분기

로컬 xlsx vs Drive 연동 선택 → Drive 연동 시 gws MCP 우선 (에이전트가 credential 직접 처리 금지).

Phase 5 — 결과 평가 + 의견 제시

진입 시: references/evaluation-criteria.md Read tool로 로드.

단순 숫자 나열이 아닌 "전략 상태 진단 + 튜닝 방향 제시":

평가 항목	내용
강점	잘 작동하는 부분
주의점	위험 신호, MDD 집중 구간, 거래 비용
벤치마크 비교	상대 성과 해석
구간별 분석	시장 국면별 성과
개선 제안	구체적 튜닝 방향 제시

평가 완료 후 → "어떤 방향으로 튜닝해볼까요?" → Phase 6 자연스럽게 연결.

Phase 5 평가 후 → "인터랙티브하게 탐색하고 싶으면 Streamlit으로 변환할까요?" 제안 가능.

Phase 6 — 파라미터 튜닝 루프

Phase 5 평가 → 튜닝 방향 합의 → 파라미터 수정 → 재실행 → 결과 비교 → 재평가 → 반복

Run 비교 테이블 (핵심 지표 3개 고정):

| 파라미터 | Run 1 (원본) | Run 2 | ...  |
| lookback | 12m          | 6m    | ...  |
| CAGR     | 15.2%        | 18.1% | ...  |
| MDD      | -22%         | -31%  | ...  |
| Sharpe   | 0.82         | 0.91  | ...  |

Run 관리 정책:

• 비교 테이블에는 최근 5개 Run만 표시
• local/strategies/<전략명>.json에는 전체 히스토리 보존
• 사용자가 "Run 2 다시 보여줘" 하면 JSON 히스토리에서 복원

과최적화 경고: 파라미터를 너무 세밀하게 맞추면 과최적화 위험. in-sample/out-of-sample 분리 안내.

사용자가 방향을 모를 때: Phase 5 개선 제안을 구체적 파라미터 변경으로 연결.

제약 조건

• 수치는 에이전트가 직접 확보: Phase 5 평가에 필요한 stats는 Python 스크립트를 Bash로 실행해 stdout에서 파싱. 사용자에게 수치 복사를 요청하지 않는다.
• 외부 의존성 체크: streamlit, yfinance, pykrx 미설치 가능 → 최초 실행 시 which uv/poetry 로 패키지 매니저를 감지하고 uv → poetry → venv → pip 순으로 적절한 설치 명령을 안내. 상세 분기는 references/python-templates.md, references/streamlit-templates.md 참조.
• Sheets Drive 보안: gws MCP 경유 → 에이전트가 OAuth credential 직접 처리 금지.
• SKILL.md는 흐름 제어만: 세부 구현 패턴, 코드 템플릿, 계산 공식은 모두 references/에서 로드.