<p align="center">
<img src="https://raw.githubusercontent.com/gaaiyun/joinquant-skill/HEAD/assets/joinquant-skill-logo.svg" width="180" alt="JoinQuant Skill 프로젝트 로고">
</p>
<h1 align="center">聚宽 전략 도우미 · JoinQuant Skill</h1>
<p align="center">코딩 에이전트(Coding Agent)가 JoinQuant API를 먼저 확인하고 전략을 작성하도록 돕습니다.</p>
<p align="center">
<a href="https://github.com/gaaiyun/joinquant-skill/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/gaaiyun/joinquant-skill/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://www.python.orgعات"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
<a href="references/"><img alt="14 API 참고 자료" src="https://img.shields.io/badge/references-14-0a7f73"></a>
<a href="templates/"><img alt="5 전략 템플릿" src="https://img.shields.io/badge/templates-5-0969da"></a>
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-2ea44f.svg"></a>
<a href="https://github.com/gaaiyun/joinquant-skill/stargazers"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/gaaiyun/joinquant-skill?style=flat&logo=github"></a>
</p>
<p align="center">
<a href="#quick-start">빠른 시작</a> ·
<a href="#能力说明">기능 설명</a> ·
<a href="#验证与使用边界">검증 및 사용 경계</a> ·
<a href="#相关项目">관련 프로젝트</a>
</p>
코딩 에이전트(Coding Agent)가 사용할 수 있는 JoinQuant API 지식 기반, 전략 골격 및 코드 검사 도구입니다.
Cursor, Claude Code, Codex와 같은 코딩 에이전트(coding agent)는 Python에 익숙하지만 JoinQuant의 실행 환경과 API 제약 사항을 반드시 이해하는 것은 아닙니다. 이들은 함수를 조작하거나(编造), 연구 인터페이스와 백테스팅 인터페이스를 혼용하고, 복권화(复权) 및 거래 비용을 무시하여 문법적으로는 정확하지만 JoinQuant에서 실행할 수 없는 전략을 제시할 수 있습니다.
본 저장소는 JoinQuant API 자료, 전략 골격, 정적 검사(static check), 요인 예시, 리서치 보고서 분석 프로세스 및 MCP 도구를 하나의 스킬에 담았습니다. 에이전트는 작업별로 필요한 자료를 로드할 수 있으며, 사용자도 내부의 CLI를 직접 사용할 수 있습니다.
[!IMPORTANT]
본 저장소는 코드 구조와 일부 JoinQuant 사용법만 검사할 수 있으며, 전략 수익성을 검증하거나 JoinQuant 클라우드의 컴파일, 백테스팅 및 모의 거래를 대체할 수 없습니다. lint는 단순히 코드가 현재 규칙에 해당하지 않음을 설명할 뿐이므로, 데이터 시점, 거래 비용, 위험 제약 및 체결 조건을 여전히 확인해야 합니다.
목차
Quick Start
1. 저장소 클론하기
요청하신 청크를 이어서 번역합니다.
git clone https://github.com/gaaiyun/joinquant-skill.git
cd joinquant-skill
python --version # Python 3.10 이상 필요
아래의 API 검색, 전략 생성 및 lint 명령어는 외부 종속성이 필요하지 않습니다. 테스트, factors, factor_lab, PDF 파싱 및 MCP에 대한 종속성은 선택적 종속성을 참조하세요.
2. 전략 골격 생성
python scripts/strategy_scaffold.py --list
python scripts/strategy_scaffold.py `
--type rotation `
...
3. 전략 검사
python scripts/strategy_lint.py my_strategy.py --strict
오류(error)와 경고(warning)를 수정한 후, 코드를 JoinQuant 웹 에디터에 붙여넣어 플랫폼 컴파일 및 백테스팅을 계속 진행하세요.
4. Agent가 이 Skill을 사용하도록 하기
등록이 완료되면, 요구사항을 직접 Agent에게 전달합니다:
joinquant-skill을 사용하여 ETF 로테이션 전략 작성:
종목 풀은 510300.XSHG, 510500.XSHG, 159915.XSHE이며,
20일 모멘텀으로 정렬하고, 매주 월요일 09:31에 포트폴리오를 조정하며, 최대 2개 종목만 보유합니다.
Agent는 작업을 기반으로 해당 템플릿과 참조(reference)를 읽고, API를 검증한 후에 코드를 생성합니다.
flowchart LR
A["전략 요구사항, 기존 코드 또는 리서치 보고서 JSON"] --> B{"JoinQuant Skill"}
B --> C["references: API 검색"]
...
자세한 설치 단계는 INSTALL_CN.md를 참고하시고, 전체 개발 프로세스는 WORKFLOW.md를 참고하세요.
이것이 해결하는 문제점
API 환각(API Hallucination)
jqdata.get_stock_data()나 pandas.DataFrame.diff_in_diff()와 같은 함수는 존재하지 않습니다. 이 저장소는 주제별로 분리된 참조 자료, 원본 API 데이터 검색 및 lint 규칙을 제공하여 Agent가 코드를 생성하기 전에 먼저 검증할 수 있도록 합니다.
실행 환경 혼용(Mixed Execution Environments)
동일한 함수라도 리서치 환경, 백테스팅 환경, 로컬 jqdatasdk에서 매개변수와 반환 구조가 다를 수 있습니다. 각 참조 자료는 특정 사용 시나리오를 중심으로 구성되어 있어, 로컬 연구 코드를 JoinQuant 전략에 통째로 붙여넣는 것을 방지합니다.
백테스팅 세부 사항 누락(Backtest Detail Omissions)
수정 방식(复权方式), 데이터 마감 시점, 스케줄링 시간, 수수료 및 슬리피지는 모두 결과에 영향을 미칩니다. 템플릿은 검토 가능한 시작점을 제공하며, lint는 일부 고빈도 문제를 알려줍니다. 이들은 미래 데이터가 존재하지 않음을 증명할 수 없으며, 전략이 과적합(overfitted)되었는지 여부를 판단할 수도 없습니다.
장문 문서의 컨텍스트화 어려움(Difficulty Contextualizing Long Documents)
저장소는 약 294 KB 분량의 원본 API 자료를 보관하며, 이를 14가지 유형의 참조로 분리했습니다. Agent는 현재 작업에 관련된 부분만 로드하므로, 전체 문서를 프롬프트에 넣을 필요가 없습니다.
기능 설명
| 모듈 | 용도 | 실행 위치 | 검증 경계 |
|---|
references/ | 14가지 JoinQuant API 및 운영 메커니즘 설명 | Agent 컨텍스트 / 로컬 읽기 | 자료는 JoinQuant 업데이트에 따라 구식이 될 수 있으므로, 핵심 인터페이스는 공식 문서를 재확인해야 합니다 |
| ... | | | |
참조(Reference) 라우팅
어떤 문서를 읽어야 할지 모른다면, 먼저 함수 이름으로 검색하세요:
python scripts/api_search.py get_price
python scripts/api_search.py --context 10 fq
python scripts/api_search.py --regex "set_\w+"
자주 사용되는 워크플로우
JoinQuant 전략 생성 또는 수정
- 종목 풀, 신호, 포트폴리오 조정 빈도 및 포지션 제약 조건을 명확히 정의합니다.
- 가장 유사한 템플릿부터 시작하고, 초기화 및 스케줄링 코드를 빈 파일에서 다시 작성하지 않습니다.
- 관련 참조 자료를 사용하여 각 JoinQuant API를 검증합니다.
strategy_lint.py --strict을 실행합니다.- JoinQuant 에디터에서 컴파일한 후, 백테스팅 및 결과 확인을 진행합니다.
JoinQuant 전략 도우미 · JoinQuant Skill
기존 코드 검토
python scripts/strategy_lint.py path\to\strategy.py --strict
python scripts/strategy_lint.py path\to\strategy.py --json
수동 점검이 필요한 핵심 사항:
- 데이터가 신호 발생 시점에 이미 발표되었는지;
end_date, count 및 현재 백테스트 시간이 일치하는지;- 주식, ETF, 선물에 해당 수수료와 슬리피지(slippage)가 사용되었는지;
- 거래 정지, 상하한가, 퇴출 종목 및 공백 주식 풀 처리는 어떻게 했는지;
- 포트폴리오 재조정 목표에 비용과 체결 실패 여유분이 남았는지.
리서치 보고서에서 전략 후보 생성
파이프라인은 텍스트 정리, 프롬프트 구성, 구조화된 JSON 읽기 및 코드 생성을 담당합니다. LLM 호출은 사용자가 직접 수행해야 합니다.
# 1. PDF → 텍스트
python -m research_importer extract report.pdf -o out/01_extracted_text.txt
...
LLM 대기 단계까지 미리 실행할 수도 있습니다:
python -m research_importer pipeline report.pdf -o out/
codegen은 기본적으로 JoinQuant 네이티브 팩터(native factor)로 매핑되었거나 저장소 내에 이미 수동으로 구현된 팩터만 받습니다. 알 수 없는 비네이티브 팩터는 전체가 0인 순위 생성을 방지하기 위해 직접 실패합니다. 구조적 골격만 필요하다면 --allow-placeholders를 명시적으로 추가할 수 있습니다. 생성된 NaN/TODO 플레이스홀더는 백테스트에 바로 사용할 수 없습니다.
스키마(schema) 내의 보조 팩터, 위험 제약 조건, 수수료, 슬리피지 및 신뢰도는 반드시 실행 가능한 로직으로 변환된 것은 아닐 수 있습니다. 결과를 재현하기 전에 리서치 보고서 원문과 항목별로 대조해야 합니다. 저작권 경계는 research_importer/disclaimer.md를 참조하십시오.
전체 예시는 examples/case-research-replication/에서 확인할 수 있습니다.
로컬 팩터 연구
factor_lab은 jqdatasdk와 함께 사용하며, 전체를 JoinQuant 에디터에 복사해서는 안 됩니다.
from jqdatasdk import auth, get_index_stocks
from factors import get as get_factor
from factor_lab import compute_ic, grouping_backtest
...
팩터 매핑, 전처리 권장 사항 및 이식 경계는 factors/USAGE.md를 참조하십시오.
설치
로컬 도구로 사용하기
git clone https://github.com/gaaiyun/joinquant-skill.git
cd joinquant-skill
python scripts/strategy_scaffold.py --list
Cursor, Claude Code 또는 Codex에 등록하기
Windows 사용자는 여러 클라이언트가 동일한 저장소를 참조하도록 하여 복사 후 버전 드리프트(version drift)를 방지할 수 있습니다:
cd D:\projects\joinquant-skill
$repoPath = (Get-Location).Path
...
클라이언트가 다른 skill 루트 디렉토리를 사용하는 경우, 동일한 저장소를 해당 디렉토리에 링크하면 됩니다. 링크를 생성한 후에는 SKILL.md, references/, scripts/ 및 templates/ 모두 설치 위치에서 접근 가능한지 확인해야 합니다. 루트 디렉토리 파일만 복사할 경우 skill이 작동하지 않을 수 있습니다.
macOS, Linux 및 기타 설치 방법은 INSTALL_CN.md를 참조하십시오.
선택적 의존성
# 테스트, factors 및 factor_lab용
pip install -r requirements-dev.txt
...
JoinQuant 전략 코드 내에서 pip install을 실행하지 마십시오. 이 의존성들은 로컬 도구 환경에만 설치됩니다.
MCP 서버
MCP SDK를 설치한 후 stdio 서버 시작:
pip install "mcp[cli]"
python -m jqskill_mcp.server
Claude 데스크톱 설정 예시:
{
"mcpServers": {
"joinquant-skill": {
...
cwd는 전체 레포지토리를 가리켜야 합니다. 클라이언트가 python을 찾지 못하면, 먼저 python -c "import sys; print(sys.executable)"를 실행한 후 출력된 절대 경로를 command에 채워 넣으세요. 서비스는 API 검색, 팩터 조회, 전략 linter(lint), 골격 생성, 리서치 보고서 프롬프트 등 jq_* 도구를 노출합니다. 서명 및 입력 모델은 jqskill_mcp/server.py를 참조하세요.
검증 및 사용 범위
로컬 테스트
python -m pytest tests -q
기본 테스트는 외부 네트워크에 접근하지 않으며, JoinQuant 계정이 필요하지 않습니다. CI 환경에서는 Python 3.10, 3.11, 3.12 및 3.13에서 pytest를 실행하며, 레포지토리 자체의 linter로 templates와 examples를 검사합니다.
선택적 온라인 테스트
AkShare 및 jqdatasdk 테스트는 기본적으로 건너뛰어지며, 명시적으로 활성화해야 합니다:
$env:JQSKILL_ENABLE_AKSHARE_LIVE = "1"
python -m pytest tests\test_optional_live_integrations.py -q
...
두 번째 항목은 먼저 jqdatasdk를 설치하고 권한을 부여해야 합니다. 온라인 테스트는 외부 인터페이스와 일부 팩터 ID만 검사하며, 전략 수익률은 검사하지 않습니다.
증거 계층화
| 레벨 | 입증 가능한 것 | 입증 불가능한 것 |
|---|
| pytest | 레포지토리 함수, CLI 및 mock runtime이 테스트 정의를 준수함 | JoinQuant 클라우드의 현재 동작, 실제 네트워크 및 계정 상태 |
| ... | | |
일반적인 함정
| 함정 | 영향 | 확인 방법 |
|---|
use_real_price를 완전한 미래 데이터 방어 수단으로 간주하는 것 | 여전히 신호 시점에서 아직 발생하지 않은 데이터를 읽을 수 있음 | 각 필드를 context.current_dt로 재검토하고, avoid_future_data 설정을 평가하세요 |
| ... | | |
프로젝트 구조
joinquant-skill/
├── README.md 프로젝트 진입점 및 기술 매뉴얼
├── SKILL.md Agent skill 라우팅 설명
...
핵심 규칙
JoinQuant의 기존 기능 우선 사용
본 레포지토리는 백테스팅 엔진을 구현하지 않으며, jqdatasdk를 재작성하지 않습니다. JoinQuant에 네이티브 팩터가 존재하는 경우, factors/는 jqfactor.get_factor_values를 우선 호출합니다. 해당 팩터가 없는 경우에만 시세 또는 재무 필드를 이용해 수동으로 계산하는 것을 고려해야 합니다.
출처와 환경 함께 기록
API 서명, 데이터 필드 및 팩터 ID는 모두 변경될 수 있습니다. 새로운 레퍼런스나 예시를 추가할 때는 자료의 출처, 적용 가능한 환경, 검증 날짜를 명확히 기재해야 합니다. 연구 환경에서 사용 가능하다고 해서 백테스팅 환경에서도 사용 가능하다는 의미는 아닙니다.
코드 생성은 초안 작성만 담당
템플릿과 코드 생성(codegen) 기능은 반복적인 구조와 일반적인 오류를 해결합니다. 전략 정의, 위험 제약 조건, 데이터 가용성 및 백테스팅 설계는 여전히 사용자에게 책임이 있습니다.
유료 리서치 보고서 본문 수록하지 않음
레포지토리는 사용자가 소유한 PDF 또는 공개 요약만 처리하며, 증권사의 유료 리서치 보고서는 저장하지 않습니다. 연구 결론을 인용할 때는 출처를 명시하고 원문의 권한 범위를 준수해야 합니다.
관련 프로젝트
| 프로젝트 | 적합한 작업 | 본 레포지토리와의 관계 |
|---|
JoinQuant/jqdatasdk | 로컬에서 JoinQuant 데이터 가져오기 | 선택적 데이터 의존성으로 사용하며, 전체 SDK를 중복 캡슐화하지 않음 |
| ... | | |
Star History
차트는 매주 GitHub Actions가 레포지토리 자체 토큰을 사용하여 업데이트하며, SVG는 본 레포지토리에 저장되어 제3자 이미지 서비스에 의존하지 않습니다.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg">
<img alt="gaaiyun/joinquant-skill GitHub Star History" src="https://raw.githubusercontent.com/gaaiyun/joinquant-skill/HEAD/assets/star-history-light.svg">
</picture>
이 프로젝트가 JoinQuant 코드 문제를 해결했다면 Star를 눌러주세요. API 오류, 만료된 자료 또는 플랫폼 호환성 문제가 발생하면 재현 가능한 issue를 제출해 주세요.
문서
라이선스
MIT, LICENSE 참조.
크레딧