JoinQuant Skill
JoinQuant(聚宽) 플랫폼에서 수정 없이 실행되는 정량적 투자 전략 코드를 생성합니다.
이 스킬을 사용해야 하는 경우
적합한 경우:
- JoinQuant에서 주식 백테스트 / 페이퍼 트레이딩 / 실시간 트레이딩
- ETF 로테이션, 다중 팩터 종목 선정, 모멘텀, 평균 회귀 전략
- JoinQuant의 선물(期货) 전략
- 신용 거래(融资融券) 전략
- 전략 코드 리뷰 / 린트: 가짜 API 호출 및 미래 함수 위반 탐지
- 전략 아이디어를 JoinQuant API 호출로 변환
부적합한 경우:
- JoinQuant 없이 로컬 데이터 분석 (대신
jqdatasdk또는 pandas/numpy 사용) - 다른 플랫폼(vectorbt, backtrader, vn.py)에서의 전략 백테스트 (해당 스킬 사용)
- 순수 머신러닝 모델 학습 (JoinQuant 전용 API 불필요)
- JoinQuant 시뮬레이션 트레이딩 이외의 브로커 API(CTP, Interactive Brokers 등)를 통한 실시간 트레이딩 (다른 스킬 필요)
기본 모드
대부분의 사용자 요청은 세 가지 패턴 중 하나에 해당합니다. 패턴을 먼저 감지한 후 라우팅하세요:
| 패턴 | 트리거 | 액션 |
|---|---|---|
| 빠른 코드 | "X 전략을 작성해줘" / "JoinQuant로 Y를 구현해줘" | 템플릿 선택, 사용자 특정 부분 채우기, 바로 붙여넣기 가능한 코드 반환 |
| API 질문 | "JoinQuant에서 get_price의 fq 파라미터는 무엇인가요?" / "set_option에는 어떤 옵션이 있나요?" | 해당 references/XX-*.md 로드 후 그에 기반하여 답변 |
| 코드 리뷰 | "내 JoinQuant 코드를 검토해줘" / 기존 코드 붙여넣기 | 정신적(또는 실제) strategy_lint.py 실행, 가짜 API 호출 및 누락된 보호 장치 지적 |
점진적 공개: 14개 API 카테고리
모든 참조 파일을 한 번에 로드하지 마십시오(총 294KB로 컨텍스트 소모). 사용자 요청을 패턴 매칭하고 관련 카테고리 파일만 로드하세요:
| 카테고리 | 참조 파일 | 키워드 트리거 |
|---|---|---|
| 전략 설정 | references/01-strategy-setup.md | initialize, set_benchmark, set_option, set_order_cost, set_slippage, run_daily, run_weekly, run_monthly |
| 데이터 획득 | references/02-data-getters.md | get_price, attribute_history, history, get_current_data, get_fundamentals, get_money_flow, get_concept, get_industry |
| jqlib 팩터 라이브러리 | references/03-jqlib.md | alpha101, alpha191, technical_analysis, jqfactor |
| 데이터 처리 | references/04-data-processing.md | get_factor_values, calc_factor_history, neutralize, winsorize, standardlize |
| 포트폴리오 최적화 | references/05-portfolio-optimization.md | optimizer, max_sharpe, min_variance, target_return, mean_variance |
| 거래 함수 | references/06-trading.md | order, order_value, order_target, order_target_value, cancel_order, get_open_orders |
| 객체 | references/07-objects.md | Order, Position, Portfolio, OrderCost, OrderStyle, MarketOrderStyle, LimitOrderStyle |
| 기타 함수 | references/08-misc-functions.md | record, log, write_file, send_message |
| 다중 포트폴리오 | references/09-multi-portfolio.md | set_subportfolios, SubPortfolioConfig, transfer_cash |
| Tick 레벨 | references/10-tick-strategy.md | tick, get_ticks, every_tick |
| 신용 거래 | references/11-margin-trading.md | margincash_open, margincash_close, marginsec_open, marginsec_close, set_margin_rate |
| 선물 | references/12-futures.md | get_dominant_future, futures, set_future_commission |
| 기여 분석 | references/13-attribution-analysis.md | brinson, factor analysis, attribution |
| 엔진 메커니즘 | references/14-strategy-engine.md | 체결, 권리 조정, 슬리피지, 세금, 위험 지표, alpha, beta, sharpe, max drawdown |
사용자가 어떤 키워드 목록에도 없는 함수 이름을 언급하면 scripts/api_search.py <keyword>를 사용하여 모든 참조 파일에서 검색하세요.
템플릿
templates/ 디렉토리에 있는 5개의 프로덕션 준비 템플릿:
| 템플릿 | 사용 시기 |
|---|---|
01-basic-single-stock.py | 초보 사용자, 단일 주식, 단순 MA 크로스오버. JoinQuant의 "헬로 월드". |
02-multi-factor.py | 다중 팩터 종목 선정(PE / 시가총액 / 모멘텀), 월간 리밸런싱. 가장 일반적인 "실제" 전략 구조. |
03-etf-rotation.py | 모멘텀 순위 기반 ETF 로테이션. 개인 투자자에게 인기 있음. |
04-momentum-stock.py | 종목 풀 내 횡단면 모멘텀, 주간 리밸런싱. |
05-mean-reversion.py | 볼린저 / RSI 평균 회귀. 변동성 인지. |
코드 생성 시 템플릿에서 시작하여 수정하고, 처음부터 작성하지 마십시오. 이유:
- 템플릿에는 이미 보일러플레이트(set_benchmark, set_option, set_order_cost, set_slippage)가 포함되어 있습니다.
- 템플릿은 올바른 타이밍(적절한 time 인자를 사용한 run_daily / run_weekly)을 가지고 있습니다.
- 템플릿은 미래 함수 함정(날짜 기반 대신 카운트 기반 슬라이싱 사용)을 피합니다.
린트 도구
생성된 코드를 사용자에게 반환하기 전에 정신적으로(또는 실제로) strategy_lint.py를 실행하세요:
python scripts/strategy_lint.py <user_strategy.py>
중요 검사 항목:
- ❌ 가짜 API 호출 (예:
jqdata.get_stock_data()는 존재하지 않음) - ❌ 미래 함수: 하드코딩된 미래 날짜로 카운트 기반이 아닌
get_price또는attribute_history사용 - ❌
set_option('use_real_price', True)누락 (정확한 백테스트에 필수) - ❌
set_order_cost(...)및set_slippage(...)누락 - ❌
before_trading_start/after_trading_end에서 주문 배치 (금지됨, 거부됨) - ❌ 더 이상 사용되지 않는 API 사용 (
update_universe등) - ⚠️ 모듈 전역 변수 대신 막대 간 상태를 위해
g.전역 변수 권장 - ⚠️ 높은 상관관계 자산에 대해 클러스터 인지 크기 조정 권장
생성 시 반드시 유지해야 할 사항
전략에 대해 조언할 때 다음 사항을 절대 놓치지 마세요:
- 항상
use_real_price=True를 설정하세요. 기존 사전 조정 가격은 미래 함수 편향이 있습니다. 이는 협상 불가 사항입니다. set_order_cost및set_slippage는 필수입니다. 이것들이 없으면 백테스트가 비현실적이며 사용자를 오도합니다.run_daily의 time 인자는 중요합니다.'open'은 09:30에 실행되고,'every_bar'는 모든 막대(분 또는 일)마다 실행됩니다. 잘못된 선택은 잘못된 실행 타이밍을 초래합니다.g.는 유일하게 안전한 전역 상태입니다. 모듈 수준 전역 변수는 일부 JoinQuant 환경에서 실행 간에 누출될 수 있습니다.- 자본 관리 측면에서
order보다order_value가 더 좋습니다. 주식 분할 시 주식 수를 수동으로 계산하는 것은 오류가 발생하기 쉽습니다. - 리밸런싱 시
order_target_value를 사용하고, 직접 "현재 가치 - 목표 가치"를 계산하지 마십시오. - JoinQuant 내부에서
pip install을 하지 마십시오. 플랫폼은 샌드박스 처리되어 있으며 사전 설치된 라이브러리만 작동합니다.
워크플로우
일반적인 종단 간 전략 세션:
1. 사용자가 자연어로 아이디어 설명
2. AI: 일치하는 템플릿 선택 (예: 03-etf-rotation.py)
3. AI: 2~3가지 명확화 질문:
- 대상 풀 범위 (지수 구성 / 사용자 정의 목록)
- 리밸런싱 빈도 (일 / 주 / 월)
- 위험 관리 (손절 / 포지션 상한 / 섹터 중립)
4. AI: 템플릿 수정하여 전략 코드 생성
5. AI: 정신적 린트(또는 실제) 실행 — 문제 수정
6. 사용자: JoinQuant 온라인 편집기에 붙여넣고, 컴파일 및 실행
7. 오류 발생 시: 해당 references/XX-*.md 다시 로드하여 수정
8. 사용자: 백테스트 결과 검토, 반복
고위험(실시간 거래) 전략의 경우 추가로:
- 슬리피지, 수수료, 위험 지표에 대해
references/14-strategy-engine.md참조 - 레버리지 관련 시
references/11-margin-trading.md참조 - 모델 위험(과적합, 체제 변화, 거래 비용 현실성)에 대해 명시적으로 논의
파일
| 파일 | 역할 |
|---|---|
README.md | 프로젝트 소개 |
WORKFLOW.md | 전략 개발 종단 간 가이드 (✅ 완료) |
INSTALL_CN.md | 중국어 설치 가이드 (✅ 완료) |
api文档/api.txt | 원본 294KB API 문서 (원시 백업) |
references/01-14-*.md | 14개 점진적 공개 카테고리 파일 (✅ 모두 완료) |
templates/01-05-*.py | 5개의 프로덕션 템플릿 (✅ 완료) |
scripts/strategy_lint.py | 린트 도구 — 블랙/화이트리스트 혼합 (✅ 작동) |
scripts/strategy_scaffold.py | 설명에서 스캐폴드 생성 (✅ 작동) |
scripts/api_search.py | 키워드로 API 검색 (✅ 작동) |
examples/case-mean-reversion/ | 종단 간 사례: RSI 평균 회귀 (✅) |
examples/case-etf-rotation/ | 종단 간 사례: ETF 월간 로테이션 (✅) |
examples/bad-strategy-for-lint-test.py | 린트 회귀 테스트용 네거티브 테스트 샘플 (✅) |
factors/ | (v2) Barra 스타일 팩터 라이브러리, 7개 카테고리 |
factor_lab/ | (v2) 단일 팩터 IC / 그룹화 / 감쇠 분석 |
research_importer/ | (v2) 증권사 리서치 PDF → JoinQuant 코드 |
jqskill_mcp/ | (v2) 모든 스킬 기능을 노출하는 MCP 서버 |
tests/ | pytest (v2 이후 50개 이상의 테스트 통과) |
이 스킬은 2026-04-19 기준 버전 0.5.0입니다. 14개 참조 파일 + 5개 템플릿 + 3개 스크립트 + 13개 테스트 + WORKFLOW + 2개 예제가 모두 완료되었습니다.