galaxis-po/AGENTS.md

AGENTS.md - galaxis-po 개발 에이전트 가이드

프로젝트 개요

퀀트 & 퇴직연금 포트폴리오 관리 앱. 김종봉 전략 기반 백테스팅, 신호 생성, 포트폴리오 관리 기능 제공.

기술 스택

• Backend: FastAPI, Python 3.12, SQLAlchemy, PostgreSQL, uv
• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Infra: Docker, Docker Compose

디렉토리 구조

galaxis-po/
├── backend/
│   ├── app/          # FastAPI 앱 (main.py, api/, core/, models/)
│   ├── jobs/         # 스케줄러, 데이터 수집 잡
│   ├── alembic/      # DB 마이그레이션
│   └── requirements.txt / pyproject.toml
├── frontend/         # Next.js 앱
├── docs/plans/       # 설계 문서 (구현 전 반드시 확인)
└── quant.md          # 김종봉 전략 상세 가이드

개발 원칙

코드 작성 시

1. docs/plans/ 의 관련 설계 문서를 먼저 확인할 것
2. quant.md 에 전략 로직이 정의되어 있음 — 임의 변경 금지
3. 기존 코드 스타일 유지 (Python: snake_case, TS: camelCase)
4. 모든 API 엔드포인트는 backend/app/api/ 하위에 router로 추가
5. DB 스키마 변경 시 alembic migration 파일 함께 생성

금지 사항

• .env 파일 수정 금지 (.env.example 참고만 가능)
• docker-compose.prod.yml 임의 수정 금지
• 테스트 없는 비즈니스 로직 추가 금지

작업 완료 조건

• 기능 구현
• 관련 테스트 추가 또는 기존 테스트 통과 확인
• 타입 에러 없음 (Python: mypy / TS: tsc --noEmit)
• 작업 내용 요약 보고

자주 쓰는 명령

# 백엔드 개발 서버
cd backend && uv run uvicorn app.main:app --reload

# 프론트엔드 개발 서버
cd frontend && npm run dev

# DB 마이그레이션
cd backend && uv run alembic upgrade head

# 테스트 실행
cd backend && uv run pytest

보고 형식

작업 완료 시:

완료: [작업명]
변경 파일: [파일 목록]
주요 내용: [한 줄 요약]
주의사항: [있을 경우만]