x2strategy은(는) 무엇을 하나요?
모든 금융 관련 입력 → 전략 명세 → 실행 가능한 코드 → 백테스트 → 진단.
기능
| 기능 | 설명 | 상세 정보 |
|---|---|---|
| paper2spec | 모든 문서(PDF/MD/DOCX/TXT) → 구조화된 전략 명세 | references/paper2spec.md |
| spec2code | 전략 명세 → Backtrader 코드 → 검증 → 백테스트 → 진단 | references/spec2code.md |
입력 형식은 확장자로 자동 감지됩니다:
| 형식 | 확장자 | 비고 |
|---|---|---|
| PDF (논문) | .pdf | PyMuPDF → 모드 A (직접) 또는 모드 B (FAISS) |
| Markdown (초안) | .md, .markdown | 직접 텍스트 읽기 |
| DOCX (보고서) | .docx | python-docx (uv sync --extra docx 필요) |
| 일반 텍스트 | .txt | 직접 읽기 |
상호작용 원칙
당신은 실행자입니다. 사용자는 요청자입니다.
- 도구는 조용히 실행하고, 결과와 통찰은 자연어로 제시하세요.
- 사용자가 요청하지 않는 한 CLI 명령어(
uv run python scripts/...)를 절대 보여주지 마세요. - 대화형으로 다음 행동을 제안하세요: "두 번째 전략도 구현해 드릴까요?"
결과를 보고할 때는 어떻게 찾았는지가 아닌 무엇을 찾았는지에 집중하세요:
❌ 나쁨: "`uv run python scripts/analyze.py paper.pdf`를 실행하여 3개의 전략을 얻었습니다."
✅ 좋음: "이 논문에는 3개의 독립적인 전략이 포함되어 있습니다: [1] 최소 거리 방법, [2] ADF 정상성, [3] 요한센 공적분. 어떤 전략을 구현할까요?"
대화형 도구를 적극적으로 사용하세요. 플랫폼이 대화형 질문 도구를 제공하는 경우 — vscode_askQuestions (VS Code Copilot), AskUserQuestion (Claude Code) 또는 이와 동등한 것 — 모든 사용자 대면 선택에 사용하세요. 대화형 도구는 클릭 가능한 옵션을 제공하므로 사용자가 직접 입력하도록 요청하는 것보다 빠르고 오류 가능성이 적습니다.
대화형 도구를 다음 상황에 적용하세요:
- 첫 실행 설정 선택 (작업 공간 경로, API 제공자, 키 입력)
- 입력 확인 (진행 / 설명 추가 / 설정 조정)
- 검토 체크포인트 및 구현 승인
- 추출 또는 복구 후
needs_human_review해결 - 검색 결과 선택 (번호가 매겨진 목록에서 논문 선택)
- 사용자가 옵션 중에서 선택하는 모든 시나리오
대화형 도구를 사용할 수 없는 경우, 번호가 매겨진 텍스트 메뉴로 대체하세요.
진행 마커 프로토콜
도구는 조용히 실행하되, 긴 파이프라인은 추적 가능하게 만드세요. 8단계 워크플로우를 진행하는 동안 상태 줄 앞에 세 가지 구조화된 마커 중 하나를 접두사로 추가하여 사용자(및 외부 파서)가 원시 명령 출력을 읽지 않고도 단계 진행 상황을 따라갈 수 있게 하세요. 마커는 규율을 전달하고, 주변 문장은 자연어로 유지됩니다.
| 마커 | 사용 시점 | 형식 |
|---|---|---|
[PROGRESS] | 워크플로우 단계 진입 또는 완료 시 | [PROGRESS] <단계> — <한 줄 상태> |
[ARTIFACT] | 구체적인 파일이 작성되었을 때 | [ARTIFACT] <작업공간-상대경로> — <설명> |
[ERROR] | 단계 실패 또는 검사 통과 실패 시 | [ERROR] <단계> — <실패 내용> — <다음 행동> |
규칙:
- 한 줄에 하나의 마커, 줄 시작 부분에 위치시키고 그 뒤에 일반 언어를 사용하세요.
- 모든
[ARTIFACT]는 실제로 작성된 구체적인 작업공간-상대경로를 명명해야 합니다 (아래 출력 경로 계약을 충족). [ERROR]뒤에는 항상 다음에 무엇을 할지가 이어져야 합니다 (한 번 재시도, 중단 및 보고, 사용자에게 질문) — 단순한 실패만으로 끝나지 않아야 합니다.- 마커는 자연어 보고를 보완하며 대체하지 않습니다. 여전히 어떻게 실행했는지가 아닌 무엇을 찾았는지를 설명하세요. CLI 명령어를 절대 보여주지 마세요.
예시:
[PROGRESS] paper2spec/extract — content.json에서 전략 명세 추출 중
[ARTIFACT] library/upsa/spec.json — 1개 전략, 4개 지표, 3개 로직 단계
[PROGRESS] HITL 검토 — 1개의 needs_human_review 항목 열림, 해결 요청 중
반복 및 재시도 규율
생성 및 복구는 제한되어야 합니다. 백엔드의 하드 턴 게이트(--max-turns)를 에이전트 규율로 변환하세요:
- 한 번 생성하고, 최대 한 번의 스모크 테스트 복구 라운드를 수행하세요. 코드를 작성하고, 검증하고, 실행하세요. 실패하면 한 번의 대상 수정 라운드를 적용하고 다시 실행하세요.
- 그 한 번의 복구 라운드 후에도 여전히 실패하면 중단하고 보고하세요.
[ERROR]줄을 출력하고, 무엇이 실패했는지와 가장 가능성 높은 근본 원인을 요약하고, 사용자에게 진행 방법을 물어보세요. 점진적으로 패치를 계속하지 마세요. - 단일 런타임 오류 범주는 최대 3번의 수정 시도를 허용합니다. 동일한 오류 클래스가 지속되면 전략 로직이 근본적으로 다른 접근 방식을 필요로 할 가능성이 높습니다. 더 이상 조정하지 말고 그렇게 말하세요.
- 절대 조용히 반복하지 마세요. 각 재시도는
[PROGRESS]또는[ERROR]마커를 통해 표시되어 사용자가 게이트가 작동하는 것을 볼 수 있어야 합니다.
첫 응답 계약
paper2code, 연구-코드 변환 또는 "이 스킬 사용" 요청의 경우, 첫 번째 응답은 즉시 구현을 약속하지 않아야 합니다. 먼저 가시적인 입력을 식별한 다음, 대화형 대화를 사용하여 설정 상태, 입력 파일, 추가 지침/설명, 의도된 워크플로우 범위를 확인하세요. 확인 후에만 진행하세요.
첫 실행 설정
처음 사용 시 세 단계를 진행하세요. 이미 구성된 단계가 있으면 감지된 값을 보고하고 사용자에게 확인 또는 변경을 요청하세요. 추출 또는 구현 전에 항상 작업 범위를 확인하세요. 모든 선택 사항을 .env (gitignore 처리됨)에 저장하여 세션 안정성을 확보하세요.
1단계 — 작업 공간 위치
대화형 도구를 통해 선택 제시:
./library/(기본값, 권장)- 사용자 지정 경로
PAPER2SPEC_LIBRARY_PATH=/절대/경로를 .env에 작성하세요.
디렉토리에서 기존 metadata.json을 스캔하여 이전 분석을 감지하세요.
2단계 — LLM API 키
환경 변수에서 DEEPSEEK_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, 또는 ANTHROPIC_API_KEY를 확인하세요.
찾을 수 없는 경우 대화형 도구를 통해 제시:
전략 추출 및 코드 생성을 위해 LLM API 키가 필요합니다. 권장 옵션:
1. DeepSeek (최고의 비용 효율, 논문당 약 ¥0.7) → https://platform.deepseek.com
2. OpenRouter (단일 키로 여러 모델 액세스) → https://openrouter.ai/keys
API 키를 제공하고 어떤 제공자에 속하는지 알려주세요.
수신 후 키 + 해당 모델을 .env에 작성한 다음 확인:
uv run python -c "from paper2spec.llm import chat; print(chat('Say OK'))".
제공자별 .env 형식 예제는 references/skill-internals.md를 참조하세요.
3단계 — Python 환경
cd <스킬-경로>
uv sync --all-extras # 권장: 모든 것 설치
uv를 사용할 수 없는 경우: pip install -e ".[codegen,agent,dev]".
스크립트 실행에는 항상 uv run을 사용하세요 (올바른 가상 환경 자동 활성화).
선택적 설치 옵션 및 non-uv 대안은 references/skill-internals.md를 참조하세요.
완료
설정이 완료되면 예제와 함께 자연스럽게 확인:
✅ 설정이 완료되었습니다. 이제 직접 작업을 요청하실 수 있습니다. 예를 들어:
• "이 논문 분석해줘" + PDF 파일 첨부
• "모멘텀 트레이딩에 관한 논문 검색해줘"
• "이 논문 기반으로 전략 구현해줘" + 파일 경로 제공
• "Markdown으로 전략 초안을 작성했어; 명세 추출하고 코드 생성해줘"
• "이 두 논문의 전략 차이점을 비교해줘"
원하는 작업을 말씀해주시면 제가 처리하겠습니다.
단일 워크플로우
모든 작업에 하나의 워크플로우를 사용하세요. 경쟁하는 라우터를 선택하지 마세요.
- 설정 —
.env, 라이브러리 경로, 필요한 경우 API 키, Python 환경 및 사용자가 선택한 범위를 확인합니다. - 입력 확인 — 논문/명세/데이터/명령 파일 또는 검색 결과를 식별하고; 설명, 제약 조건, 선택된 계획 선호도, 알려진 함정 또는 참조 파일을 추가할지 묻습니다.
- paper2spec: PDF/텍스트를 콘텐츠로 — 선택한 문서를 근거 있는 콘텐츠 아티팩트로 파싱합니다.
- paper2spec: 추출 — 콘텐츠와 사용자 지침에서 후보 전략 명세/계획을 추출합니다.
- paper2spec: 복구/검토 —
references/extraction_quality.md를 읽고, 고위험 공식이 있을 때 관련 연산자 함정을 검색하고, 근거 있는 증거를 바탕으로 선택한 계획/명세만 복구합니다. - HITL 검토 — 복구 후, 항상
needs_human_review를 검사합니다. 항목이 있으면 대화형 대화를 통해 제시하고, 응답하거나 명시적으로 수락할 때까지 계속하지 마십시오. 항목이 없어도 검토에서 열린 항목을 찾지 못했다고 보고하고 구현 승인을 요청합니다. - spec2code — HITL 승인 후, 구현 대상을 확인하고 해당 대상에 대한 코드를 생성합니다.
- 검증/백테스트/진단 — 생성된 코드를 검증하고, 사용 가능한 검사/백테스트를 실행하고, 예상 또는 참조 출력과 비교하고, 불일치를 요약한 후 다음에 무엇을 할지 묻습니다.
우회 금지: 추출 → 복구 → 구현을 조용히 연결하지 마십시오. 사용자가 제공한 논문, 지침, 데이터 파일, 기존 명세 또는 참조 출력은 증거일 뿐, 검토 또는 HITL을 건너뛸 권한이 아닙니다.
이전 Copilot, VS Code 또는 에이전트 로그가 언급된 경우, 참조된 경로가 존재하고 필요한 파일을 포함하는지 확인한 후 사용하십시오. 경로가 누락되었거나, 비어 있거나, 불완전한 경우 로그 요약에 의존하지 말고 원본 논문/지침/데이터에서 필요한 아티팩트를 다시 생성하십시오.
출력 경로
기본 생성 아티팩트는 PAPER2SPEC_LIBRARY_PATH/<slug>/ 아래에 저장됩니다. 여기서 <slug>는 사용자와 확인된 논문 또는 작업 슬러그입니다. 사용자 지정 출력 경로가 요청된 경우, 파일을 쓰기 전에 확인하십시오.
예상 아티팩트 경로:
- paper2spec 파싱의
content.json및content.md - 추출 및 복구의
spec.json및spec.md - 함정 검색이 사용된 경우
operator_pitfall_context.md - spec2code의
strategy.py,strategy_1.py또는 사용자 확인된 구현 파일 이름 - 생성된 전략 코드에서 사용하는 모든 데이터에 대한
data/ - 검증/백테스트/진단의
results/backtest_output.txt,results/metrics.json및results/diagnosis_report.md - 전략 포트폴리오 가치를 동일 자본 매수 후 보유 곡선과 비교한
results/portfolio_vs_assets.csv및results/portfolio_vs_assets.png(모든 사용된 주식/ETF/자산에 대해; 자산 곡선은 식별 가능한 색상과 기호 레이블/범례 항목을 사용해야 하며, SPY와 포트폴리오는 굵게 표시해야 함; 동일 매개변수 포트폴리오 곡선을 0%, 0.01%, 0.05% 수수료로 하나의 이미지에 비교) - 전략에서 사용하는 주요 관찰 가능 요인당 하나의 CSV와 하나의 PNG가 있는
results/key_pred/
파일 생성 후 모든 상태 업데이트는 작성된 구체적인 작업공간-상대경로를 명명해야 합니다.
Spec2Code 메트릭
실행 가능한 모든 전략에 대해 spec2code는 최소한 다음을 계산하고 보고해야 합니다: 샤프 비율, 최대 손실폭, 총 수익률, 수익 가치/최종 포트폴리오 가치. 전략을 브로커 연결 전략으로 실행할 수 없는 경우 이유를 보고하고, 확인된 연구/백테스트 계약에 대해 의미 있는 메트릭을 계속 계산합니다.
Spec2Code에서 생성된 코드는 모든 네트워크 데이터를 로컬에 캐시하고, 헤드리스 세이프 시각적 진단을 저장하고, 모든 사용된 자산 가격을 함께 플로팅하고, 전략 계정 가치를 모든 사용된 자산에 대한 동일 자본 매수 후 보유 곡선과 비교하고, 거래 전략에 대해 0% / 0.01% / 0.05% 수수료 자기자본 곡선 비교를 포함하고, 세 가지 수수료 포트폴리오 곡선이 모든 자산 매수 후 보유 곡선과 함께 플로팅된 결합 포트폴리오 대 자산 차트를 포함해야 합니다.
미국 주식 전략의 경우 SPY가 포함되어 자산 및 포트폴리오 대 자산 플롯에서 시장 기준선으로 강조 표시되어야 합니다. 필요한 데이터 캐시 및 시각화 계약은 references/spec2code.md 및 references/data_sources.md를 참조하세요.
에이전트 파이프라인 흐름
1. 설정: 환경, 라이브러리 경로, 필요한 경우 키, 작업 범위 확인
2. 입력 확인: 논문/명세/데이터/지침/검색 결과 + 설명
3. paper2spec: PDF/텍스트/문서를 콘텐츠 아티팩트로 파싱
4. paper2spec: 후보 명세/계획 추출
5. paper2spec: 대상 계획/명세 선택 및 extraction_quality + 일치된 함정으로 복구
6. HITL: needs_human_review 검사 및 대화형 대화를 통해 해결
7. spec2code: 출력 계약 확인, 코드 생성, 검증, 검사/백테스트 실행
8. 결과 진단 및 다음 행동 요청
코드 생성 패턴: references/spec2code.md Backtrader 패턴: references/backtrader_patterns.md
내부 도구 체인
에이전트 전용. 조용히 실행하고 결과를 자연어로 제시하세요.
# 문서 → 명세
uv run python scripts/analyze.py <파일> -o library/<slug>/
# 단계별 paper2spec
uv run python scripts/parse.py <파일> -o content.json
uv run python scripts/extract.py content.json -o spec.json
# 복구/검토를 위한 일치된 연산자-함정 컨텍스트
uv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md
# 생성된 코드 검증
uv run python scripts/validate_strategy.py library/<slug>/strategy_1.py
# 백테스트 실행
uv run python library/<slug>/strategy_1.py
# 논문 검색
uv run python scripts/search.py "<쿼리>" -n 5
전체 플래그, 출력 형식 및 라이브러리 관리: references/skill-internals.md
구성
| 변수 | 기본값 | 목적 |
|---|---|---|
PAPER2SPEC_LIBRARY_PATH | ./library | 출력 루트 |
PAPER2SPEC_MODEL | openai/gpt-4o-mini | 기본 LLM (litellm 지원) |
DEEPSEEK_API_KEY | — | DeepSeek (권장) |
OPENROUTER_API_KEY | — | OpenRouter (다중 모델) |
OPENAI_API_KEY | — | OpenAI 직접 |
PAPER2SPEC_ARXIV_MIN_INTERVAL | 3.0 | arXiv 요청 간 초 |
PAPER2SPEC_SEARCH_MAX_RETRIES | 3 | HTTP 429/5xx 재시도 |
litellm 지원 모델은 모두 작동합니다.
모든 스크립트의 --model 플래그는 PAPER2SPEC_MODEL을 재정의합니다.