회사 코드를 바꿔보자 - 2

까다로운 개발자들을 설득해보자

3 Layered Architecture 도입과 팀원 설득 과정

문제(https://jaemoon.tistory.com/316)를 해결하기 위해 구조적인 접근이 필요하다고 판단했다. 그래서 선택한 것이 '무늬만 3 Layered Architecture'로 되어 있는 현재 코드를 실제로 Controller – Service – Repository 구조로 명확히 분리하는 일이었습니다.

현 회사에서 Express 프레임워크를 사용하고 있습니다. Express의 장점과 단점은 단 하나로 귀결됩니다.

• 장점은 자유도가 높습니다.
• 단점도 자유도가 높습니다.

개발자 각자의 스타일에 따라 자유롭게 코드를 작성할 수 있었습니다. 그렇기 때문에 회사 내에서는 일관된 규칙 없이 다양한 책임과 역할이 있는 코드가 뒤섞인 상태가 되었습니다.

프레임워크 도입에 대한 고민

팀장직을 맡았을 때, NestJS 도입을 고려했습니다. Nest는 프레임워크 자체적으로 명확한 규칙과 구조를 강제하고, 학습만 된다면 훨씬 더 체계적인 코드 작성을 유도할 수 있었기 때문입니다. 그러나 팀에는 저를 포함한 5명의 개발자가 있었고, Nest에 대해 충분히 이해하고 있는 구성원은 없었습니다. 심지어 팀장인 저 조차도 Nest의 설계 철학이나 상황별 코드 구조에 대해 완벽히 확신하지 못한 상태였다.

게다가 갑작스러운 프레임워크의 변경은 팀원들에게 불필요한 혼란과 심리적 저항감을 불러올 수 있었습니다. 그래서 Express를 그대로 유지하면서 Nest의 구조적인 장점을 가져오는 방식으로 방향을 바꾸었다. (추가적으로 성공적으로 코드를 변경했다면 Nest로의 마이그레이션까지 생각하고 있고, 현재 2025.06.10~ 진행중입니다.)

우선, 기존의 무질서한 코드에 논리적 계층 구조를 도입하기 위해, Controller – Service – Repository 구조를 따르기로 했다. Nest에서는 Router와 Controller가 하나의 파일에 작성되지만, Express에서는 Router를 별도 파일로 분리하는 것이 더 가독성이 좋았기 때문에 Router까지 포함한 총 4개의 파일 구조를 정립했다. 이렇게 책임과 역할을 명확히 분리하는 방향으로 팀의 코딩 규칙을 정립하고자 했습니다.

팀원 설득 과정

하지만 문제는 설득이었습니다. 저는 팀장이라는 직책을 갖고 있었지만 팀에서 가장 연차가 낮았고, 나이도 가장 어렸습니다. 이전 코드들이 다소 복잡하긴 했지만, 기능적으로 문제없이 동작하고 있었기 때문에 "왜 굳이 바꿔야 하느냐"는 의문을 가진 팀원들도 있었습니다. 그리고 그 의문은 충분히 타당했습니다. 실제 서비스 사용자는 소스 코드를 보지 않으며, 눈에 보이는 문제가 없었기 때문이다. 우리만 눈 감으면 되는 일이었다.

그래서 단순히 '구조가 깔끔해서', 'Nest처럼 보여서' 라는 피상적인 이유로는 설득할 수 없었다. 저는 실제로 1인 프로젝트를 진행하면서 겪었던 문제를 근거로 논리적으로 설득을 시도했다.

내가 제시한 문제 인식과 해결 논리

• DRY (Don’t Repeat Yourself)
  • 코드 중복이 심각하다. 동일한 기능을 수행하는 코드가 여러 곳에 흩어져 있고, 이로 인해 오류의 가능성과 유지 비용이 증가한다.
• 유지보수의 어려움
  • 중복된 코드들 속에서 필요한 함수를 찾아 복사 붙여넣기를 하고, 조금씩 수정하면서 생기는 오류가 많다.
• 디버깅 시간 증가
  • 동일한 코드가 여러 곳에 존재하므로, 어느 부분이 문제인지 원인을 분석하기 위한 시간이 지나치게 오래 걸린다.
  • 또한, 하나의 코드에서 발생한 문제를 동일하고 비슷한 코드를 찾아 전부 변경을 해줘야 한다.
• 가독성 저하
  • 하나의 파일에 수많은 기능이 섞여 있다. 신규 입사자가 코드를 이해하고 적응하기에 지나치게 가파른 진입 장벽이 존재한다.
• 결합도 문제
  • 하나의 함수가 변경되면 전체 기능에 영향을 미친다. 이제부터는 단일 책임 원칙(SRP)에 따라, 의존성을 최소화한 구조로 리팩토링하자. (Layer별로 보았을 때의 단일 책임 원칙)

이러한 논리적인 근거를 바탕으로 설명했을 때, 팀원들도 대부분 비슷한 불편을 경험해봤기 때문에 큰 반대 없이 내 제안을 수용해주었다. 결국 우리는 Express 기반을 유지하면서도, 내부적으로는 Nest의 구조적 장점을 흡수한 3 Layered Architecture를 도입하는 데 성공할 수 있었다.

 

회사 코드 문화를 바꾸었다 - 완

 

회사 코드를 바꿔보자 - 3

 

회사 코드를 바꿔보자 - 1