문서로만 지키던 아키텍처 규칙, 테스트 코드로 강제하기
Summary
“그거 컨벤션 위반인데요?” 잔소리 대신 ‘테스트 코드’로 아키텍처 강제하기
말뿐인 아키텍처 문서는 가라! ArchUnit과 CI로 신규 위반 0건을 달성한 우아한형제들의 실전 전환기
아무리 꼼꼼히 문서를 작성하고 코드 리뷰를 해도 아키텍처 규칙은 조금씩 깨지기 마련입니다. 우아한형제들 파트너셀프서비스팀은 이러한 소모적인 컨벤션 논쟁과 아키텍처 붕괴를 막기 위해 아크유닛(ArchUnit)을 전격 도입했습니다. 기존의 거대한 레거시 부채는 동결하고 신규 위반부터 완벽히 차단하며 점진적으로 코드 품질을 끌어올린 여정을 소개합니다.
- 01코드 리뷰의 한계를 극복하고 아키텍처 규칙을 빌드 단계에서 자동으로 강제하는 자동화 체계 구축
- 02수천 건의 기존 규칙 위반을 감당할 수 있게 해준 아크유닛의 FreezingArchRule 실전 활용법
- 03Lombok 등 바이트코드에 남지 않는 소스 레벨 어노테이션을 탐지하기 위한 커스텀 소스 스캐닝 구현
- 04AI 에이전트(Claude)를 활용한 대규모 반복 규칙 이관 및 테스트 생성 공수 획기적 단축
- 05실제 적용 후 @Builder 오용 등 기존 기술 부채를 최대 99%까지 청소해낸 놀라운 정량적 결과
RECOMMENDATION
규칙을 담은 사내 문서가 레거시화되어 가고 있거나, 코드 리뷰 시간의 절반 이상을 사소한 컨벤션 지적에 낭비하고 있는 다중 모듈 아키텍처 기반의 백엔드 팀에게 적극 권장합니다. 소규모 단일 모듈 프로젝트라면 도입 비용 대비 효용이 적을 수 있으므로 신중히 고려하세요.
The Problem
기존에는 아키텍처 규칙과 코딩 컨벤션을 사내 위키 등의 문서에만 정의해 두어, 코드 리뷰 과정에서 누락되거나 신규 팀원의 온보딩 시 위반 사항이 누적되는 등의 문제가 있었습니다. 또한, 리뷰어가 동일한 컨벤션 지적을 반복하게 되면서 코드 리뷰의 효율성이 저하되었습니다.
The Solution
자바 아키텍처 테스트 도구인 아크유닛(ArchUnit)을 별도 모듈로 분리 도입하고, CI 파이프라인과 연동하여 규칙 위반 시 머지가 불가능하도록 강제했습니다. 기존 대규모 레거시 위반 코드는 FreezingArchRule 기능을 통해 동결 예외 처리하여 신규 위반만 차단했으며, 바이트코드 분석이 어려운 Lombok 소스 코드는 자체적인 소스 스캔 방식으로 보완했습니다.
The Result
새로운 규칙 위반 건수가 0건으로 유지되기 시작했으며, 동결된 기존 기술 부채 중 @Builder 사용 규칙 위반은 99%(823건에서 10건으로), 웹에서 아웃포트 직접 의존 위반은 14%(4,447건에서 3,813건으로) 감소하는 정량적 개선 성과를 거두었습니다.
Trade-off
Lombok과 같은 소스 레벨 어노테이션(@Retention(SOURCE))은 아크유닛이 분석하는 바이트코드에 남지 않아 별도의 소스 스캔 검사 로직을 추가로 구현해야 했습니다. 또한, FreezingArchRule로 동결한 부채를 실질적으로 해결하기 위한 일정을 병행 관리하지 않으면 단순히 기술 부채를 방치하는 부작용이 생길 수 있으며, 규칙 증가에 따른 테스트 유지보수 비용도 증가합니다.
Key Concepts
More from 우아한형제들
View all posts from 우아한형제들한꺼번에 짊어지던 배치를 내려놓고, 하나씩 흘려보내는 워크플로로
Kotlin CoroutineTemporalMongoDB21시간 전AI에게 만드는 법 대신 실패하는 법을 묻다: 포토그래퍼의 수천 명 동시 접속 게임 만들기
Server-Sent EventsRedis PubSubKubernetes1주 전옆 팀은 AI를 어떻게 쓸까? 첫 사내 기술 콘퍼런스 우아한테크데이
Developer RelationsKnowledge SharingAI Transformation2주 전기술블로그 세 번째 책 《요즘 우아한 백엔드 개발》 출간
KotlinApache KafkaElasticsearch1개월 전배포 없이 앱과 로컬 웹을 잇다
ProxyTunnelingWebSocket1개월 전
