ID: key_26_22_05_25_사전_P5 Created date: 5월 25 2026 월요일
연관 문서
개발 일정 > 사전 준비 서버 (befw-app-server) | DB (PostgreSQL)
개요
befw-app-server (CIRA 서버 레포) 루트에 CLAUDE.md를 작성한다.
이 파일은 Claude Code가 서버 코드를 생성·수정할 때 참조하는 핵심 컨텍스트 문서다.
Claude Code 작업 수행서
목표
서버 레포 루트에 CLAUDE.md를 생성하고, Claude Code가 일관된 방식으로 코드를 생성할 수 있도록 모든 컨벤션을 명시한다.
작업 지시
C:\workspace\tsh\boilerplate\be\befw\dd\cira\CLAUDE.md 파일을 생성해줘.
아래 섹션을 모두 포함해서 작성해야 해.
---
## 프로젝트 개요
- 서비스명: CIRA (Custom Jira)
- 역할: 사내 프로젝트 관리 플랫폼 백엔드 API 서버
- 언어: Java 17 / Kotlin
- 프레임워크: Spring Boot 3.x
- 기반 라이브러리: befw-lib-core (공통 기능 제공)
## 아키텍처
- 레이어 구조: Controller → Service → Repository
- 패키지 구조:
com.tas.cira
├── auth/ (인증 도메인)
├── user/ (사용자 도메인)
├── project/ (프로젝트 도메인)
├── issue/ (이슈 도메인)
├── sprint/ (스프린트 도메인)
├── board/ (칸반 보드 도메인)
├── comment/ (댓글 도메인)
└── common/ (공통: 응답포맷, 예외, 유틸)
## DB Migration
- 도구: Flyway
- 파일 위치: src/main/resources/db/migration/
- 네이밍: V{버전}__{설명}.sql (예: V1__create_users.sql)
- 버전 간격: 10 단위 (V10, V20 — 중간 삽입 여지 확보)
- ddl-auto: validate (Flyway가 DDL 관리)
## Table Convention
- 테이블명: snake_case 복수형
- 컬럼명: snake_case
- PK: id UUID DEFAULT gen_random_uuid()
- FK: {참조테이블단수형}_id
- 공통 컬럼: created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ, deleted_at TIMESTAMPTZ
- Soft Delete: deleted_at IS NULL = 정상, IS NOT NULL = 삭제
- 조회 시 항상 WHERE deleted_at IS NULL 조건 포함
## API 컨벤션
- Base URL: /api/v1
- 응답 포맷: ApiResponse<T> 래퍼 사용
- 에러 응답: { success: false, error: { code, message, details } }
- 인증: Bearer JWT (Authorization 헤더)
- 페이지네이션: ?page=0&size=20 (0-indexed)
## 코드 생성 규칙
- Controller: @RestController, @RequestMapping, @Validated
- Service: @Service, @Transactional(readOnly = true) 기본
- 쓰기 작업에만 @Transactional 명시
- Repository: Spring Data JPA Repository 인터페이스
- DTO:
- Request: XxxRequest.java (record 또는 class + @Valid)
- Response: XxxResponse.java (record 권장)
- Exception: CiraException(ErrorCode) 사용
- 로깅: @Slf4j, log.info/warn/error 사용
## 보안 규칙
- 모든 API는 인증 필요 (명시적 허용 목록 제외)
- 허용 목록: POST /auth/login, POST /auth/register, POST /auth/refresh
- RBAC: @PreAuthorize 또는 서비스 레이어에서 권한 검증
- 입력값 검증: Bean Validation (@NotNull, @Size 등) 필수
## 테스트 규칙
- 단위 테스트: Service 레이어 (Mockito)
- 통합 테스트: @SpringBootTest + TestContainers (PostgreSQL)
- 커버리지 목표: 서비스 레이어 80% 이상
## befw-lib-core 활용
- [P1 분석 결과 반영]
## Error Code 목록
- [P3 에러코드 테이블 반영]
완료 기준
| 항목 | 기준 |
|---|---|
| CLAUDE.md 존재 | 레포 루트에 커밋 |
| 전체 섹션 포함 | 아키텍처~에러코드 전체 기재 |
| Claude Code 검증 | CLAUDE.md 기반 코드 생성 테스트 1회 수행 |
선행 조건
후행 작업
- 1-1_DB-DDL-Flyway-마이그레이션 — 이 파일 기반으로 진행