# 단타 자동매매 시스템 종합 기획서 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. 핵심 설계 원칙 (절대 불변) 1. **감정 0** — 진입/청산은 코드가 결정, AI는 보조 2. **손절 우선** — AI 긍정 판단과 무관하게 손절 룰 항상 우선 3. **14:50 강제 청산** — 하드코딩, 어떤 상황에서도 예외 없음 4. **검증 순서 필수** — 모의투자 3개월 → 실전 전환 조건 충족 → 실거래 5. **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) ```python # 변동성 돌파 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) ```dockerfile # claude_morning/Dockerfile FROM node:20-slim RUN npm install -g @anthropic-ai/claude-code WORKDIR /app COPY run.sh . CMD ["bash", "run.sh"] ``` ```bash # 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) ```bash # 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 스키마 ```sql -- 체결 내역 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. 절대 금지 ```python 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개월 이상 검증 후 실거래 전환할 것.