sundol/CLAUDE.md

작업 규칙 (절대 규칙)

• 코드를 수정하기 전에 반드시 계획을 사용자에게 설명하고 컨펌을 받은 후 진행할 것. 컨펌 없이 코드를 절대 건드리지 말 것.
• 사용자가 질문하면 질문에만 답할 것. 답변 후 임의로 코드를 수정하지 말 것.
• 문제를 발견해도 직접 고치지 말고 보고만 할 것.
• 전략 로직(매수/매도 조건, LLM 프롬프트, 계층 구조)은 절대 자의적으로 변경 금지.
• 존댓말 사용.
• null 처리, exception 처리 시 무시/빈값 처리 하지 않도록 한다. (ignored, 빈 리스트 반환 등 금지)
• 변경이 단순하더라도 절차를 생략하지 말 것. "단순하니까 괜찮겠지"라는 임의 판단 금지.

배포 전 필수 절차 (순서대로)

1. 컴파일 확인
2. PMD 정적 분석 실행
3. 변경된 코드 전체를 다시 읽고 로직 리뷰 (재시도 시 데이터 중복 적재, null 참조, 카운터/리스트 누적 등 세는 로직 문제 확인)
4. 점검 결과를 사용자에게 보고하고 승인받은 후 배포 진행

빌드/배포

• 빌드: cd backend && export JAVA_HOME=/opt/homebrew/Cellar/openjdk/25.0.2/libexec/openjdk.jdk/Contents/Home && set -a && source ../.env && set +a && mvn package -q -DskipTests
• 컴파일만: cd backend && export JAVA_HOME=/opt/homebrew/Cellar/openjdk/25.0.2/libexec/openjdk.jdk/Contents/Home && set -a && source ../.env && set +a && mvn compile
• 프론트엔드 빌드/배포: cd sundol-frontend && bash build.sh (환경변수 검증 포함)
• 프론트엔드 빌드 전 .env에 NEXT_PUBLIC_GOOGLE_CLIENT_ID, NEXT_PUBLIC_API_URL 필수. 없으면 Google OAuth 로그인 깨짐.
• 배포 시 반드시 git push origin main 포함

DB 접속 (Oracle Autonomous DB - SQLcl)

• 환경변수 파일: .env (프로젝트 루트)
• SQLcl 실행 (DB 작업은 반드시 SQLcl을 통해 수행):

# .env에서 ORACLE_WALLET_PATH, ORACLE_TNS_NAME, ORACLE_USERNAME, ORACLE_PASSWORD 참조
set -a && source .env && set +a
sql ${ORACLE_USERNAME}/${ORACLE_PASSWORD}@${ORACLE_TNS_NAME}?TNS_ADMIN=${ORACLE_WALLET_PATH}

• DDL 변경이 필요하면 SQLcl로 직접 ALTER TABLE 실행할 것
• 테이블 생성/변경 등 모든 DB 스키마 작업은 SQLcl을 통해 수행

코드 설계 원칙

• 최대한 모듈화하여 재활용 가능하도록 설계할 것
• 아래 디자인 패턴 가이드를 참조하여 적절한 패턴을 적용할 것
• 과도한 패턴 사용은 지양하고, 문제 복잡도에 맞는 수준으로 적용할 것

소프트웨어 디자인 패턴 참조 가이드

디자인 패턴은 개발자들이 직면하는 반복적인 문제들을 해결하기 위한 검증된 방법론입니다.

1. 생성 패턴 (Creational Patterns)

• 싱글톤 (Singleton): 특정 클래스의 인스턴스가 오직 하나만 생성되도록 보장 (전역 설정, 로깅, 캐시 관리)
• 팩토리 (Factory): 객체 생성 로직을 캡슐화하여 클라이언트에서 직접 생성하지 않도록 함 (조건부 객체 생성)
• 빌더 (Builder): 복잡한 객체를 단계별로 구성하여 생성 (매개변수가 많거나 선택적일 때)
• 프로토타입 (Prototype): 기존 객체를 복제하여 기능 확장

2. 구조 패턴 (Structural Patterns)

• 퍼사드 (Facade): 복잡한 내부 시스템을 단순한 인터페이스로 감싸기 (API 래퍼, 복잡한 라이브러리 단순화)
• 어댑터 (Adapter): 서로 호환되지 않는 인터페이스를 연결
• 프록시 (Proxy): 실제 객체 대신 대리인 객체를 사용하여 접근 제어나 부가 기능 수행 (지연 로딩, 캐싱)

3. 행위 패턴 (Behavioral Patterns)

• 옵저버 (Observer/Pub-Sub): 한 객체의 상태 변화를 여러 구독자들에게 알림 (이벤트 기반 시스템)
• 이터레이터 (Iterator): 컬렉션의 내부 구조를 노출하지 않고 요소들을 순회
• 전략 (Strategy): 알고리즘을 외부에서 주입받아 사용하여 동작을 확장 (Open-Closed 원칙 준수)
• 메디에이터 (Mediator): 객체들이 직접 통신하지 않고 중재자를 거쳐 복잡한 관계 단순화
• 스테이트 (State): 객체의 내부 상태에 따라 행동이 달라지게 함 (복잡한 조건문을 클래스로 대체)

패턴 적용 주의사항

• 단순한 문제에 복잡한 패턴 적용 지양
• 일부 패턴은 성능 오버헤드 발생 가능하므로 성능 고려
• 팀원들이 이해할 수 있는 수준의 패턴 선택