문서로만 지키던 아키텍처 규칙, 테스트 코드로 강제하기 - 박공손

우아한형제들 파트너셀프서비스팀이 문서와 리뷰로 지키던 규칙을 실행 검사로 옮긴 사례다. 원문.

팀의 계약을 검사로 옮기기

팀이 선택한 레이어 의존·코딩 규칙을 ArchUnit 테스트와 CI에 연결했다. 기존 위반이 없는 규칙은 즉시 검사하고, 나머지는 위반 목록을 동결해 새로운 위반을 차단했다. 동결 목록은 Git으로 관리하고 기존 부채는 별도 개선 작업으로 줄였다. AI는 규칙의 테스트 변환·위반 분류·반복 수정에 활용했다.

바이트코드에 남지 않는 SOURCE 보존 어노테이션은 해당 관찰 방식으로 찾을 수 없어 Java 소스 검사로 보완했다. 저자는 구현한 검사에서 신규 위반 0건과 기존 부채 감소를 보고한다. 실행 결과는 독립 재현하지 않았다.

도입 조건과 보조 확인

구조 규칙은 이 팀의 변경 경계를 보호하는 계약이다. 동결 뒤의 부채 관리, 검사 범위와 유지 비용도 함께 고려해야 하며 단순한 프로젝트에서는 도입 비용이 효용보다 클 수 있다.

ArchUnit 공식 가이드 §8.6에서 기준선 저장·해소분 제거·재동결 동작을 추가 확인했다. 조회한 가이드는 1.5.0이며 원문 환경은 1.3.0이다. 현재 문서로 메커니즘을 대조했으며 원문 버전의 설정을 재현한 것은 아니다. 기준선 증가를 곧바로 우회로 단정하지 않고, 규칙·범위·형식 변경과 수용 결정을 구분하는 것은 이번 증류의 해석이다.

연결

• 규칙 전달과 실행 검사의 역할: 규칙을 다시 전달하는 것과 위반을 판정하는 것은 다르다
• 단계적 도입과 기존 부채: 규칙 검사를 점진적으로 도입할 때 기존 위반의 기준선을 관리한다
• 구조가 보호할 계약인 경우: 규칙은 소유한 가장 좁고 안정적인 공개 경계에서 깊게 테스트한다
• 변경을 제약하는 테스트와 함께 읽기: 테스트의 회귀 보호와 결함 탐색 - Yosef K