VCP 스크리너 - 미네르비니 변동성 수축 패턴은(는) 무엇을 하나요?
S&P 500 종목 중 Mark Minervini의 변동성 수축 패턴(VCP)을 스크리닝하여, 변동성이 수축되고 브레이크아웃 피벗 부근에 있는 Stage 2 상승 추세 종목을 식별합니다.
사용 시기
- 사용자가 VCP 스크리닝 또는 미네르비니 스타일의 설정을 요청할 때
- 사용자가 타이트 베이스 / 변동성 수축 패턴을 찾고자 할 때
- 사용자가 Stage 2 모멘텀 주식 스캔을 요청할 때
- 사용자가 명확한 리스크가 정의된 브레이크아웃 후보를 요청할 때
- 사용자가 "의 모든 과거 VCP를 찾아줘" 또는 한 티커의 과거 VCP 설정을 전방 결과와 함께 연구하고자 할 때 (
--history --ticker SYM)
전제 조건
- FMP API 키 (
FMP_API_KEY환경 변수 설정 또는--api-key전달) - 무료 티어(하루 250회 호출)는 기본 스크리닝(상위 100개 후보)에 충분함
- 전체 S&P 500 스크리닝(
--full-sp500)에는 유료 티어 권장
워크플로우
단계 1: 스크리닝 준비 및 실행
VCP 스크리너 스크립트 실행:
# 기본: S&P 500, 상위 100개 후보
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts
# 사용자 정의 유니버스
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts
# 전체 S&P 500 (유료 API 티어)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts
엄격 모드 (미네르비니 순수 설정)
valid_vcp=True이고 execution_state가 (Pre-breakout, Breakout)인 종목만 반환:
python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/
단일 티커 히스토리 모드
한 티커의 다년간 가격 내역을 탐색하여, 형성된 모든 VCP를 탐지하고 각 탐지에 전방 결과 통계(브레이크아웃 / 손절 / 타임아웃, 결과까지 걸린 일수, 최대 이익, 최대 손실)를 첨부합니다. 패턴 연구 및 백테스팅 컨텍스트에 유용하며, 실시간 스크리너가 아닙니다.
# 기본: 약 5년 (1260 거래일), 5일 간격, 60일 결과 창
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history --ticker FIX --output-dir reports/
# 사용자 지정 스캔 길이: 750 거래일 (약 3년), 90일 결과 창
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history 750 --ticker TSLA \
--stride-days 5 --outcome-days 90 \
--output-dir reports/
# 장기 스캔: 10년 (2520 거래일)
python3 skills/vcp-screener/scripts/screen_vcp.py \
--history 2520 --ticker NVDA --output-dir reports/
출력 (타임스탬프 포함):
vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json— 전체 분석기 페이로드 + 탐지별forward_outcome+ 요약 통계가 포함된 탐지 타임라인vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md— 사람이 읽을 수 있는 타임라인
모드별 플래그:
| 매개변수 | 기본값 | 범위 | 효과 |
|---|---|---|---|
--history [DAYS] | (꺼짐) / 1260 (값 없으면) | 100-5040 | 히스토리 모드 활성화; 선택적으로 거래일 스캔 창 지정 (--ticker 필요) |
--ticker SYM | — | — | 스캔할 티커 |
--stride-days | 5 | 1-60 | 기준 커서 위치 사이의 거래일 간격 |
--outcome-days | 60 | 5-252 | 탐지당 평가되는 전방 창 |
참고:
- 횡단면 파이프라인과 달리 스캔당 FMP API 호출 2회(티커 + SPY 히스토리)만 필요
marketCap및 절대 RS 백분위수는 라이브 스크리닝 유니버스가 아닌 해당 티커 단독으로 반영되므로, 포트폴리오 사이징이 아닌 패턴 연구에 사용- 탐지는
(T1_high_date, last_low_date, pivot)별로 중복 제거되어 커서가 이동해도 동일한 VCP가 반복 보고되지 않음
고급 튜닝 (백테스팅용)
연구 및 백테스팅을 위한 VCP 탐지 매개변수 조정:
python3 skills/vcp-screener/scripts/screen_vcp.py \
--min-contractions 3 \
--t1-depth-min 12.0 \
--breakout-volume-ratio 2.0 \
--trend-min-score 90 \
--atr-multiplier 1.5 \
--output-dir reports/
| 매개변수 | 기본값 | 범위 | 효과 |
|---|---|---|---|
--min-contractions | 2 | 2-4 | 높을수록 패턴 수는 적지만 품질 향상 |
--t1-depth-min | 10.0% | 1-50 | 높을수록 얕은 첫 번째 조정 제외 |
--breakout-volume-ratio | 1.5x | 0.5-10 | 높을수록 거래량 확인 엄격 |
--trend-min-score | 85 | 0-100 | 높을수록 Stage 2 필터 엄격 |
--atr-multiplier | 1.5 | 0.5-5 | 낮을수록 스윙 탐지 민감도 증가 |
--contraction-ratio | 0.70 | 0.1-1 | 낮을수록 더 타이트한 수축 필요 |
--min-contraction-days | 5 | 1-30 | 높을수록 최소 수축 기간 증가 |
--lookback-days | 120 | 30-365 | 길수록 오래된 패턴 발견 |
--max-sma200-extension | 50.0% | — | 과도 확장 상태 및 패널티에 대한 SMA200 거리 임계값 |
--wide-and-loose-threshold | 15.0% | — | 이 임계값 이상이면 최종 수축 깊이에서 와이드-앤-루즈 플래그 트리거 |
--strict | 꺼짐 | — | 미네르비니 엄격 모드: Pre-breakout 또는 Breakout이면서 valid VCP인 경우만 |
단계 2: 결과 검토
- 생성된 JSON 및 Markdown 보고서 읽기
- 패턴 해석 컨텍스트를 위해
references/vcp_methodology.md로드 - 점수 임계값 지침을 위해
references/scoring_system.md로드
단계 3: 분석 제시
각 상위 후보에 대해 다음 제시:
- 품질 (
composite_score/ 등급) — VCP 패턴이 얼마나 잘 형성되었는가? - 실행 상태 (
execution_state) — 지금 매수 가능한가? (Pre-breakout / Breakout = 실행 가능) - 패턴 유형 (
pattern_type) — Textbook VCP / VCP-adjacent / Post-breakout / Extended Leader / Damaged - 상태 한도가 적용된 경우
★표시 (원 점수가 하향 조정됨) - 수축 세부 사항 (T1/T2/T3 깊이 및 비율)
- 거래 설정: 피벗 가격, 손절가, 리스크 비율
- 거래량 건조 비율 및 브레이크아웃 거래량 점수
- 상대 강도 순위
단계 4: 실행 가능한 지침 제공
실행 상태별 (1차 필터):
- Pre-breakout / Breakout: 패턴이 활성 진입 구간에 있음 — 등급 기반 사이징 적용
- Early-post-breakout: 브레이크아웃 진행 중이지만 이상적인 진입 부근 아님 — 축소 사이징 또는 풀백 대기
- Extended / Overextended: 거래 기회 놓침 — 다음 베이스를 위해 워치리스트에 추가
- Damaged / Invalid: 설정 무효 — 진입 금지
등급별 (2차, 상태가 실행 가능성을 확인한 후):
- Textbook VCP (90+): 피벗에서 공격적 사이징으로 매수 (1.5-2x)
- Strong VCP (80-89): 피벗에서 표준 사이징으로 매수 (1x)
- Good VCP (70-79): 피벗 위 거래량 확인 시 매수 (0.75x)
- Developing (60-69): 워치리스트에 추가, 더 타이트한 수축 대기
- Weak/No VCP (<60): 모니터링만 또는 건너뛰기
3단계 파이프라인
- 사전 필터 - 시세 기반 스크리닝 (가격, 거래량, 52주 위치) ~101회 API 호출
- 추세 템플릿 - 260일 히스토리를 사용한 7점 Stage 2 필터 ~100회 API 호출
- VCP 탐지 - 패턴 분석, 점수 매기기, 보고서 생성 (추가 API 호출 없음)
출력
vcp_screener_YYYY-MM-DD_HHMMSS.json- 구조화된 결과vcp_screener_YYYY-MM-DD_HHMMSS.md- 사람이 읽을 수 있는 보고서
리소스
references/vcp_methodology.md- VCP 이론 및 추세 템플릿 설명references/scoring_system.md- 점수 임계값 및 구성 요소 가중치references/fmp_api_endpoints.md- API 엔드포인트 및 비율 제한