Spring Standards - Coding Conventions
Spring Boot 3.5.x + Java 21 헥사고날 아키텍처 엔터프라이즈 표준
프로젝트 소개
14개 전문 Claude Skills와 146개 코딩 컨벤션 문서가 일관된 고품질 코드 생성을 보장하는 엔터프라이즈 표준 프로젝트입니다.
핵심 철학
| 원칙 | 설명 |
|---|---|
| Documentation-Driven | 146개 코딩 컨벤션 문서가 설계를 강제 |
| Smart Strategy | 기존 코드 수정 → TDD, 신규 코드 생성 → Doc-Driven |
| Zero-Tolerance | Lombok 금지, Law of Demeter, Long FK 전략 |
| AI-First | Claude Code + Serena MCP + 14개 전문 Skills |
문서 통계
| 레이어 | 파일 수 | 주요 내용 |
|---|---|---|
| 00-project-setup | 5 | 멀티모듈, Gradle, GitHub Workflows, Terraform |
| 01-adapter-in-layer | 27 | REST API, Controller, DTO, Error, OpenAPI, Security |
| 02-domain-layer | 14 | Aggregate, VO, Event, Exception |
| 03-application-layer | 51 | Assembler, DTO, Event, Facade, Factory, Manager, Port, Service, Scheduler |
| 04-persistence-layer | 41 | MySQL (Adapter, Entity, Mapper, Repository), Redis (Cache, Lock) |
| 05-testing | 3 | Integration Testing, Test Fixtures |
| 06-observability | 4 | Logging, ADOT, CloudWatch |
| 07-local-development | 1 | 로컬 개발 환경 |
| 총계 | 146 | README 제외 |
레이어별 가이드
🏗️ 00. Project Setup
프로젝트 구조 및 인프라 설정
| 문서 | 설명 |
|---|---|
| 멀티모듈 구조 | 헥사고날 멀티모듈 구조 및 의존성 규칙 |
| Gradle 설정 | Gradle 빌드 설정 가이드 |
| GitHub Workflows | CI/CD 워크플로우 설정 |
| 버전 관리 | gradle.properties 버전 관리 |
| Terraform | AWS 인프라 Wrapper Module 패턴 |
🌐 01. Adapter-In Layer (REST API)
HTTP 요청/응답 처리 → UseCase 위임
핵심 원칙: Thin Controller, Pure Java, Bean Validation 필수, RESTful 설계
| 컴포넌트 | 가이드 | 테스트 | ArchUnit |
|---|---|---|---|
| REST API 요약 | 가이드 | - | - |
| Controller | 가이드 | 테스트 | ArchUnit |
| DTO - Command | 가이드 | 테스트 | ArchUnit |
| DTO - Query | 가이드 | 테스트 | ArchUnit |
| DTO - Response | 가이드 | 테스트 | ArchUnit |
| Error Handling | 가이드 | 테스트 | ArchUnit |
| Mapper | 가이드 | 테스트 | ArchUnit |
| OpenAPI | 가이드 | - | ArchUnit |
| Security | 가이드 | 테스트 | ArchUnit |
🎯 02. Domain Layer
순수 비즈니스 로직 (기술 독립적)
핵심 원칙: Pure Java (Lombok 절대 금지), Law of Demeter 엄수, Aggregate 중심 설계, 불변성 우선
| 컴포넌트 | 가이드 | 테스트 | ArchUnit |
|---|---|---|---|
| Domain 요약 | 가이드 | - | - |
| Aggregate | 가이드 | 테스트 | ArchUnit |
| Value Object | 가이드 | 테스트 | ArchUnit |
| Query VO | 가이드 | - | - |
| LockKey | - | - | ArchUnit |
| Domain Event | 가이드 | - | ArchUnit |
| Exception | 가이드 | 테스트 | ArchUnit |
🔧 03. Application Layer
UseCase + Transaction 관리
핵심 원칙: UseCase = 단일 비즈니스 트랜잭션, Transaction 경계 엄격, CQRS 분리 고정, Port/Adapter 패턴
| 컴포넌트 | 가이드 | 테스트 | ArchUnit |
|---|---|---|---|
| Application 요약 | 가이드 | - | - |
| Assembler | 가이드 | 테스트 | ArchUnit |
| Command Facade | 가이드 | 테스트 | ArchUnit |
| Query Facade | 가이드 | - | - |
| Command Factory | 가이드 | 테스트 | ArchUnit |
| Query Factory | 가이드 | 테스트 | ArchUnit |
| Transaction Manager | 가이드 | 테스트 | ArchUnit |
| Read Manager | 가이드 | - | - |
| Command Service | 가이드 | 테스트 | ArchUnit |
| Query Service | 가이드 | 테스트 | ArchUnit |
| Event Listener | 가이드 | 테스트 | ArchUnit |
| Scheduler | 가이드 | 테스트 | ArchUnit |
💾 04. Persistence Layer
저장소 (Database) 연동
핵심 원칙: 어댑터 = 비즈니스 로직 금지, CQRS 분리 (Command=JPA, Query=QueryDSL), 엔티티 연관관계 금지 (Long FK)
MySQL (JPA/QueryDSL)
| 컴포넌트 | 가이드 | 테스트 | ArchUnit |
|---|---|---|---|
| Command Adapter | 가이드 | 테스트 | ArchUnit |
| Query Adapter | 가이드 | 테스트 | ArchUnit |
| Lock Query Adapter | 가이드 | 테스트 | ArchUnit |
| Entity | 가이드 | 테스트 | ArchUnit |
| Mapper | 가이드 | 테스트 | ArchUnit |
| JPA Repository | 가이드 | - | ArchUnit |
| QueryDSL Repository | 가이드 | 테스트 | ArchUnit |
Redis (Cache & Lock)
| 컴포넌트 | 가이드 | 테스트 | ArchUnit |
|---|---|---|---|
| Redis 요약 | 가이드 | - | - |
| Cache Adapter | 가이드 | 테스트 | ArchUnit |
| Distributed Lock | 가이드 | - | - |
| Lock Adapter | 가이드 | 테스트 | ArchUnit |
🧪 05. Testing
테스트 전략 및 Test Fixtures
| 컴포넌트 | 가이드 | ArchUnit |
|---|---|---|
| 통합 테스트 | 가이드 | - |
| Test Fixtures | 가이드 | ArchUnit |
📊 06. Observability
모니터링, 로깅, 추적
| 컴포넌트 | 가이드 |
|---|---|
| Observability 요약 | 가이드 |
| Logging 설정 | 가이드 |
| ADOT 연동 | 가이드 |
| CloudWatch 연동 | 가이드 |
🖥️ 07. Local Development
로컬 개발 환경 설정
| 컴포넌트 | 가이드 |
|---|---|
| 로컬 개발 환경 | 가이드 |
Zero-Tolerance 규칙
절대 위반 불가 규칙:
| 번호 | 규칙 | 적용 레이어 | 이유 |
|---|---|---|---|
| 1 | Lombok 전면 금지 | 전체 | 명시적 코드, 디버깅 용이성 |
| 2 | Law of Demeter | Domain | 캡슐화, 결합도 감소 |
| 3 | Long FK 전략 | Persistence | N+1 회피, 성능 최적화 |
| 4 | Transaction 경계 | Application | 외부 API 호출 격리 |
| 5 | Spring Proxy 제약 | Application | @Transactional 정상 작동 보장 |
| 6 | CQRS 분리 | Application | Command/Query 완전 분리 |
Claude Skills (14개)
프로젝트에 특화된 14개 전문 Skills:
| 카테고리 | Skill | 역할 |
|---|---|---|
| Planning | requirements-analyst |
추상적 요구사항 → 구체적 비즈니스 규칙 |
| Planning | layer-architect |
영향도 분석, TDD vs Doc-Driven 결정 |
| Domain | domain-expert |
Aggregate, VO, Event, Exception 설계 |
| Application | usecase-expert |
Port-In 인터페이스, UseCase/Service 구현 |
| Application | transaction-expert |
TransactionManager, ReadManager, Facade |
| Application | factory-assembler-expert |
CommandFactory, QueryAssembler, Bundle |
| Persistence | entity-mapper-expert |
JPA Entity, EntityMapper (Long FK) |
| Persistence | repository-expert |
JpaRepository, QueryDslRepository |
| Persistence | adapter-expert |
CommandAdapter, QueryAdapter, LockAdapter |
| Persistence | redis-expert |
Lettuce 캐시 + Redisson 분산락 |
| REST API | controller-expert |
REST Controller, Command/Query DTO |
| Cross-Cutting | testing-expert |
Integration Test, TestRestTemplate |
| Cross-Cutting | project-setup-expert |
Multi-module 구조, Gradle |
| Cross-Cutting | devops-expert |
GitHub Actions, Terraform, Docker |
링크
- GitHub Repository: ryu-qqq/claude-spring-standards
- Main README: README.md
- 전체 코딩 컨벤션: coding_convention/README.md
Last Updated: 2025-12-05 Version: 3.0