Spring Boot 프로젝트를 Claude Code와 함께 빠르게 시작하기 위한 템플릿입니다. 반복 작업(API 스캐폴딩, 코드 리뷰)을 커맨드로 자동화하고, 일관된 코드 스타일을 유지할 수 있도록 구성되어 있습니다.
| 분류 | 기술 |
|---|---|
| 언어 | Java 17 |
| 프레임워크 | Spring Boot 3.4.3 |
| 빌드 | Gradle 8.x |
| ORM | Spring Data JPA + Hibernate |
| DB 마이그레이션 | Flyway |
| DB | H2 (로컬) / PostgreSQL (운영) |
| 테스트 | JUnit 5 + Mockito + AssertJ |
| 유틸리티 | Lombok |
- Java 17
- Claude Code CLI 설치
# 1. 빌드
./gradlew build
# 2. 실행
./gradlew bootRun실행 후 확인:
| 엔드포인트 | URL |
|---|---|
| API 서버 | http://localhost:8080 |
| H2 Console | http://localhost:8080/h2-console |
| Health Check | http://localhost:8080/actuator/health |
.
├── .claude/ # Claude Code 전용 설정
│ ├── commands/ # 커스텀 슬래시 커맨드
│ │ ├── new-api.md # /new-api — API 레이어 전체 생성
│ │ ├── new-entity.md # /new-entity — Entity + 마이그레이션 생성
│ │ └── review-code.md # /review-code — 규칙 기준 코드 리뷰
│ └── rules/ # Claude가 코드 작성 시 참고하는 규칙
│ ├── api-design.md # URL 네이밍, DTO, 응답 코드 규약
│ ├── db-schema.md # JPA 엔티티 설계, Flyway 규칙
│ └── testing.md # 테스트 코드 작성 원칙
│
├── src/main/java/com/example/module/
│ ├── Application.java # 진입점
│ ├── config/
│ │ └── JpaConfig.java # @EnableJpaAuditing 설정
│ ├── dto/response/
│ │ └── ErrorResponse.java # 오류 응답 Record { code, message }
│ └── exception/
│ ├── ErrorCode.java # 에러 코드 enum (HTTP 상태 + 메시지)
│ ├── BusinessException.java # 커스텀 예외 (ErrorCode를 담아서 throw)
│ └── GlobalExceptionHandler.java # @RestControllerAdvice 전역 처리
│
├── src/main/resources/
│ ├── application.properties # H2, JPA, Flyway, Actuator 기본 설정
│ └── db/migration/
│ └── V1__init.sql # Flyway 첫 번째 마이그레이션 (자리 표시자)
│
├── CLAUDE.md # 프로젝트 전체 컨텍스트 (Claude가 가장 먼저 읽음)
├── build.gradle
├── settings.gradle
└── gradle.properties
이 템플릿의 핵심입니다. .claude/commands/에 정의된 커맨드로 반복 작업을 자동화합니다.
도메인 이름 하나로 전체 API 레이어를 한번에 생성합니다.
/new-api Post
생성되는 파일:
controller/PostController.java
service/PostService.java
repository/PostRepository.java
entity/Post.java
dto/request/PostCreateRequest.java
dto/request/PostUpdateRequest.java
dto/response/PostResponse.java
db/migration/V2__post.sql
test/.../PostServiceTest.java
test/.../PostControllerTest.java
test/.../PostRepositoryTest.java
모든 파일은 .claude/rules/의 규칙(URL 네이밍, 엔티티 설계, 테스트 원칙)을 자동으로 준수합니다.
Entity와 Flyway 마이그레이션 파일만 생성합니다. 서비스/컨트롤러 없이 DB 설계만 먼저 할 때 사용합니다.
/new-entity Comment
현재 변경된 코드(git diff 기준)를 프로젝트 규칙에 맞게 리뷰합니다.
/review-code
체크 항목:
- API URL 네이밍 / HTTP 메서드 / 응답 코드
- Entity 설계 (
setXxx()사용 여부, Audit 필드, LAZY fetch 등) - Flyway 마이그레이션 파일 누락 여부
- 테스트 계층(Repository Mock 여부, DisplayName 등)
위반 사항은 파일명·라인 번호와 함께 지적해 줍니다.
새 프로젝트에서 가장 먼저 필요한 예외 처리가 미리 구성되어 있습니다.
throw new BusinessException(ErrorCode.RESOURCE_NOT_FOUND)
↓
GlobalExceptionHandler
↓
HTTP 404 { "code": "RESOURCE_NOT_FOUND", "message": "요청한 리소스를 찾을 수 없습니다." }
새 에러 코드 추가 방법: ErrorCode.java enum에 항목을 추가하기만 하면 됩니다.
DUPLICATE_EMAIL(HttpStatus.CONFLICT, "이미 사용 중인 이메일입니다."),ddl-auto: validate로 고정되어 있어, 스키마 변경은 반드시 Flyway SQL 파일로 관리합니다.
src/main/resources/db/migration/
├── V1__init.sql ← 이미 적용됨, 수정 금지
├── V2__add_users.sql ← 새 테이블 추가 시
└── V3__add_posts.sql ← 이어서 순번 증가
/new-api, /new-entity 커맨드를 사용하면 SQL 파일도 자동 생성됩니다.
.claude/rules/에 정의된 규칙은 Claude가 코드를 생성할 때 자동으로 참고합니다.
직접 읽어두면 커맨드 결과물을 예측하기 쉽습니다.
| 파일 | 내용 |
|---|---|
api-design.md |
URL kebab-case, DTO Record 사용, 응답 코드 기준, 페이지네이션 형식 |
db-schema.md |
엔티티 기본 패턴, Audit 필드, 연관관계 LAZY, Flyway 네이밍 규칙 |
testing.md |
Given-When-Then, @DisplayName 형식, 계층별 테스트 어노테이션 |
로컬은 H2 in-memory DB를 사용합니다. PostgreSQL로 전환하려면 application.properties를 수정하세요.
# H2 설정을 주석 처리하고 아래로 교체
spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.h2.console.enabled=false