David Brain

서버 (befw-app-server)

3 min read

ID: key_26_22_05_25_18_01_00_00000 Created date: 5월 25 2026 월요일, 22주 18:00

연관 문서

개발 전 사전 정의 | 서버 개발

개요

befw-app-server 레포에서 Claude Code가 개발을 진행하려면
레포 루트의 CLAUDE.md 파일에 아래 항목이 정의되어 있어야 한다.

프로젝트 파일 위치

befw-app-server/
├── CLAUDE.md                        ← ★ Claude Code가 읽는 핵심 파일
├── pom.xml
└── src/
    └── main/
        ├── java/
        │   └── com/tsh/starter/befw/
        │       ├── controller/       ← API 엔드포인트
        │       ├── service/          ← 비즈니스 로직
        │       ├── repository/       ← DB 접근 (ORM 레이어)
        │       ├── domain/           ← 엔티티 / VO
        │       └── config/           ← Spring 설정 (Security, CORS 등)
        └── resources/
            ├── application.yml       ← 환경 설정
            └── db/migration/         ← Flyway SQL 파일 위치 (V1__init.sql 등)

CLAUDE.md 정의 항목 및 예시

1. 기술 스택 요약

## Tech Stack
- Language: Java 21 (--enable-preview)
- Framework: Spring Boot 3.x
- Build: Maven
- ORM: JPA (Hibernate) / MyBatis       ← 결정 후 하나만 기재
- DB: PostgreSQL 15
- Auth: JWT (Access Token + Refresh Token)
- Internal Framework: befw-lib-core (com.tsh.starter.befw)

작성 필요: ORM 종류 확정 후 기재

2. befw-lib-core 제공 기능 목록

## befw-lib-core 제공 기능
- CommonResponse<T>: 공통 API 응답 래퍼
- GlobalExceptionHandler: 전역 예외 처리
- JwtUtil: 토큰 발급 / 검증 유틸
- BaseEntity: createdAt, updatedAt 공통 필드
- (추가 항목을 직접 기재)

작성 필요: 실제 befw-lib-core 소스를 열어 공개된 클래스/유틸 목록 기재

3. API 응답 포맷 (공통 JSON 구조)

## API Response Format
 
### 성공
{
  "success": true,
  "data": { ... },
  "message": null
}
 
### 실패
{
  "success": false,
  "data": null,
  "message": "에러 메시지",
  "errorCode": "ISSUE_NOT_FOUND"
}

작성 필요: CommonResponse 클래스의 실제 필드명 기준으로 수정

4. 에러 코드 체계

## Error Code Convention
- 포맷: {도메인}_{상태}
- 예시:
  - AUTH_UNAUTHORIZED
  - AUTH_TOKEN_EXPIRED
  - ISSUE_NOT_FOUND
  - ISSUE_INVALID_STATUS
  - PROJECT_ACCESS_DENIED

작성 필요: 실제 사용할 에러 코드 목록 정의

5. 패키지 구조 규칙

## Package Convention
com.tsh.starter.befw.{도메인명}
  └── controller/   @RestController, @RequestMapping("/api/v1/{도메인}")
  └── service/      @Service, 비즈니스 로직
  └── repository/   @Repository, JPA/MyBatis
  └── domain/       @Entity, @Table
  └── dto/          Request/Response DTO (record 사용 권장)

작성 필요: 실제 패키지 구조가 다르면 수정

6. 로컬 실행 방법

## Local Setup
1. PostgreSQL 실행 (포트 5432, DB명: custom_jira_dev)
2. application-local.yml 환경변수 설정
3. ./mvnw spring-boot:run -Dspring-boot.run.profiles=local

작성 필요: 실제 실행 명령 및 DB 접속 정보 포맷 기재

7. 환경변수 목록

## Environment Variables (application.yml)
spring.datasource.url=jdbc:postgresql://localhost:5432/custom_jira_dev
spring.datasource.username=
spring.datasource.password=
jwt.secret=
jwt.access-token-expiry=3600
jwt.refresh-token-expiry=604800

작성 필요: 실제 키 이름 확인 후 기재 (값은 빈칸으로)

연관 메일

Graph View

Backlinks