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

기술 스택 개편 코드 문화 변화 그리고 팀과 함께한 변화

팀에서 진행한 프로젝트의 기술 스택을 개선하면서 겪은 고민과 변화의 기록입니다. 단순한 마이그레이션이 아니라, 기술을 선택하는 기준, 팀원 설득 과정, 리팩토링 단계별 전략까지 모두 포함된 여정입니다. (결과적으로 왼쪽 견갑골의 담과 왼쪽 검지의 저림을 얻었다.)

왜 Typescript였는가?

Inversify는 JavaScript로도 사용할 수 있지만, 메타데이터를 다루는 과정이 지나치게 복잡해진다. 원래도 Typescript를 도입할 생각이 있었고, 더 이상 미룰 이유도 없었다. 그리고 어느 누가 javascript로 Inversify를 쓸 수 있을까?

그리고, Typescript는 단순히 언어 차원이 아닌 "안정성"에 투자하는 결정이었다. 런타임 오류를 줄이고, 컴파일 타임에 문제를 조기에 파악할 수 있다면, 결국 우리가 원하는 예측 가능한 시스템에 가까워질 수 있다.

"그럴 바엔 처음부터 강타입 언어를 쓰지 그랬냐"는 말도 있지만, 회사에서 Node.js를 밀고 있었고, 그렇다면 Javascript보단 Typescript가 더 나은 선택이었다는 건 명확했다.

기술 선택의 기준: 현실과 이상 사이의 균형

이상적으로는 NestJS + TypeORM 혹은 Prisma 같은 조합이 가장 모던했을 것이다. 하지만 현실적인 제약은 분명 존재했다.

• 프로젝트 요구사항이 명확하지 않음(담당자도 바뀜)
• 3월 초까지도 전체적인 틀이 잡히지 않음
• 5월 중순이 마감이라 일정 빠듯

Nest + ORM까지 한꺼번에 도입했다면 리스크가 너무 컸다. 그래서 선택한 건 점진적인 전환이었다. 그리고 우리의 문제를 해결할 수 있는 스택으로의 변화.

• Express → 유지
• Javascript → Typescript
• Callback 패턴 → Async/Await
• DI라는 개념이 존재하지 않음 → Inversify 기반 DI 도입

완전히 모던한 기술 스택을 모두 도입하진 못했지만, 방향성은 NestJS 마이그레이션을 기준으로 맞췄기 때문에 추후 전환이 훨씬 수월할 것으로 판단됩니다.

팀을 설득한 방식

처음부터 팀원들이 새로운 문법이나 낯선 구조를 반길 리 없었다. 익숙한 방식으로 작성하는 코드는 보기엔 싫지만 심적 안정감은 더욱 안정적일 것이다. 그리고 "정확히 알지 못하는 코드"를 작성하는 건 누구에게나 불안하기 때문이다. 그렇다고 무작정 강행하진 않았다. 대신 아래 방식으로 접근했다.

• 코드 리뷰에서의 안전성 강조
  • 타입을 통해 실수를 줄인다는 것을 실제 예제로 보여줌
• 중복 제거와 생산성 향상 라이브 코딩
  • File 업로드 코드 리팩토링 후, 클래스 하나로 모든 케이스를 처리하는 걸 보여줌
• 점진적인 도입
  • 전면 교체가 아닌 기능 단위로 분리해서, 익숙해질 시간을 충분히 확보

덕분에 팀원들도 직접 효과를 체감하면서 수용할 수 있었다. 지금은 오히려 더 날카로운 피드백을 주는 동료도 생겼다.

리팩토링, 그 구체적인 과정

예전엔 Express + Javascript + Callback 패턴 기반으로 작성된 코드가 많았다.
위에서 작성한 파일 업로드 기능만 해도 같은 로직이 수십 군데 중복돼 있었고, 변경 시엔 하나하나 수정해야 했다. 유지보수에 꽤나 오랜 시간이 걸렸다.

중복 제거를 위해 공통 로직을 DI 가능한 클래스로 만들었다. 기능별 책임을 확실하게 분리해 어떤 클래스가 어떤 책임을 갖고 있는지 명확하게 파악이 가능했다. 그 외에도 Controller, Service, Repository로 나눠지며 코드 작성할 위치를 명확하게 분별할 수 있었다.

이 결과, 파일 업로드 중복 코드 80% 이상 제거에 성공했고, 코드 길이나 유지보수 복잡도도 눈에 띄게 줄었다. 이제는 새로운 기능 요구가 들어와도 고민할 필요 없이 구조화된 흐름을 따라가기만 하면 된다. 우리는 좀 더 예외에 신경쓰고 들어오는 유지보수인척 하는 기능을 만드는데 치중할 수 있었다.

서로 이해되는 코드의 가치

이전엔 내가 짠 코드도 시간이 지나면 낯설었다. 지금은 서로가 약속한 구조를 기반으로 개발하고 있기 때문에, 다른 개발자가 짠 코드도 쉽게 파악할 수 있고, 문제 발생 시 토론도 가능하다. (실제로 Express의 Router에서 Controller로 진입할때 This에 관련된 토론도 진행했고, 그 이후 코어 자바스크립트에 관해서 1주일에 한번씩 돌아가며 발표도 진행했다.)

그리고 무엇보다, 이 과정을 통해 팀원들이 하나둘 기술 스택 전환과 코드의 변화에 대한 가치를 체감해주기 시작했다. 이제는 단지 "작동하는 코드"가 아닌, "이해할 수 있는 코드", "변화에 강한 코드"를 지향하게 되었다.

마무리하며

이제 프로젝트는 10일 뒤면 마무리다. 현재 25년 5월 7일

물론 유지보수 기간 중에도 더 보완할 부분이 있을 것이다.

하지만 최소한 유지보수가 가능한 코드로 발전했고, 회사 내에서도 꽤 큰 기술적 도전이었으며
나 혼자만의 욕심으로 바꾼 기술 스택이었지만, 이해를 바탕으로 끝까지 함께 와준 팀원들에게 진심으로 감사하다.