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

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

왜 클린코드를 챙기기 시작했는가 (이유)

장애 복구 — 읽는 시간이 곧 돈이었다

기능 속도는 결국 코드 읽는 속도에 달려 있다고 느꼈다. 리뷰 비용은 복잡도에 비례한다는 걸 여러 번 확인했다.
결제/정산 쪽 장애를 겪을 때는 더 분명해졌다. 새벽에 로그를 뒤지는 시간, 변수 이름을 추적하는 시간 — 가독성이 곧 복구 시간이었다.

그래서 클린코드를 취향이 아니라 운영 리스크 줄이는 선택으로 봤다. ‘예쁘게’가 아니라 ‘다음 사람이 덜 헤매게’가 목적이었다.

팀에 맞춰 정한 원칙 (당시 결론)

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

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

1) 위험도부터 나눴다

배치, 결제, 인증처럼 영향 큰 모듈을 먼저 분류했다. 테스트 없는 영역은 구조 변경을 피했다. 레거시 분석에서 배운 것처럼, ‘왜 이렇게 생겼는지’를 못 쓰면 손대지 않기로 했다.

2) 작게, 자주 바꿨다

큰 PR은 피하고, 읽기 쉬운 단위로 쪼갰다. ‘동작은 그대로, 가독성만’을 원칙으로 삼았다. 한 PR에 리팩토링과 기능 변경이 섞이면 검증이 꼬였고, 그날은 회복이 늦어졌다.

3) 기준을 자동화했다

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

자주 터졌던 패턴

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

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

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

어느 날 리뷰에서 세 번째로 ‘여기 들여쓰기’를 적고 나서 깨달았다. 기준이 사람 입에 있으면, 그날의 컨디션과 관계에 따라 흔들린다. 새 멤버가 올 때마다 같은 설명을 처음부터 다시 했다.

• 당시 결론: 기계가 막을 수 있는 건 기계에게 넘기기로 했다. Prettier/ESLint를 CI에 걸고, 포맷·스타일 논쟁을 리뷰에서 아예 제거했다. 사람은 ‘이름이 의도를 드러내는가’, ‘이 책임이 한 곳에 있는가’ 같은 사람만 볼 수 있는 것에 집중하게 했다.
• 이렇게 나누고 나서야 리뷰가 감정 소모가 아니라 설계 대화가 됐다.

개선점 (지금 부족한 것)

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

앞으로 나가야 할 방향

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

마무리

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

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