Files

CI / test (pull_request) Has been cancelled

Details

refactor: split CLAUDE.md into focused documentation structure

- Restructure docs into topic-specific files to minimize context
- Create docs/workflow.md (Git + Agent workflow)
- Create docs/commands.md (Common failures + build commands)
- Create docs/architecture.md (System design + data flow)
- Create docs/testing.md (Test structure + guidelines)
- Rewrite CLAUDE.md as concise hub with links to detailed docs
- Update .gitignore to exclude data/ directory

Benefits:
- Reduced context size for AI assistants
- Faster reference lookups
- Better maintainability
- Topic-focused documentation

Closes #13

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-02-04 10:13:48 +09:00

3.2 KiB

Raw Blame History

The Ouroboros

AI-powered trading agent for global stock markets with self-evolution capabilities.

Quick Start

# Setup
pip install -e ".[dev]"
cp .env.example .env
# Edit .env with your KIS and Gemini API credentials

# Test
pytest -v --cov=src

# Run (paper trading)
python -m src.main --mode=paper

Documentation

Workflow Guide — Git workflow policy and agent-based development
Command Reference — Common failures, build commands, troubleshooting
Architecture — System design, components, data flow
Testing — Test structure, coverage requirements, writing tests
Agent Policies — Prime directives, constraints, prohibited actions

Core Principles

Safety First — Risk manager is READ-ONLY and enforces circuit breakers
Test Everything — 80% coverage minimum, all changes require tests
Issue-Driven Development — All work goes through Gitea issues → feature branches → PRs
Agent Specialization — Use dedicated agents for design, coding, testing, docs, review

Project Structure

src/
├── broker/          # KIS API client (domestic + overseas)
├── brain/           # Gemini AI decision engine
├── core/            # Risk manager (READ-ONLY)
├── evolution/       # Self-improvement optimizer
├── markets/         # Market schedules and timezone handling
├── db.py            # SQLite trade logging
├── main.py          # Trading loop orchestrator
└── config.py        # Settings (from .env)

tests/               # 54 tests across 4 files
docs/                # Extended documentation

Key Commands

pytest -v --cov=src              # Run tests with coverage
ruff check src/ tests/           # Lint
mypy src/ --strict               # Type check

python -m src.main --mode=paper  # Paper trading
python -m src.main --mode=live   # Live trading (⚠️ real money)

# Gitea workflow (requires tea CLI)
YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "..." --description "..."
YES="" ~/bin/tea pulls create --head feature-branch --base main --title "..." --description "..."

Markets Supported

🇰🇷 Korea (KRX)
🇺🇸 United States (NASDAQ, NYSE, AMEX)
🇯🇵 Japan (TSE)
🇭🇰 Hong Kong (SEHK)
🇨🇳 China (Shanghai, Shenzhen)
🇻🇳 Vietnam (Hanoi, HCM)

Markets auto-detected based on timezone and enabled in ENABLED_MARKETS env variable.

Critical Constraints

⚠️ Non-Negotiable Rules (see docs/agents.md):

src/core/risk_manager.py is READ-ONLY — changes require human approval
Circuit breaker at -3.0% P&L — may only be made stricter
Fat-finger protection: max 30% of cash per order — always enforced
Confidence < 80 → force HOLD — cannot be weakened
All code changes → corresponding tests → coverage ≥ 80%

Contributing

See docs/workflow.md for the complete development process.

TL;DR:

Create issue in Gitea
Create feature branch: feature/issue-N-description
Implement with tests
Open PR
Merge after review

3.2 KiB Raw Blame History