실무에서 클린코드와 리팩토링을 적용하는 플레이북

코드 품질은 한 번에 정리되는 게 아니었다.
작게 쪼개고, 기준을 맞추고, 반복해서 고치는 방식이 결국 가장 덜 흔들렸다.

왜 클린코드를 챙기기 시작했는가

• 기능 속도는 결국 코드 읽는 속도에 달려 있다고 느꼈다.
• 리뷰 비용은 복잡도에 비례한다는 걸 여러 번 확인했다.
• 장애 복구 시간은 가독성과 직결된다는 걸 현장에서 배웠다.

그래서 클린코드를 취향이 아니라 운영 리스크 줄이는 선택으로 봤다.

팀에 맞춰 정한 원칙

1. 함수는 한 가지 일만 하게 했다.
2. 이름은 의도가 드러나게 지었다.
3. 중복은 줄이되, 무분별한 추출은 막았다.
4. 린트/포맷은 도구로 강제했다.

리팩토링은 이렇게 진행했다

1) 위험도부터 나눴다

• 배치, 결제, 인증처럼 영향 큰 모듈을 먼저 분류했다.
• 테스트 없는 영역은 구조 변경을 피했다.

2) 작게, 자주 바꿨다

• 큰 PR은 피하고, 읽기 쉬운 단위로 쪼갰다.
• “동작은 그대로, 가독성만”을 원칙으로 삼았다.

3) 기준을 자동화했다

• Prettier, ESLint를 CI에 걸었다.
• 리뷰 체크리스트를 템플릿으로 고정했다.

자주 터졌던 패턴

• 완벽한 구조를 먼저 찾다가 일정이 밀렸다.
• 공통화에 집착하다 오히려 추적이 어려워졌다.
• 리팩토링 PR에 기능 변경이 섞여 검증이 꼬였다.

비슷한 경험 — 기준을 ‘말’이 아니라 ‘도구’로 옮긴 순간

처음엔 클린코드를 말과 리뷰 코멘트로 퍼뜨리려 했다. 그런데 사람이 매번 같은 지적을 반복하니, 지적하는 쪽도 받는 쪽도 지쳤다. ‘이건 취향 아니냐’는 갈등도 생겼다.

• 이유: 기준이 사람 입에 있으면, 그날의 컨디션과 관계에 따라 흔들렸다. 새 멤버가 올 때마다 같은 설명을 처음부터 다시 했다.
• 당시 결론: 기계가 막을 수 있는 건 기계에게 넘기기로 했다. Prettier/ESLint를 CI에 걸고, 포맷·스타일 논쟁을 리뷰에서 아예 제거했다. 사람은 “이름이 의도를 드러내는가”, “이 책임이 한 곳에 있는가” 같은 사람만 볼 수 있는 것에 집중하게 했다.
• 이렇게 나누고 나서야 리뷰가 감정 소모가 아니라 설계 대화가 됐다.

개선점 (지금 부족한 것)

• 린트/포맷은 자동화됐지만, 설계 수준의 기준(레이어 분리·의존 방향) 은 여전히 사람 합의에 의존한다.
• 리팩토링 우선순위가 “눈에 거슬리는 곳” 위주라, 실제 장애·변경 빈도 데이터와 연결돼 있지 않다.
• 체크리스트가 팀마다 조금씩 달라, 신규 인원이 “어느 기준이 진짜냐”를 헷갈려 한다.

앞으로 나가야 할 방향

1. 설계 규칙 일부도 정적 분석 규칙(import 경계, 순환 의존 금지 등) 으로 옮겨, 합의를 코드로 박제한다.
2. 변경/장애가 잦은 모듈을 데이터로 추려, ‘리팩토링을 감이 아니라 우선순위로’ 한다.
3. 리뷰 체크리스트를 단일 소스(개발자센터)로 모아, 팀 간 기준 편차를 줄인다.
4. AI 코드 리뷰(AI 코드 리뷰, 어디까지 믿을까)를 ‘1차 정리’로 끼워, 사람은 마지막 설계 판단에만 힘을 쓰게 한다.

마무리

클린코드는 정답 맞히기가 아니었다.
팀이 지킬 수 있는 기준을 만들고, 그걸 반복하는 일에 가까웠다.

지금의 다음 목표는, 그 “지킬 수 있는 기준”을 점점 더 사람의 의지에서 도구의 기본값으로 옮기는 것이다. 사람이 의지로 지키는 기준은 언젠가 무너지지만, 도구가 막는 기준은 새벽에도 똑같이 동작한다.