AI 코드, 이제 ArchUnit으로 아키텍처 규칙 위반을 즉시 잡아낸다!

본문에서는 AI가 생성한 코드의 아키텍처 규칙 위반 문제를 해결하기 위해 ArchUnit을 도입한 배경을 설명한다. 기존의 코드 리뷰 방식은 리뷰어의 부담을 가중시키고, 컨텍스트 기반 접근 방식은 강제력이 부족하다는 한계가 있었다. ArchUnit은 이러한 문제점을 해결하기 위해, 빌드 단계에서 아키텍처 규칙 위반을 자동 감지하고 AI가 스스로 수정하도록 유도하는 '시험지' 역할을 수행한다. 이는 AI가 규칙을 '알려주는' 방식에서 '어기면 안 되게 만드는' 방식으로의 전환을 의미한다. ArchUnit은 JUnit 테스트처럼 동작하며, 위반 시 명확한 에러 메시지를 제공하여 AI가 문제점을 파악하고 수정하도록 돕는다.

ArchUnit의 도입은 Gradle 의존성 추가만으로 간단하게 완료된다. 별도의 서버 구축이나 인프라 변경 없이 기존 테스트 프레임워크 위에서 동작하는 점이 특징이다. ArchUnit 테스트 코드는 사람이 자연어로 규칙을 설명하면 AI가 해당 규칙에 대응하는 코드를 생성하는 방식으로 구현된다. 즉, AI가 스스로 응시할 시험지를 AI가 만드는 구조이다. 이는 시험지를 한 번 만들면 이후 생성되는 모든 코드에 대해 일관된 검증을 수행할 수 있게 해준다. 이러한 구조는 AI와의 협업 효율성을 높이고, 아키텍처 품질을 지속적으로 유지하는 데 기여한다.

ArchUnit을 사용하면 레이어 의존성, 패키지 구조, 순환 의존성, API URL 형식 등 다양한 아키텍처 규칙을 코드 레벨에서 정의하고 자동 검증할 수 있다. 예를 들어, 레이어 간 의존성 규칙을 정의하여 Controller가 Repository를 직접 참조하는 것을 방지할 수 있다. 또한, 패키지 구조 규칙을 통해 Controller 클래스는 controller 패키지에, Service 클래스는 service 패키지에 위치하도록 강제할 수 있다. 순환 의존성 감지 규칙을 통해 패키지 간 순환 참조를 방지하고, API URL 형식을 검증하여 일관성을 유지한다. 도메인 순수성 보호 규칙을 통해 도메인 레이어가 외부 프레임워크에 의존하는 것을 막을 수 있다.

ArchUnit 도입 후 코드 리뷰의 질이 향상되고, 리뷰어는 비즈니스 로직 검토에 집중할 수 있게 되었다. AI가 생성한 코드의 아키텍처 위반을 자동 감지함으로써, 개발자는 AI 활용에 대한 심리적 안전망을 확보했다. 즉, AI가 규칙을 어겨도 테스트에서 잡히므로 안심하고 AI를 활용할 수 있게 된 것이다. 코드 리뷰 시간 감소와 더불어 AI 코드 품질 향상이라는 정량적 변화를 가져왔다. 팀원들은 ArchUnit을 통해 AI가 생성한 코드의 품질에 대한 신뢰를 얻게 되었고, AI를 활용한 개발 생산성을 더욱 높일 수 있게 되었다.

현재는 레이어 의존성과 패키지 구조와 같은 기본적인 규칙만 적용된 상태이며, 향후 도메인 이벤트 발행 규칙, DTO 변환 위치 규칙, 외부 라이브러리 사용 범위 제한 등 더 세밀한 아키텍처 규칙을 추가할 예정이다. 이는 AI와의 협업 품질을 더욱 향상시키는 데 기여할 것이다. 또한, 물류플랫폼팀 내 다른 프로젝트에도 동일한 ArchUnit 규칙 세트를 적용하여, 프로젝트 간 아키텍처 일관성을 유지할 계획이다. ArchUnit을 활용한 아키텍처 품질 관리는 AI 코드 생성 도구를 적극적으로 활용하면서도 아키텍처 품질을 유지하려는 팀에게 좋은 출발점이 될 수 있다.