Skip to content

AGENTS.md

Latest commit

 

History

History
224 lines (159 loc) · 8.26 KB

AGENTS.md

File metadata and controls

224 lines (159 loc) · 8.26 KB
Raw

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

프로젝트 개요

Kotlin과 Spring Boot 기반의 다마고치 게임 백엔드 서버입니다. 사용자는 OAuth 로그인을 통해 동물을 키우고, 칼로리를 관리하며, 다른 사용자들과 랭킹을 비교할 수 있습니다.

개발 명령어

빌드 및 실행

# 프로젝트 빌드
./gradlew build

# 애플리케이션 실행
./gradlew bootRun

# 테스트 실행
./gradlew test

# Docker 이미지 빌드
./gradlew jib

코드 품질

현재 ktlint는 주석 처리되어 있습니다 (build.gradle.kts:4).

기술 스택

  • 언어: Kotlin 1.9.24
  • 프레임워크: Spring Boot 3.3.1
  • 데이터베이스: MongoDB (Spring Data MongoDB)
  • 인증: JWT + OAuth2 (Kakao, Apple)
  • 푸시 알림: Firebase FCM
  • 문서화: SpringDoc OpenAPI (Swagger)
  • 모니터링: Spring Actuator + Prometheus
  • 컨테이너: Docker (Jib 플러그인)
  • 테스트: JUnit 5 + MockK

아키텍처

  • layered 아키텍처로 구성되어 있다.

레이어 구조

Domain Layer (domain/)

  • model/: 비즈니스 도메인 모델 (User, Pet, Auth, Ranking 등)
  • exception/: 도메인별 커스텀 예외 클래스
  • gateway/: 외부 의존성에 대한 인터페이스 (향후 제거 예정)

Application Layer (application/)

  • service/: 비즈니스 로직을 처리하는 서비스 클래스
  • processor/: OAuth 처리를 위한 프로세서 (Factory 패턴)

Infrastructure Layer (infrastructure/)

  • database/: MongoDB 엔티티 및 리포지토리
  • api/: 외부 API 클라이언트 (Kakao, Apple, Slack)
  • gateway/: Gateway 인터페이스 구현체 (향후 제거 예정)

Presentation Layer (presentation/)

  • controller/: REST API 엔드포인트
  • dto/: 요청/응답 데이터 전송 객체
  • filter/: JWT 인증 및 로깅 필터
  • scheduler/: 정기 실행 스케줄러

주요 기능

인증 (auth/)

  • OAuth2 로그인 (Kakao, Apple)
  • JWT 토큰 기반 인증/인가
  • 토큰 갱신

사용자 관리 (user/)

  • 사용자 정보 관리
  • 사용자 설정 (알림, 개인정보)
  • 메인 펫 설정

반려동물 (pet/)

  • 반려동물 추가/조회
  • 먹이 주기, 놀아주기
  • 랜덤 펫 추가

랭킹 시스템 (ranking/)

  • 사용자 랭킹 조회
  • 랭킹 보드 관리
  • 주기별 랭킹 업데이트

푸시 알림 (notification/)

  • FCM을 통한 푸시 알림
  • 칼로리 체크 알림
  • 주간 랭킹 알림
  • 비활성 사용자 알림

설정 파일

  • application.yaml: 메인 설정 파일
  • config/application.yaml: 환경별 설정

Docker 배포

Jib 플러그인을 사용하여 Docker 이미지를 빌드합니다:

  • 베이스 이미지: amazoncorretto:17-alpine-jdk
  • 플랫폼: linux/arm64
  • 포트: 8080
  • 타임존: Asia/Seoul

Git 브랜치 전략

이슈 기반 개발 워크플로우

  1. 이슈 생성: GitHub에서 새로운 이슈를 생성합니다
    • 이슈 제목은 간단명료하게 작성합니다
    • 이슈 내용에 작업의 목적과 세부사항을 기재합니다
    • 이슈 번호는 브랜치 명명 규칙에 사용됩니다
    • 이슈 제목의 형식은 [작업 형태] 간단한 설명입니다
    • 작업 형태는 feat, refactor, docs, fix, chore 등으로 구분합니다
  2. 브랜치 생성: 이슈 번호를 포함한 브랜치를 생성합니다
    • 브랜치 이름은 타입/#이슈번호-간단한-설명 형식으로 작성합니다
  3. 작업 수행: 해당 브랜치에서 이슈 내용에 맞는 작업을 진행합니다
  4. PR 생성: develop 브랜치로 Pull Request를 생성합니다
    • PR 제목은 타입: 설명 형식으로 작성합니다
    • PR 제목에 끝에 이슈번호는 추가하지 않습니다
    • PR 본문은 .github/pull_request_template.md 템플릿을 사용합니다

브랜치 명명 규칙

# 기본 형태
{타입}/#이슈번호-간단한-설명

# 브랜치 타입별 예시
feature/#190-ranking-refactor-to-layered    # 새로운 기능 개발
refactor/#189-user-pet-layered-architecture # 리팩토링
docs/#194-git-branch-strategy-docs          # 문서화 작업
fix/#xxx-bug-fix-description                # 버그 수정
chore/#xxx-dependency-update                # 빌드, 의존성 등

브랜치 타입 가이드

  • feature/: 새로운 기능 개발
  • refactor/: 코드 리팩토링
  • docs/: 문서화 작업 (README, AGENTS.md 등)
  • fix/: 버그 수정
  • chore/: 빌드 스크립트, 의존성 업데이트 등

주요 명령어

# 현재 이슈 목록 확인
gh issue list

# 특정 이슈 상세 정보 확인
gh issue view 190

# 새 브랜치 생성 및 체크아웃
git checkout -b feature/#190-ranking-refactor-to-layered

# develop 브랜치로 PR 생성
gh pr create --title "refactor: Ranking 기능 레이어드 아키텍처로 변경 (#190)" --body "$(cat <<'EOF'
## 🔎 작업 내용
-

## ➕ 기타
-

close #이슈번호
EOF
)"

개발 시 참고사항

  • MongoDB는 @Document 어노테이션을 사용한 엔티티로 관리
  • JWT 토큰은 JWTTokenProvider에서 생성/검증
  • 예외 처리는 WebExceptionHandler에서 글로벌 처리
  • 모든 API는 Swagger UI로 문서화됨 (/swagger-ui.html)
  • 클라이언트용 API 문서 진입점은 루트의 API.md이며, 상세 문서는 docs/api/에 도메인별로 관리합니다.
  • 정확한 HTTP 계약은 docs/api/openapi.yaml, 업무 규칙과 호출 흐름은 docs/api/*.md를 기준으로 합니다.
  • controller, DTO, 인증, 상태 코드 또는 에러 코드 변경 시 같은 작업에서 API 문서를 반드시 갱신합니다.
  • OpenAPI 스냅샷은 서버 실행 후 ./scripts/update-openapi.sh [base-url]로 갱신합니다.
  • API 문서 변경 후 ./scripts/validate-api-docs.sh를 실행합니다.
  • 로깅은 LoggingFilter와 LoggingUtils를 활용
  • 파일 끝에는 항상 개행 문자를 추가합니다

하네스: ddan-ddan-server 백엔드 개발

목표: 이슈 분석 → 설계 → 구현 → 테스트·API 문서 → 리뷰 → PR 생성을 6개 전문 에이전트로 자동화한다.

트리거: 기능 추가, 버그 수정, 리팩토링, 이슈 작업, PR 생성 요청 시 ddan-ddan-feature-dev 스킬을 사용하라. 한 줄 수정·단순 코드 질문은 직접 응답.

구성 위치:

  • 에이전트: .codex/agents/ (issue-analyzer, backend-architect, kotlin-spring-implementer, test-engineer, api-documenter, code-reviewer)
  • 스킬: .agents/skills/ (ddan-ddan-feature-dev 오케스트레이터 + layered-architecture-guide, kotlin-spring-conventions, kotest-testing-patterns, korean-pr-convention)

API 문서 에이전트

  • api-documenter는 구현 이후 test-engineer와 병렬 실행합니다.
  • API 변경이 있으면 SpringDoc OpenAPI 스냅샷과 관련 도메인 문서를 갱신합니다.
  • API 변경이 없으면 문서를 수정하지 않고 _workspace/04_api_docs.md에 “문서 변경 불필요”와 근거를 기록합니다.
  • code-reviewer는 코드와 API 문서의 불일치를 Major 이상으로 차단합니다.

변경 이력:

날짜 변경 내용 대상 사유
2026-05-02 초기 구성 전체 -
2026-05-03 Spring 어노테이션 핵심 코드 통합 테스트 가이드 추가 skills/kotest-testing-patterns PR #277 사고 — @TransactionalEventListener가 단일 MongoDB 환경에서 silent dropping. 단위 테스트가 listener 직접 호출이라 잡지 못함.
2026-05-03 체크리스트 보강 (통합 테스트 누락 + @TransactionalEventListener + 트랜잭션 매니저 페어 점검) agents/code-reviewer 동일 사고 재발 방지
2026-05-06 체크리스트 보강 (SecurityFilterChain Order/securityMatcher 매트릭스 점검) agents/code-reviewer PR #302 사고 — apiFilterChain Order=1이 loginFilterChain Order=2보다 먼저 평가되어 /v1/auth/login이 401로 차단됨. 단위 테스트로 못 잡음.
2026-06-23 API 문서 구조와 api-documenter 에이전트 추가 API.md, docs/api, feature-dev, code-reviewer 클라이언트 에이전트의 계약 탐색성과 API 변경 시 문서 동기화 보장