AI 생성 코드의 아키텍처 규칙 위반을 빌드에서 차단

요약

Claude가 생성한 코드에서 Repository가 Controller를 직접 참조하는 등 아키텍처 규칙 위반이 반복되었습니다. Skill이나 컨텍스트에 규칙을 적어줘도 복잡한 기능 구현 시 빠뜨리는 경우가 있었고, 코드 리뷰로 잡으려면 리뷰어 부담이 커졌습니다. ArchUnit으로 위반 시 테스트를 실패시키고 AI가 에러 메시지를 읽어 스스로 수정하는 구조를 만든 과정에 대한 글입니다.

인사이트

• 컨텍스트에 규칙을 적어주는 것은 "참고 자료"일 뿐 강제력이 없음 — AI는 읽고 이해하지만 매번 정확하게 수행하지는 않음
• ArchUnit은 JUnit 테스트로 동작하여 위반 시 구체적인 에러 메시지를 출력 — Claude는 이 메시지를 읽고 위반 원인을 이해한 뒤 올바른 패턴으로 코드를 재구성함
• 시험지 자체도 AI가 작성 가능 — 자연어로 규칙을 설명하면 ArchUnit 테스트 코드를 생성하고, 이후 생성되는 모든 코드에 일관된 검증을 수행

해결

1. Gradle 의존성 1줄로 도입

• archunit-junit5:1.3.0 추가, 별도 서버나 인프라 변경 불필요

2. 적용한 규칙 5종

• 레이어 의존성: layeredArchitecture()로 Controller→Service→Repository 방향만 허용, 모듈 간 api/exception 패키지만 접근 허용
• 패키지 구조: *Controller는 ..controller.. 패키지에, *Service는 ..service..에 위치 강제
• 순환 의존성: slices().matching(...).should().beFreeOfCycles() — 3줄로 프로젝트 전체 순환 참조 감지
• 도메인 순수성: domain 패키지 클래스는 java/kotlin/slf4j만 의존 가능 — Spring @Component, JPA 어노테이션 침투 차단
• 네이밍 일관성: @Service는 *Service 클래스에만, @Transactional(readOnly=true) 클래스는 *ReadService/*SearchService 네이밍 강제

3. AI 연동 루프

• Claude가 코드 생성 → 테스트 실행 → ArchUnit 위반 감지 → Claude가 에러 메시지를 읽고 수정 → 테스트 통과, 사람 개입 없음

결과

코드 리뷰에서 아키텍처 검증에 쏟는 시간이 사라졌고, 리뷰어는 비즈니스 로직에만 집중할 수 있게 되었습니다.