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

들어가며 제가 속한 파트너셀프서비스팀은 코딩 컨벤션을 사내 위키 문서와 AI 에이전트가 참조할 수 있는 규칙 문서에 정의해놓고 개발하고 있습니다. 하지만 그 규칙을 잘 지키고 있는지 확인하는 방법이 코드 리뷰뿐이었다는 점이 문제였습니다. 문서에 있는 규칙은 팀원들이 의식적으로 인지해서 코드를 작성하거나 리뷰를 받는 과정에서 반영해야 했습니다. AI 에이전트를 이용해 규칙을 주입하더라도 세션별 컨텍스트에 따라 규칙을 위반하는 경우가 있었습니다. 저희 팀은 헥사고날 아키텍처를 실용적으로 변형한 형태로 사용하고 있습니다. 인바운드 포트(유스케이스 인터페이스)를 별도로 두지 않고 웹계층이 도메인(domain) 모듈의 서비스(*Service)를 직접 호출한다는 점에서 교과서적 헥사고날 아키텍처와는 조금 다릅니다. 대신 아웃포트(outport) 쪽 구조는 그대로 차용해서 외부 의존을 역전시켰습니다. 실제 구현은 아웃바운드 어댑터(infra·external)에 두고 아웃포트(outport)에 구현체를 제공하도록 했습니다. 외부 API와 캐시 연동이 많고 자주 바뀌는 팀 특성상 외부의 변화가 핵심 비즈니스 로직(domain)까지 번지지 않게 하기 위해서입니다. 덕분에 도메인은 외부 API와 독립적으로 유지되고, 테스트하기도 수월해집니다. 이 구조를 지키기 위한 팀 규칙은 .claude/rules/에 문서로 정리돼 있습니다. 아키텍처(레이어 의존) 규칙뿐 아니라 네이밍, 코딩 스타일, 테스트 코드, 예외, 로깅, 커밋 규칙 등 개발 전반의 컨벤션이 있습니다. 팀 내 규칙 파일 architecture.mdc 파일 예시 이 글은 아키텍처, 코딩 스타일 등의 팀 규칙을 아크유닛(ArchUnit)이라는 도구를 사용해 테스트 코드로 강제한 과정을 다룹니다. 아크유닛(ArchUnit)을 들어는 봤지만 직접 써본 적은 없는 분, "우리 팀에도 적용해볼까" 고민하는 분을 위한 글입니다. 특히 다음 다섯 가지 질문 위주로 작성했습니다. 적용하면 뭐가 좋나요? 어떻게 적용하나요? 시행착오는 없었나요? 적용 전/후 무엇이 달라졌나요? 주의사항은 없나요? 개발 환경: Java 11, Gradle 6.8, Spring Boot 2.4.5, Lombok 1.18.20, ArchUnit 1.3.0, JUnit 5.7.2 아크유닛(ArchUnit)으로 살아있는 규칙 만들기 1. 적용하면 좋은점 문서가 아닌 코드 레벨에서 규칙을 강제할 수 있습니다. 아키텍...