jongjae0305
18 KiB
18 KiB
단타 자동매매 시스템 종합 기획서 v3.0
버전: v3.0 (최종 확정) 최종 수정: 2026-05-14 인프라: Synology NAS (Container Manager) 언어: Python 3.11 API: KIS Open API (한국투자증권) 알림: Discord Webhook AI: Claude Code headless (Docker 컨테이너, 자동 스케줄)
0. 핵심 설계 원칙 (절대 불변)
- 감정 0 — 진입/청산은 코드가 결정, AI는 보조
- 손절 우선 — AI 긍정 판단과 무관하게 손절 룰 항상 우선
- 14:50 강제 청산 — 하드코딩, 어떤 상황에서도 예외 없음
- 검증 순서 필수 — 모의투자 3개월 → 실전 전환 조건 충족 → 실거래
- AI 역할 분리 — Claude Code: 장 전 분석 + 장 후 개선 (동일 방식, 시간만 다름)
1. 확정 사항 요약
| 항목 | 확정값 | 비고 |
|---|---|---|
| 증권사 | KIS 한국투자증권 | REST + WebSocket, 모의투자 지원 |
| 인프라 | Synology NAS Docker | Container Manager, 24시간 운영 |
| 언어 | Python 3.11 | KIS 예제 모두 Python |
| DB | SQLite | 단일 파일, 백업 단순 |
| 캐시 | Redis (Docker) | 실시간 시세 캐시 |
| 알림 | Discord Webhook | 단방향, aiohttp POST 5줄 |
| 감시 종목 | 최대 30개 | KIS WebSocket 안정성 기준 |
| 전략 | 변동성 돌파 (K=0.5) | 단순·검증됨 |
| AI 엔진 | Claude Code headless | Docker 컨테이너로 NAS에서 자동 실행 |
| 월 운영비 | Claude Code 구독 요금만 | API 키 별도 불필요 |
| 코드 관리 | Gitea (NAS) | 자동 커밋/리포트 저장 |
2. 하루 전체 흐름
08:30 ┌─────────────────────────────────────────────────┐
│ [컨테이너 1] Claude Code - 장 전 분석 │
│ │
│ claude -p " │
│ 오늘 날짜 기준 뉴스, 수급, 지수 데이터 수집 │
│ 오늘 단타 전략 판단 (섹터/종목/리스크) │
│ → daily_context.json 저장 │
│ " │
│ │
│ Discord 전송: │
│ "[AI분석] 시장:중립 / 반도체 주목 / 금융 회피" │
└─────────────────────────────────────────────────┘
↓ daily_context.json 생성
08:50 유니버스 30종목 확정 + 목표가 계산
↓
09:00 ┌─────────────────────────────────────────────────┐
│ [컨테이너 2] 매매 프로그램 시작 │
│ │
│ KIS WebSocket → 실시간 시세 수신 │
│ 변동성 돌파 신호 발생 │
│ → AI 필터 (daily_context.json 참조) │
│ → 조건 충족 시 매수 실행 │
│ │
│ 청산 우선순위: │
│ 1순위: 14:50 강제 청산 (절대 불변) │
│ 2순위: 손절 -1.5% │
│ 3순위: 1차 익절 +2% (50% 매도) │
│ 4순위: 2차 익절 +3% (전량) │
│ 5순위: 120분 경과 시 청산 │
│ │
│ Discord 실시간 전송: │
│ [매수] [손절] [익절1] [익절2] [경고] │
└─────────────────────────────────────────────────┘
↓
14:50 강제 전량 청산
↓
15:10 ┌─────────────────────────────────────────────────┐
│ [결산] 오늘 결과 저장 │
│ │
│ SQLite → 매매내역 / 손익 / 승률 저장 │
│ │
│ Discord 전송: │
│ "[결산] 매매5회 / 승3패2 / 순손익 +1.2%" │
└─────────────────────────────────────────────────┘
↓
15:30 ┌─────────────────────────────────────────────────┐
│ [컨테이너 3] Claude Code - 장 후 피드백 │
│ │
│ claude -p " │
│ 오늘 매매 결과 분석 │
│ 이상 패턴 감지 (연속손절/비정상수익 등) │
│ 문제 있으면 app/config.py 수정 │
│ reports/daily/날짜.md 저장 │
│ 실전 전환 조건 체크 │
│ " │
│ │
│ Discord 전송: │
│ "[분석] 오늘 평가 + 수정사항 요약" │
│ (실전 조건 충족 시) "[🚀실전전환권고]" │
└─────────────────────────────────────────────────┘
↓
Gitea 수정된 코드 + 리포트 자동 커밋
3. 시스템 구성도
Synology NAS (Container Manager)
│
├── [컨테이너] stockbot-main ← 매매 프로그램 (09:00~15:00 상시)
├── [컨테이너] stockbot-redis ← 실시간 시세 캐시
├── [컨테이너] stockbot-dashboard ← Streamlit 모니터링 (포트 8501)
├── [컨테이너] claude-morning ← 08:30 장 전 분석 (실행 후 종료)
├── [컨테이너] claude-evening ← 15:30 장 후 피드백 (실행 후 종료)
└── [컨테이너] stockbot-killswitch ← 긴급 청산 (수동 트리거)
외부 연결
├── KIS WebSocket ← 실시간 체결/호가/VI
├── KIS REST API ← 주문/잔고/수급/순위
├── 네이버 금융 ← 뉴스 크롤링
├── Discord Webhook ← 단방향 알림
└── Gitea (NAS) ← 코드 관리 / 리포트 저장
4. 폴더 구조
/volume1/docker/stockbot/
│
├── .env ← API 키 (Git 절대 제외)
├── .env.example ← 키 입력 가이드
├── docker-compose.yml
├── README.md
├── test_connection.py ← KIS 연결 테스트
│
├── app/ ← 매매 프로그램
│ ├── main.py ← asyncio 메인 루프
│ ├── config.py ← 전략 파라미터
│ ├── Dockerfile
│ ├── requirements.txt
│ │
│ ├── ai/ ← Claude Code가 읽고 쓰는 영역
│ │ └── daily_context.json ← 장 전 분석 결과 (매일 갱신)
│ │
│ ├── data/
│ │ ├── universe.py ← 종목 풀 (30개)
│ │ └── collector.py ← WebSocket 시세 수신
│ │
│ ├── strategy/
│ │ ├── base.py
│ │ └── volatility_breakout.py ← 변동성 돌파 + AI 필터
│ │
│ ├── risk/
│ │ └── manager.py ← L1~L5 손실 한도
│ │
│ ├── execution/
│ │ ├── kis_client.py ← KIS REST/WebSocket 래퍼
│ │ └── order_executor.py ← 주문 전송
│ │
│ ├── monitor/
│ │ ├── notifier.py ← Discord Webhook
│ │ └── dashboard.py ← Streamlit
│ │
│ └── db/
│ ├── models.py ← SQLite 스키마
│ └── repository.py ← DB 접근
│
├── claude_morning/ ← 장 전 분석 컨테이너
│ ├── Dockerfile
│ └── run.sh ← claude -p "..." 실행 스크립트
│
├── claude_evening/ ← 장 후 피드백 컨테이너
│ ├── Dockerfile
│ └── run.sh
│
├── kill_switch/
│ └── kill.py ← 긴급 전량 청산
│
├── reports/
│ ├── daily/ ← 매일 자동 생성 (날짜.md)
│ ├── weekly/ ← 매주 자동 생성
│ └── live_ready/ ← 실전 전환 조건 충족 시 생성
│
├── data/
│ ├── stockbot.db ← SQLite
│ └── universe_cache.json
│
└── logs/
├── trades.log ← 영구 보관 (세금 신고용)
└── claude.log ← AI 판단 이력
5. 전략 파라미터 (config.py)
# 변동성 돌파
STRATEGY_K = 0.5 # 변동성 계수
ENTRY_START = "09:00"
ENTRY_END = "14:30"
FORCE_EXIT = "14:50" # 절대 변경 불가
TP1_PCT = 0.02 # 1차 익절 +2% → 50% 매도
TP2_PCT = 0.03 # 2차 익절 +3% → 전량
SL_PCT = 0.015 # 손절 -1.5%
MAX_HOLD_MIN = 120 # 최대 보유 120분
# 리스크
POS_SIZE_PCT = 0.20 # 1종목 최대 20%
MAX_POSITIONS = 2 # 동시 최대 2종목
DAILY_SL_PCT = 0.03 # 일일 손실 한도 -3%
CONSEC_LOSS = 3 # 연속 손절 횟수 한도
# AI 필터
AI_CONTEXT_PATH = "data/daily_context.json"
AI_MIN_SCORE = 40 # 감성점수 40 미만 → 거래 중단
6. 리스크 관리 (L1~L5)
| 레벨 | 조건 | 동작 | Discord |
|---|---|---|---|
| L1 | 1회 -1.5% | 즉시 손절 | [손절] |
| L2 | 일일 -3% | 당일 신규 진입 중단 | [경고] |
| L3 | 3연속 손절 | 당일 매매 중단 | [경고] |
| L4 | 주간 -7% | 주말까지 중단 | [경고] |
| L5 | 월간 -15% | 전략 폐기 + Claude Code 재검토 | [긴급] |
7. Claude Code 컨테이너 구성
장 전 분석 (08:30)
# claude_morning/Dockerfile
FROM node:20-slim
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /app
COPY run.sh .
CMD ["bash", "run.sh"]
# claude_morning/run.sh
claude --bare -p "
오늘($(date '+%Y-%m-%d')) 장 시작 전 분석을 수행해.
1. data/news/ 폴더에서 오늘 수집된 뉴스 파일 읽기
2. data/market/ 폴더에서 수급/지수 데이터 읽기
분석 항목:
- 시장 분위기 (강세/중립/약세)
- 감성 점수 (0~100)
- 리스크 레벨 (낮음/보통/높음)
- 주목할 섹터
- 회피할 섹터
- 추천 종목 (boosted)
- 제외 종목 (blacklist)
- 포지션 사이즈 배율 (0.5~1.5)
결과를 data/daily_context.json 으로 저장.
Discord Webhook으로 분석 요약 전송.
FORCE_EXIT=14:50 은 절대 수정 불가.
" \
--allowedTools "Read,Write,Bash" \
--dangerously-skip-permissions \
--max-turns 10
장 후 피드백 (15:30)
# claude_evening/run.sh
TODAY=$(date '+%Y-%m-%d')
claude --bare -p "
오늘($TODAY) 매매 결과를 분석하고 개선해.
1. data/stockbot.db 에서 오늘 매매 내역 조회 (sqlite3)
2. logs/trades.log 에서 오늘 로그 확인
3. reports/daily/ 의 최근 30일 리포트 참조
분석 항목:
- 오늘 승률/손익/이상패턴
- 연속 손절 여부
- 파라미터 조정 필요 여부
코드 수정:
- 문제 명확할 때만 app/config.py 수정
- FORCE_EXIT=14:50 절대 변경 불가
실전 전환 조건 체크 (모두 충족 시 live_ready 파일 생성):
- 30거래일 이상 운영
- 최근 30일 승률 > 48%
- 최근 30일 MDD < -10%
- 최근 30일 샤프지수 > 1.0
- L3 발동 월 2회 이하
결과를 reports/daily/${TODAY}.md 저장.
Discord로 요약 전송.
실전 조건 충족 시 '[🚀실전전환권고]' 메시지 전송.
" \
--allowedTools "Read,Write,Bash" \
--dangerously-skip-permissions \
--max-turns 20
8. Discord 알림 목록
| 시각 | 이벤트 | 메시지 형식 |
|---|---|---|
| 08:30 | AI 분석 완료 | [AI분석] 시장:중립(62점) / 주목:반도체 / 회피:금융 |
| 09:00~ | 매수 | [매수] 삼성전자 74,000원 / 목표 75,480 / 손절 72,890 |
| 09:00~ | 매수 (AI추천) | [매수★] 하이닉스 185,000원 / AI 추천 종목 |
| 09:00~ | 1차 익절 | [익절1] 삼성전자 +2.1% / 잔여 50% |
| 09:00~ | 2차 익절 | [익절2] 삼성전자 +3.0% / 전량 청산 |
| 09:00~ | 손절 | [손절] 삼성전자 -1.5% / 즉시 청산 |
| 14:50 | 강제 청산 | [14:50 강제청산] 전 포지션 청산 완료 |
| 15:00~ | L2~L4 발동 | [경고-L2] 일일 손실 -3% 도달. 오늘 매매 중단. |
| 15:10 | 일일 결산 | [결산] 매매5회 / 승3패2 / 순손익 +1.2% |
| 15:30 | AI 피드백 | [분석] 오늘 평가 요약 + 수정사항 |
| 조건충족 | 실전 전환 | [🚀실전전환권고] 30일 검증 완료. 실거래 전환 검토. |
| 수시 | 긴급 | [긴급] WebSocket 끊김. kill-switch 실행. |
9. .env 구조
# KIS 실거래
KIS_APP_KEY=...
KIS_APP_SECRET=...
KIS_ACCOUNT_NO=...
# KIS 모의투자
KIS_MOCK_APP_KEY=...
KIS_MOCK_APP_SECRET=...
KIS_MOCK_ACCOUNT_NO=...
# 운영 모드
KIS_MOCK=true # true=모의투자 / false=실거래
DRY_RUN=true # true=신호만 확인 / false=실제 주문
# Discord
DISCORD_WEBHOOK_URL=...
# Redis
REDIS_HOST=stockbot-redis
REDIS_PORT=6379
# 기타
LOG_LEVEL=INFO
DB_PATH=data/stockbot.db
10. SQLite 스키마
-- 체결 내역
CREATE TABLE trades (
id INTEGER PRIMARY KEY AUTOINCREMENT,
date TEXT NOT NULL,
ticker TEXT NOT NULL,
name TEXT,
entry_time TEXT NOT NULL,
exit_time TEXT,
entry_price REAL NOT NULL,
exit_price REAL,
quantity INTEGER NOT NULL,
side TEXT NOT NULL, -- BUY / SELL
exit_reason TEXT, -- TP1/TP2/SL/FORCE/TIME
pnl REAL,
fee REAL,
ai_boosted INTEGER DEFAULT 0
);
-- 일일 요약
CREATE TABLE daily_summary (
date TEXT PRIMARY KEY,
total_trades INTEGER DEFAULT 0,
win_trades INTEGER DEFAULT 0,
lose_trades INTEGER DEFAULT 0,
net_pnl REAL DEFAULT 0,
max_drawdown REAL DEFAULT 0,
trading_stopped INTEGER DEFAULT 0
);
-- AI 판단 이력
CREATE TABLE ai_context_log (
date TEXT PRIMARY KEY,
generated_at TEXT,
trade_allowed INTEGER,
market_sentiment TEXT,
sentiment_score INTEGER,
risk_level TEXT,
hot_sectors TEXT,
avoid_sectors TEXT,
boosted_tickers TEXT,
blacklist_tickers TEXT,
position_size_mult REAL,
reason TEXT
);
11. 실전 전환 조건
모의투자 시작 후 매일 Claude Code가 자동 체크.
아래 5가지 전부 충족 시 reports/live_ready/날짜_READY.md 생성 + Discord 🚀 알림.
| 조건 | 기준 |
|---|---|
| 누적 운영 | 30거래일 이상 |
| 승률 | 최근 30일 > 48% |
| MDD | 최근 30일 < -10% |
| 샤프지수 | 최근 30일 > 1.0 |
| L3 발동 | 월 2회 이하 |
전환 시: .env에서 KIS_MOCK=false, DRY_RUN=false 로 변경.
12. 운영 모드 조합
| KIS_MOCK | DRY_RUN | 동작 |
|---|---|---|
| true | true | 신호만 확인 (주문 없음) ← 처음 테스트 |
| true | false | 모의투자 실제 주문 ← 3개월 검증 |
| false | false | 실거래 ← 조건 충족 후 |
13. 개발 로드맵
Phase 1 — 연결 테스트 (1주)
- .env 설정 (KIS 모의투자 키 4개)
- test_connection.py 실행 → KIS 연결 확인
- Discord Webhook 테스트
- DRY_RUN=true로 신호 발생 확인
Phase 2 — 모의투자 시작
- KIS_MOCK=true, DRY_RUN=false
- 매일 자동 실행 확인 (08:30 / 09:00 / 15:30)
- Discord 알림 정상 수신 확인
- 매일 reports/daily/ 리포트 자동 생성 확인
Phase 3 — 3개월 검증
- 30거래일 이상 운영
- Claude Code 자동 피드백 / 코드 개선 축적
- 실전 전환 조건 5가지 체크
Phase 4 — 실거래 (조건 충족 후)
- KIS_MOCK=false
- 총자산 100만원으로 시작
- 1개월 단위 성과 검토 → 점진적 증액
14. 보안 체크리스트
- .env → .gitignore 등록 (최우선)
- KIS API 키 → Gitea 절대 커밋 금지
- DISCORD_WEBHOOK_URL 외부 노출 금지
- NAS 방화벽: 포트 8501 내부망만 허용
- 매매 로그 SQLite + logs/ 이중 보관
15. 절대 금지
HARD_EXIT_TIME = "14:50" # 절대 변경 불가
AI_SCOPE = "ENTRY_ONLY" # AI는 신규 진입 차단만, 청산 불관여
BLACKLIST = [
"신규상장 6개월 미만", "관리종목", "투자경고",
"거래정지", "우선주", "스팩", "ETF/ETN",
]
TRADING_BLACKOUT = [
("08:00", "09:00"), # 동시호가
("11:30", "13:00"), # 점심
("14:50", "15:30"), # 마감
]
16. 면책
본 기획서는 시스템 설계 문서이며 투자 수익을 보장하지 않는다. 단타는 개인투자자의 90% 이상이 손실을 보는 영역이다. 반드시 모의투자 3개월 이상 검증 후 실거래 전환할 것.