Draft Architecture

우선 기본 설계는 아래 생성형 AI 서비스를 기반으로 진행합니다.

• Architecture / Prompt Engineering - Gemini3 Pro
• Chat Completion - ChatGPT 5.2
• Agentic Deep Search - Claude Sonnet 4.6

---

 

 

Project Structure

crypto_ai_agent/
├── config/                  # 설정 파일 저장소
│   ├── config.yaml          # 트레이딩 설정 (종목, 주기, 리스크 한도 등)
│   └── prompt_templates.py  # LLM에게 보낼 프롬프트 템플릿 모음
├── data/                    # 로컬 데이터 저장소 (DB, CSV)
│   ├── trade_history.db     # 매매 기록 (SQLite)
│   └── logs/                # 로그 파일 폴더
├── src/                     # 핵심 소스 코드
│   ├── __init__.py
│   ├── market_data/         # [눈/귀] 데이터 수집 모듈
│   │   ├── connector.py     # CCXT 거래소 연결
│   │   └── technical.py     # 보조지표(RSI, MACD) 계산
│   ├── brain/               # [뇌] AI 판단 모듈
│   │   ├── llm_client.py    # OpenAI/Claude API 통신
│   │   ├── reasoning.py     # 매매 논리 및 결정 생성
│   │   └── memory.py        # 단기/장기 기억 (이전 매매 복기)
│   ├── governance/          # [전두엽] 리스크 관리 & 검증
│   │   ├── risk_manager.py  # 자금 관리, 손절 라인 강제
│   │   └── validator.py     # AI 응답(JSON) 유효성 검사
│   ├── execution/           # [손/발] 주문 실행 모듈
│   │   └── order_executor.py# 실제 매수/매도 주문 전송
│   └── utils/               # 공통 유틸리티
│       ├── logger.py        # 로깅 설정
│       └── notifier.py      # 텔레그램/슬랙 알림
├── tests/                   # 단위 테스트 (Unit Test)
├── .env                     # API Key 등 보안 정보
├── main.py                  # 프로그램 진입점 (Entry Point)
├── requirements.txt         # 의존성 패키지 목록
└── Dockerfile               # 배포용 도커 이미지 설정

 

 

Logical Architecture & Data Flow

데이터는 [수집 -> 분석 -> 판단 -> 검증 -> 실행]의 단방향 파이프라인을 따릅니다.

1. Market Data Layer (수집)
   • 역할: 거래소(Upbit/Binance)에서 캔들 데이터(OHLCV)와 호가창 정보를 가져옵니다.
   • 확장성: ExchangeConnector 클래스를 추상화(Interface)하여 나중에 Upbit 클래스를 Binance로 바꿔 끼우기만 하면 작동하도록 설계합니다.
2. Feature Engineering Layer (분석)
   • 역할: 원본 데이터를 AI가 이해하기 쉬운 형태(피처)로 가공합니다.
   • 핵심: Ta-Lib을 이용해 RSI, 볼린저밴드 수치를 계산하고, 뉴스 헤드라인을 가져와 감성 점수(Sentiment Score)를 매깁니다.
3. Brain Layer (판단 - LLM Agent)
   • 역할: 수치 데이터 + 시장 뉴스 + 자신의 과거 매매 기록을 프롬프트로 받아 매매 여부를 결정합니다.
   • 출력: 단순 텍스트가 아닌 구조화된 JSON을 뱉어야 합니다.
   •  

     {
         "decision": "BUY",
         "confidence": 0.85,
         "reason": "RSI가 과매도(25) 상태이며, 비트코인 반감기 뉴스 호재가 있음",
         "allocation_percent": 10
     }
     

   • JSON
4. Governance Layer (검증 - Hard Rules)
   • 역할: AI를 믿지 않는 단계입니다. AI가 "BUY"를 외쳐도 이 계층에서 거부할 수 있습니다.
   • 규칙 예시:
     • 이미 보유 현금이 5% 미만이면 매수 불가.
     • 변동성이 너무 심하면(VIX 지수 급등 시) 매매 중단.
     • 하루 손실 한도(-3%) 도달 시 강제 종료 (Circuit Breaker).
5. Execution Layer (실행)
   • 역할: 검증된 명령을 실제 API 주문으로 변환합니다. API 에러 시 재시도(Retry) 로직이 포함됩니다.

 

관리 및 운영

 

봇을 24시간 365일 안정적으로 돌리기 위한 전략입니다.

A. 로깅의 이원화 (Dual Logging)

로그를 두 가지 레벨로 나누어 관리해야 원인 파악이 쉽습니다.

• System Log (system.log): 프로그램 에러, API 연결 끊김, 메모리 부족 등 **'개발자'**를 위한 로그.
• Trading Log (trade_journal.log): AI가 왜 샀는지(Reason), 당시 지표 값, 수익률 등 **'트레이더'**를 위한 로그. 나중에 이 로그를 다시 AI에게 학습시켜 성능을 개선합니다.

B. 설정의 외부화 (Configuration Management)

코드를 수정하지 않고 봇의 성격을 바꿀 수 있어야 합니다. config.yaml 파일로 관리합니다.

YAML

strategy:
  risk_level: "conservative" # conservative, aggressive
  target_coin: "KRW-BTC"
  timeframe: "15m"

risk:
  max_drawdown_daily: 0.03 # 하루 3% 잃으면 종료
  max_position_size: 0.2   # 한 번에 시드의 20%만 진입

C. 알림 시스템 (Notification)

봇이 죽었는지 살았는지 매번 로그 파일을 열어볼 수 없습니다.

• Telegram Bot을 연동하여 매매 체결 시, 에러 발생 시 즉시 푸시 알림을 보냅니다.
• Heartbeat: 1시간마다 "정상 작동 중, 현재 수익률 +1.2%" 메시지를 보내 생존 신고를 하게 합니다.

 

확장 전략

처음엔 단순하게 시작하되, 나중에 고도화할 수 있는 길을 열어둡니다.

1. 모델 다변화 (Multi-Model Consensus):
   • 지금은 GPT-4o 하나만 쓰지만, 나중에는 Claude 3.5(분석용)와 GPT-4(결정용) 두 모델에게 동시에 물어보고 둘 다 "매수"라고 할 때만 진입하는 **'합의 알고리즘'**을 도입할 수 있도록 Brain 모듈을 유연하게 짭니다.
2. 벡터 DB 도입 (Memory Augmentation):
   • 초기에는 지난 10개의 매매 기록만 프롬프트에 넣지만, 나중에는 ChromaDB나 Pinecone 같은 벡터 DB를 붙입니다.
   • *"지난달 비슷한 차트 패턴에서 내가 손절했었지"*라는 장기 기억을 AI가 떠올리게 할 수 있습니다.
3. 백테스팅 (Backtesting) 모드:
   • Execution Layer에 MockExecutor를 만들어, 과거 데이터를 흘려보내며 실제 돈을 쓰지 않고 전략을 검증하는 모드를 쉽게 켤 수 있게 설계합니다.

 

RoadMap

이 아키텍처를 기반으로 다음 순서로 개발 진행 예정입니다.

1. 환경 설정: 프로젝트 폴더 생성 및 라이브러리 설치 (ccxt, openai, pandas, python-dotenv).
2. Market Data: 거래소 시세 조회 및 기술적 지표 계산 함수 구현.
3. Governance (중요): 묻지마 매수를 막을 리스크 관리 클래스 구현.
4. Brain: LLM 프롬프트 엔지니어링 및 JSON 파싱 로직 구현.
5. Execution & Loop: 실제 주문 및 메인 루프(while True) 구현.

 

CheckList

코드가 완성 후의 확인 사항입니다. 

1. Dry Run (모의 투자): 처음에는 execute_order 함수에서 실제 주문(create_order) 코드를 주석 처리하고 print("주문 실행 됨") 로그만 찍히게 해서 며칠 돌려보세요.
2. 로그 확인: AI가 JSON 형식을 잘 지키는지, RiskManager가 위험한 주문을 잘 차단하는지 로그 파일을 통해 확인해야 합니다.
3. 비용 관리: GPT-4o는 비용이 발생하므로, 너무 자주(예: 1분마다) 호출하면 API 비용이 많이 나옵니다. 1시간 또는 4시간 봉 기준으로 시작하는 것을 추천합니다.