안녕하세요. 백엔드 개발자 최혜미입니다.
오늘 소개해드릴 업무 자동화 시리즈 세 번째 주제는
커밋 전 코드 컨벤션 위반을 자동으로 검사하고, 위반 시 커밋을 차단하는 시스템입니다.
얼마 전 진행 중인 프로젝트에 백엔드 팀원분이 새로 합류하면서 코드 컨벤션 유지에 대한 고민이 생겼습니다.
온보딩은 했지만, 익숙하지 않은 규칙들을 바쁜 일정 속에서 매번 챙기긴 어려웠는지 자주 누락이 발생했습니다.
저희 팀에는 응답값 포맷 통일, 커스텀 예외 사용, 문서화 규칙은 물론
기본적인 줄 정렬이나 엔드포인트 규격 같은 컨벤션도 포함되어 있습니다.
개인적으로 이런 기본적인 컨벤션을 지키는 것부터가 코드 품질의 시작이라고 생각하기 때문에 코드 컨벤션에 아주 예민한 편입니다.
그렇다 보니 코드 리뷰마다 컨벤션 관련 피드백이 반복됐고,
정작 중요한 설계나 비즈니스 로직 논의에는 집중하기 어려운 경우도 종종 생겼습니다.
또한 컨벤션이 지켜지지 않다 보니
프론트엔드 쪽에서 응답 포맷 수정 요청이 계속 들어오고,
이후 다시 수정하는 작업이 반복되며 전반적으로 비효율적이라는 느낌을 받았습니다.
그렇다고 매번 제가 직접 지적하기에는
같은 팀원 입장에서 조심스러운 부분도 있어 참 곤란하더라고요.
그러다 이런 생각이 들었습니다.
“아, 나 대신 마음 편하게 컨벤션 지적해줄 사람이 있었으면 좋겠다...”
저는 실행력 하나는 최고이기에 바로 이 아이디어로 개발에 착수했습니다
어떻게 구성해야 가장 효율적일까?
-
처음엔 AI 기반 코드 리뷰를 떠올렸습니다.
변경된 코드를 AI가 읽고 피드백을 주는 방식이죠.
그런데 알아보니 이미 잘 되어 있는 코드 품질 검사 툴들이 충분히 있었고
굳이 AI까지 도입하기엔 리소스 대비 효과가 크지 않다고 판단해 제외했습니다. -
Lint 도입도 고려했지만, 직접 적용해본 결과 기준이 너무 엄격했습니다.
코드 품질은 올라갈 수 있지만 그만큼 팀원 피로도도 커지더라고요.
좋은 도구라도 사용에 부담이 된다면 결국 유지되지 않습니다.
그래서 여러 기준을 테스트해본 끝에
꼭 지켜야 할 핵심 컨벤션만 검사하는 게 가장 효율적이라는 결론에 도달했습니다.
현재는 팀원들의 피드백을 반영하면서 조금씩 조정해 나가고 있으며
다행히 지금 설정된 수준은 과하지도, 느슨하지도 않게 잘 동작하고 있습니다.
시스템 구성 및 동작 흐름
이 자동화 시스템은 커밋 직전에 코드 컨벤션을 검사하고,
위반이 감지되면 커밋을 차단하는 구조로 되어 있습니다.
검사를 수행하는 컨벤션 기준은 꼭 필요한 항목만 선별했습니다.
지나치게 엄격하면 오히려 유지가 어렵기 때문에, 꼭 필요한 수준에서 마지노선을 설정했습니다.
현재 적용된 주요 규칙은 다음과 같습니다.
- Controller 반환 타입: 응답 구조 통일을 위해 지정된 포맷만 허용
- Swagger 문서화: 모든 API는 @Operation, DTO는 @Schema 필수
- Exception 구조: 에러 처리/로깅 일관화를 위해 커스텀 예외 상속
- URL 구조: 모든 API는 지정된 버전 접두 사용
- 코드 스타일: 임포트/공백/개행 자동 정리
💡 이 규칙들은 필요 시 팀 상황에 맞춰 점진적으로 수정하고 있습니다.
위의 검사를 통해 코드가 컨벤션을 지키지 않을 경우, 커밋 자체가 안 되도록 막아줍니다.
전체 구조는 아래와 같습니다.
개발자가 코드 작성 → git add → git commit
│
└─ pre-commit 훅 실행
├─ 변경된 Java 파일 추출
├─ Spotless로 포맷 검사
├─ ArchUnit으로 규칙 검사
└─ 통과 시 커밋 완료 / 실패 시 차단
- Git pre-commit 훅을 활용하여, 커밋 직전에 자동 검사 실행
- Spotless: 코드 포맷을 정리해주는 도구입니다.
커밋 전에 들여쓰기, 임포트, 공백 같은 스타일 문제를 자동으로 정리해줍니다. - ArchUnit: 아키텍처 규칙을 코드로 강제할 수 있는 테스트 라이브러리입니다.
특정 애노테이션, 패키지 구조, 상속 여부 등 컨벤션 위반을 검사할 수 있습니다.
두 도구 모두 변경된 파일만 타깃으로 검사하도록 구성되어 있어, 커밋 속도에도 부담이 없습니다.
실제로 대부분의 커밋은 몇 초 내로 검사를 마치고 통과합니다.
실패 시에는 콘솔에 구체적인 오류 원인이 출력됩니다!
자동 수정 가능한 항목은 별도 명령어 안내도 함께 표시된답니다!
도입 후기
처음에는 “이렇게 까지 해야 하나?” 싶은 걱정도 있었습니다.
하지만 도입 이후 팀원들의 반응은 의외로 긍정적이었어요!
무엇보다 좋았던 점은
사람이 일일이 지적하지 않아도 된다는 것이었습니다!
같은 팀원끼리 컨벤션을 지적하는 건 생각보다 에너지가 많이 드는 일인데
이 시스템 하나로 그 스트레스가 확실히 줄었습니다.
덕분에 진짜 하고 싶은 개발에 더 집중할 수 있었고
컨벤션이 자연스럽게 온보딩되는 효과도 덤으로 따라왔습니다. 😊
이 작업을 하면서 가장 크게 느낀 점은 한 문장으로 정리할 수 있습니다.
“컨벤션은 말이 아니라, 시스템으로 강제하는 게 가장 효율적이다.”
앞으로도 팀 상황에 맞춰 규칙은 계속 조정될 수 있겠지만
사람이 직접 지적하지 않아도 기준이 지켜지는 환경을 만들어가는 것이 제 목표입니다.
다음에는 또 어떤 자동화를 만들고, 어떤 불편함을 줄여나갈지
벌써부터 기대가 됩니다!
다음 글에서도 더 나은 개발 환경 이야기를 가지고 찾아오겠습니다.
감사합니다.
