아키텍처 규칙 강제하기(feat MultiModule, ArchUnit, AI Agent)

com.example.project
    ├── controller
    ├── service
    ├── repository
    └── model

// ❌ 하나의 객체를 모든 곳에서 혼용
 
data class UserModel(
    val id: Long?,           // DB용? 응답용?
    val name: String?,       // nullable인지 아닌지 추적 불가
    @NotNull val email: String, // 어느 레이어에서 채워지는지 모름, nullable 하게 들어가야하는 곳도 있는데 라이브러리 어노테이션 제약으로 예외가 발생하는 케이스가 있었음.
    val password: String?,   // 응답에 노출되면 안 되는데...
    val createdAt: LocalDateTime?,
    ....
)
// Controller, Service, Repository 전부 UserModel 사용

// 1. HTTP 요청 전용 (Controller 진입점)
data class CreateUserRequest(
    @NotNull val name: String,
    @NotNull val email: String,
    @NotNull val password: String
)
 
// 2. Service 레이어 전달 전용 (Controller → Service)
data class CreateUserCommand(
    val name: String,
    val email: String,
    val encodedPassword: String   // Controller에서 인코딩 완료된 값
)
 
// 3. DB 저장 전용 (Service → Repository)
@Entity
data class UserEntity(
    @Id @GeneratedValue
    val id: Long = 0,
    val name: String,
    val email: String,
    val password: String,
    val createdAt: LocalDateTime = LocalDateTime.now()
)
 
// 4. HTTP 응답 전용 (민감 정보 제외)
data class CreateUserResponse(
    val id: Long,
    val name: String,
    val email: String
)

// CouponController.kt — 원래 의도된 사용처
@RestController
class CouponController(
    private val couponService: CouponService
) {
    @PostMapping("/coupons/issue")
    fun issueCoupon(@RequestBody request: IssueCouponRequest) {
        couponService.issueCoupon(request.userId, request.couponCode)
    }
}

// CouponService.kt
@Service
class CouponService(
    private val couponRepository: CouponRepository
) {
    fun issueCoupon(userId: Long, couponCode: String) {
        val coupon = couponRepository.findByCouponCode(couponCode)
            ?: throw IllegalArgumentException("존재하지 않는 쿠폰입니다.")
 
        check(!coupon.isExpired()) { "만료된 쿠폰입니다." }
        check(coupon.hasRemainingCount()) { "발급 가능 수량이 초과되었습니다." }
 
        coupon.issue(userId)
        couponRepository.save(coupon)
    }
}

// RegisterService.kt — 사전가입 완료 시 쿠폰 발급
@Service
class RegisterService(
    private val userRepository: UserRepository,
    private val couponService: CouponService  // 주입받기 시작
) {
    fun completePreRegistration(userId: Long) {
        // ...사전가입 처리 로직
        couponService.issueCoupon(userId, "PREREGISTER_2024")  // 호출
    }
}

// EventService.kt — 특정 이벤트 달성 시 쿠폰 발급
@Service
class EventService(
    private val eventRepository: EventRepository,
    private val couponService: CouponService  // 여기서도
) {
    fun completeEvent(userId: Long, eventId: Long) {
        // ...이벤트 달성 처리 로직
        couponService.issueCoupon(userId, "EVENT_REWARD_001")  // 여기서도 호출
    }
}

// CouponService.kt — 정책 변경: 등급 검증 추가
@Service
class CouponService(
    private val couponRepository: CouponRepository,
    private val userService: UserService  // 의존성 추가
) {
    fun issueCoupon(userId: Long, couponCode: String) {
        val coupon = couponRepository.findByCouponCode(couponCode)
            ?: throw IllegalArgumentException("존재하지 않는 쿠폰입니다.")
 
        // 신규 정책: 등급 검증 추가
        val user = userService.getUser(userId)
        check(user.grade.canUseCoupon(coupon.requiredGrade)) {
            "쿠폰 사용 가능한 등급이 아닙니다."
        }
 
        check(!coupon.isExpired()) { "만료된 쿠폰입니다." }
        check(coupon.hasRemainingCount()) { "발급 가능 수량이 초과되었습니다." }
 
        coupon.issue(userId)
        couponRepository.save(coupon)
    }
}

CouponService.issueCoupon() 변경 → 영향 범위
 
  CouponController  →  쿠폰 발급 API              ✅ 의도한 변경
  RegisterService   →  사전가입 완료 쿠폰 지급     🔴 의도치 않은 영향
  EventService      →  이벤트 달성 쿠폰 지급       🔴 의도치 않은 영향

// RewardHandler.kt — 보상 지급이라는 행위를 추상화
interface RewardHandler {
    fun issue(userId: Long, rewardCode: String)
}

// CouponRewardHandler.kt — 쿠폰 발급 구현체
@Component
class CouponRewardHandler(
    private val couponRepository: CouponRepository
) : RewardHandler {
    override fun issue(userId: Long, rewardCode: String) {
        val coupon = couponRepository.findByCouponCode(rewardCode)
            ?: throw IllegalArgumentException("존재하지 않는 쿠폰입니다.")
 
        check(!coupon.isExpired()) { "만료된 쿠폰입니다." }
        check(coupon.hasRemainingCount()) { "발급 가능 수량이 초과되었습니다." }
 
        coupon.issue(userId)
        couponRepository.save(coupon)
    }
}

// EventService.kt — 이제 CouponService를 직접 알지 않아도 된다
@Service
class EventService(
    private val eventRepository: EventRepository,
    private val rewardHandler: RewardHandler  // 추상화에만 의존
) {
    fun completeEvent(userId: Long, eventId: Long) {
        // ...이벤트 달성 처리 로직
        rewardHandler.issue(userId, "EVENT_REWARD_001")
    }
}

// 각 모듈별로 의존하고 있는 모듈을 지정해줍니다.(의존 방향 강제)
... 생략
// controller
dependencies {
    implementation("yjh.ontongsal:service")
}
 
// service
dependencies {
    implementation("yjh.ontongsal:repository")
    implementation("yjh.ontongsal:domain")
}

// 실제 빌드할때 의존 관계에 따라 빌드 모듈을 지정해줄 수 있습니다.
// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}
 
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") { from(files("../app/gradle/libs.versions.toml")) }
    }
}
 
rootProject.name = "service"
 
includeBuild("../repository")
includeBuild("../domain")

testImplementation("com.tngtech.archunit:archunit-junit5:1.4.1")

import com.tngtech.archunit.core.importer.ImportOption
import com.tngtech.archunit.junit.AnalyzeClasses
import com.tngtech.archunit.junit.ArchTest
import com.tngtech.archunit.lang.ArchRule
import com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes
import com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses
 
@AnalyzeClasses(
    packages = ["yjh.ontongsal.restapi"],
    importOptions = [ImportOption.DoNotIncludeTests::class],
)
class ArchitectureTest {
 
    @ArchTest
    val domainHasNoApplicationDependency: ArchRule =
        noClasses()
            .that().resideInAPackage("..service..")
            .should().dependOnClassesThat()
            .resideInAPackage("..controller..")
            .`as`("서비스 계층은 컨트롤러 계층에 의존하지 않아야 한다")
}

// CLAUDE.md 아키텍처 규칙 작성 예시
# 아키텍처 규칙
 
## 레이어 의존 방향 (반드시 준수)
Controller → Service → Repository 단방향만 허용
 
## 금지 패턴
- Controller에서 Repository 직접 참조 금지
- Service에서 다른 Service 직접 주입 금지
- 공통 비즈니스 로직은 UseCase 또는 Handler로 분리
 
## DTO 분리 원칙
- HTTP 요청/응답: XxxRequest, XxxResponse (controller 패키지)
- 레이어 간 전달: XxxCommand, XxxResult (service 패키지)
- DB 전용: XxxEntity (repository 패키지)
- 하나의 객체를 여러 레이어에서 혼용하지 않는다
 
## 코드 생성 시 체크리스트
1. 새 클래스를 만들기 전에 UseCase 인터페이스를 먼저 확인할 것
2. 의존 방향이 위 규칙을 따르는지 확인할 것
3. DTO가 레이어 경계를 넘어가고 있지 않은지 확인할 것

// UseCase 인터페이스 + 테스트 코드가 AI 컨텍스트로 작동하는 예시
// ArticleUseCase.kt — AI가 "무엇을 할 수 있는가"를 파악하는 명세
interface ArticleUseCase {
    fun write(actor: Actor, boardId: TargetId, title: ArticleTitle, content: ArticleContent): Long
    fun update(actor: Actor, articleId: TargetId, title: ArticleTitle, content: ArticleContent): Long
    fun delete(actor: Actor, articleId: TargetId)
 
    fun findArticle(articleId: TargetId): Article
    fun findAll(targetId: TargetId, page: Int, pageSize: Int): Page<Article>
    fun findAllInfiniteScroll(targetId: TargetId, lastArticleId: Long?, pageSize: Int): Slice<Article>
}
 
// ArticleUseCaseTest.kt — 명세가 곧 AI의 구현 범위이자 경계
class ArticleUseCaseTest {
 
    @Test
    fun `게시글 작성 - 정상 작성`() {
        // given
        val actor = Actor(userId = 1L)
        val boardId = TargetId(10L)
        val title = ArticleTitle("첫 번째 게시글")
        val content = ArticleContent("내용입니다.")
 
        // when
        val articleId = articleUseCase.write(actor, boardId, title, content)
 
        // then
        assertThat(articleId).isPositive()
    }
 
    @Test
    fun `게시글 수정 - 작성자가 아니면 예외`() {
        val actor = Actor(userId = 999L)  // 작성자가 아닌 사용자
        val articleId = TargetId(1L)
 
        assertThrows<AccessDeniedException> {
            articleUseCase.update(actor, articleId, ArticleTitle("수정"), ArticleContent("수정 내용"))
        }
    }
 
    @Test
    fun `게시글 목록 조회 - 페이지네이션`() {
        val targetId = TargetId(10L)
 
        val result = articleUseCase.findAll(targetId, page = 0, pageSize = 20)
 
        assertThat(result.content).hasSizeLessThanOrEqualTo(20)
    }
 
    @Test
    fun `게시글 무한스크롤 - lastArticleId 이후 항목만 반환`() {
        val targetId = TargetId(10L)
        val lastArticleId = 50L
 
        val result = articleUseCase.findAllInfiniteScroll(targetId, lastArticleId, pageSize = 10)
 
        assertThat(result.content).allMatch { it.id < lastArticleId }
    }
}

// SKILL/COMMAND 파일 예시
# SKILL: validate-architecture
 
## 실행 조건
코드 변경이 발생했을 때 자동 실행
 
## 수행할 검증 항목
 
### 1. UseCase 변경 감지
- UseCase 인터페이스가 변경된 경우
  → 구현체(ServiceImpl)가 인터페이스를 올바르게 구현하는지 확인
  → 관련 테스트 코드가 존재하는지 확인
 
### 2. 의존 방향 검증
변경된 파일에서 아래 패턴을 탐지하면 경고:
- controller 패키지에서 repository 패키지 import
- service 클래스에서 다른 service 클래스를 생성자 주입
- XxxRequest / XxxResponse 객체가 service 패키지 내부에 존재
 
### 3. 위반 감지 시 출력 형식
[ARCHITECTURE VIOLATION]
파일: {파일명}
위반 규칙: {규칙명}
위반 내용: {구체적인 위반 내용}
권장 수정: {수정 방향 제안}

#!/bin/sh
# .git/hooks/pre-commit
 
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "UseCase.kt$")
 
if [ -n "$CHANGED_FILES" ]; then
  echo "UseCase 변경 감지 → SKILL 파일 자동 업데이트"
 
  for file in $CHANGED_FILES; do
    echo "처리 중: $file"
 
    # UseCase 인터페이스에서 메서드 목록 추출
    METHODS=$(grep -E "fun [a-zA-Z]+" "$file" | sed 's/.*fun //' | sed 's/(.*//')
 
    # SKILL 파일 업데이트
    SKILL_FILE=".claude/skills/validate-architecture.md"
    {
      echo "# 자동 생성: $(date)"
      echo "## 검증 대상 UseCase: $file"
      echo "## 정의된 메서드"
      echo "$METHODS" | while read -r method; do
        echo "  - $method"
      done
    } >> "$SKILL_FILE"
 
    git add "$SKILL_FILE"
  done
 
  echo "SKILL 파일 업데이트 완료"
fi