# 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)
- [ ] 작업 내용 요약 보고

## 자주 쓰는 명령
```bash
# 백엔드 개발 서버
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
```

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