원세션 리팩터링 저널: 작은 승리를 기록해 코드베이스를 정말로 조금씩 더 좋게 만드는 법

지저분한 파일을 멍하니 바라보다가 한숨 쉬면서 이렇게 생각한 적이 있을 겁니다. “이걸 제대로 고칠 시간은 없어…” 혼자가 아닙니다. 대부분의 팀의 코드베이스는… 그냥 그런 상태입니다. 재앙은 아니지만, 그렇다고 깔끔하지도 않은—점점 작업하기 까다로워지는 그런 상태 말입니다.

문제는 기술적인 것만이 아닙니다. 감정적인 문제이기도 합니다.

모든 TODO, 얽힌 함수, 헷갈리는 이름 하나하나가, 그 부분에서 작업할 때마다 계속 들고 다녀야 하는 작은 정신적 짐이 됩니다. 몇 주, 몇 달이 지나면 이 작은 짐들이 쌓여서 진짜 짜증과 인지 과부하로 변합니다.

이에 맞서는 가벼운 방법이 바로 원세션 리팩터링 저널(one-session refactor journal) 입니다. 아주 단순한 습관인데, 이렇게 합니다:

1. 작업 세션(또는 하루)에 한 번, 작은 범위의 리팩터링을 합니다.
2. 무엇을, 왜, 어떻게 바꿨는지, 그리고 어떤 느낌이었는지 짧은 저널로 기록합니다.

별것 아닌 것처럼 들리죠. 하지만 그렇지 않습니다. 꾸준히 하면, “모든 걸 멈추고 대규모 리팩터링” 같은 단계를 거치지 않아도, 코드베이스를 나빠지지 않고 조금씩 더 좋아지게 만드는 조용한 엔진이 됩니다.

감정 상태가 코드 품질에 왜 중요한가

우리는 프로그래밍이 순수하게 논리적인 일이라고 생각하고 싶어 하지만, 실제 개발에는 감정적인 요소가 크게 작용합니다.

• 시스템의 깨지기 쉬운 부분을 건드릴 때 긴장을 느낍니다.
• 지저분한 영역에 또 다른 워크어라운드를 추가할 때 죄책감을 느낍니다.
• 해결할 여력이 없는 기술 부채가 있다는 걸 알 때 불안을 느낍니다.

이 감정적 오버헤드는 당신의 기술적 판단에도 영향을 줍니다.

• “저 파일은 지옥이야”라는 이유로 특정 파일을 회피하게 됩니다.
• 주변 코드가 혼란스러워서, 작은 변경도 과하게 고민하게 됩니다.
• “언젠가는 꼭 고쳐야지”라고 생각하는 것들을 머릿속에 떠안고 에너지를 소모합니다.

리팩터링 저널은 반쯤은 기술적 도구이고, 반쯤은 감정적 도구입니다. 이것은 당신에게 다음을 제공합니다.

• 머릿속에 계속 품고 있던 스트레스를 내려놓을 수 있는 공간
• 아직 망가진 것만 보는 대신, 실제로 나아진 부분을 구조적으로 인정할 수 있는 방법
• “코드베이스는 조각조각, 조금씩 더 좋아지고 있다”는 사실을 상기시켜 주는 히스토리

감정적 부담이 줄어들면 기술적 판단은 더 좋아집니다. 덜 반사적으로, 더 의도적으로 행동하게 되고, 언젠가 있을 “리팩터링 스프린트”를 기다리기보다, 당장 손에 닿는 부분부터 조금씩 개선하는 쪽을 선택하게 됩니다.

원세션 리팩터링 저널이란 무엇인가?

아이디어는 단순합니다.

• 원 세션(one session): 각 코딩 세션(또는 하루)에, 10–20분 정도의 짧고 제한된 시간만 투자해서, 이미 손대고 있는 코드와 관련된 리팩터링을 하나 합니다.
• 리팩터링만: 기능을 추가하지 않습니다. 구조, 네이밍, 가독성, 구성만 개선합니다.
• 저널 작성: 끝나고 나면 무엇을 바꾸었고 왜 그렇게 했는지 짧게 적어 둡니다.

정말 이게 전부입니다. 특별한 툴도 필요 없습니다.

저널은 원하는 곳에 둘 수 있습니다.

• 레포 안의 마크다운 파일 (refactor-journal.md)
• 공유 Notion/Confluence 페이지
• 본인이 편한 개인 메모 앱

매체는 중요하지 않습니다. 중요한 건 습관입니다.

리팩터링 저널 엔트리에는 무엇을 쓰나?

각 엔트리는 짧고 구조화해서 쓰면 좋습니다. 예를 들어:

## 2025-01-10 – PaymentService 정리

**Area:** `PaymentService`, `PaymentValidator`
**Time:** ~15분

**Problem:** 결제 검증 로직을 이해하기 어렵고, 하나의 긴 메서드가 여러 책임을 섞어서 가지고 있음.

**Changes:**
- `processPayment`에서 `validateCardDetails`와 `validateBillingAddress`를 분리(extract).
- `chk()`를 `validatePaymentRequest`로 리네임.
- 검증 단계에 대한 짧은 docstring 추가.

**Why:**
- 결제 검증을 별도로 테스트하기 쉽게 만들기 위해.
- `processPayment`를 읽을 때의 인지 부담을 줄이기 위해.

**Notes / Feelings:**
- 예전에 버그가 났던 영역이라 건드릴 때 좀 불안했음.
- 함수 분리와 네이밍 정리 후에는 로직을 읽을 때 확실히 마음이 더 편안해짐.

이 정도면 2–3분이면 쓸 수 있고, 다음을 얻습니다.

• 무엇이 개선되었는지에 대한 명확한 기록
• 단순히 “기분 내켜서 치웠다”가 아니라, 왜 그랬는지에 대한 이유
• 당신의 감정적 경험을 인정하고 풀어낼 수 있는 공간

시간이 지나면 이 엔트리들이 코드베이스가 어떻게 진화해 왔는지 보여주는 지도이자, “우리는 실제로 계속 나아지고 있다”는 증거가 됩니다.

작은 승리: 눈에 보이는 진전의 힘

거대한 아키텍처 리팩터링은 드뭅니다. 대부분의 조직은 몇 주 동안 기능 개발을 멈추고 “기초를 다 뜯어고치는” 일을 허용하기 어렵습니다. 그러다 보니, 문제는 늘 인식하고 있지만 정작 제대로 손댈 기회는 잘 오지 않는, 답답한 상태에 빠지기 쉽습니다.

원세션 리팩터링 저널은 이 구도를 뒤집습니다.

• 무언가를 개선하기 위해 허락을 기다릴 필요가 없습니다.
• 의미 있는 진전을 내기 위해 큰 시간 블록이 필요하지 않습니다.
• 작은 승리들이 축적되고, 기록되고, 보이고, 공유됩니다.

한 세션에 할 수 있는 리팩터링 예시는 이런 것들입니다.

• 동작을 더 잘 드러내도록 헷갈리는 함수 세 개의 이름을 바꾼다.
• 100줄짜리 메서드를 더 의도가 드러나는 여러 헬퍼 함수로 분리한다.
• 거대(god) 파일 하나를 역할이 더 분명한 두 개의 모듈로 나눈다.
• 복붙된 코드 덩어리를 작은 재사용 함수 하나로 치환한다.
• 깨지기 쉬운 외부 연동 부분에 대해 docstring이나 주석을 추가한다.

이것들 하나하나만 보면 시스템 전체를 바꾸지는 못합니다. 하지만 이런 작업이 반복되고, 기록될 때, 당신이 매일 실제로 마주치는 코드의 표면적이 점점 더 좋아집니다.

심리적으로도, 이런 작은 승리들의 리스트가 점점 길어지는 모습을 보는 것은 다음을 돕습니다.

• “대충 때워 넣고만 있다”는 느낌을 줄입니다.
• 어제의 리팩터를 보는 순간, 오늘 것도 더 쉽게 하게 됩니다.
• 이 코드베이스가 가라앉는 배라는 느낌을 줄입니다.

왜 ‘무엇’과 ‘왜’를 기록하는가? (미래의 나를 위한 패턴 찾기)

무엇을 리팩터링했는지, 왜 그렇게 했는지 적는 것은 단순한 기록 작업이 아닙니다. 이것은 정신적 공간을 만들어 줍니다.

머릿속에 다 담고 있으려고 하기보다, 다음을 하게 됩니다.

• “이 모듈은 볼 때마다 헷갈린다” 같은 걱정을 외부로 꺼내 적습니다.
• 당장 하고 있는 작업에 집중할 수 있도록 작업 기억(working memory)을 비워 냅니다.

몇 주에 한 번 저널을 훑어보면서 패턴을 찾고 질문해 보세요.

• 항상 같은 모듈만 치우고 있는가? 그렇다면 근본적인 재설계가 필요할 수 있습니다.
• 이름을 계속 바꾸고 있는가? 그렇다면 도메인 언어 자체가 불분명한 것일 수 있습니다.
• 가드 절(guard clause)이나 검증 로직을 자주 추가하는가? 그렇다면 더 명시적인 계약(계약 기반 설계)이나 더 나은 타입 시스템이 필요할지도 모릅니다.

이런 패턴들은 일상 업무 속에서는 잘 보이지 않는 깊은 구조적 문제를 드러냅니다. 그리고 더 큰 개선을 설득력 있게 주장할 근거를 제공합니다.

“지난 한 달 동안 Order 도메인을, 개념이 불명확해서 총 7번이나 손봤어요. 이 부분은 집중적으로 다시 설계해야 합니다.”

이 말은 “그쪽이 좀 지저분한 것 같아서요”보다 훨씬 설득력이 있습니다.

구조와 가독성이 먼저, 성능은 나중에

리팩터링 시간만 생기면 “뭔가 똑똑한” 성능 최적화를 하고 싶어질 수 있습니다. 대부분의 경우, 그건 지금 중요한 게 아닙니다.

일상적인 작업에서는, 다음을 개선하는 쪽이 장기적으로 훨씬 큰 가치를 줍니다.

• 네이밍: 함수와 변수가 실제로 하는 일을 드러내는 이름
• 구조: 한 파일에 다 몰아넣지 않고, 작고 집중된 모듈로 나누는 것
• 가독성: 흐름이 직선적이고, 읽을 때 놀랄 일이 적은 코드
• 테스트 용이성: 개별 로직을 따로 떼어 테스트하기 쉬운 구조

좋은 코드란, 6개월 뒤에 다른 일을 하고 돌아와도 여전히 이해할 수 있는 코드입니다. 리팩터링 저널은, 그런 기준에 더 가까워지도록 이끌어 주는 쪽으로 당신의 선택을 밀어줘야 합니다.

성능 최적화도 물론 중요합니다. 다만 그것은:

• 프로파일링과 측정에 의해 주도되어야 하고, 감(감각)에만 의존하면 안 되며,
• 마찬가지로 저널에 “무엇, 왜, 어떤 영향이 있었는지”를 기록하는 식으로 관리되어야 합니다.

대부분의 세션에서는 이런 목표로 가세요.

“이 코드를, 나중에 이걸 읽게 될 인간(미래의 나 포함)이 더 쉽게 이해할 수 있도록 만들자.”

당신의 미래 버전과 동료들은, 섣부른 마이크로 최적화보다 이 방향에서 훨씬 더 큰 가치를 얻게 될 것입니다.

원세션 습관은 기능 개발과 어떻게 함께 가는가

팀들은 종종 “리팩터링을 하면 속도가 느려질까 봐” 걱정합니다. 원세션 리팩터링 습관은 이를 정반대로 설계한 것입니다.

• 작다: 세션당 10–20분이면, 충분히 설득 가능한 수준의 시간입니다.
• 로컬(local): 새 기능이나 버그 픽스 때문에 이미 손대고 있는 코드 주변만 개선합니다.
• 점진적: 출시를 막을 만한 위험한 빅뱅식 변경은 하지 않습니다.

팀 가이드라인으로 이렇게 정할 수 있습니다.

무언가 코드를 수정할 때마다, 발견했을 때보다 약간이라도 더 나은 상태로 남겨두고, 무엇을 했는지 기록한다.

시간이 지나면 이것은 다음을 가능하게 합니다.

• “청소 타임”이 따로 필요 없을 정도로, 기술 부채를 지속적으로 갉아먹게 됩니다.
• 가장 자주 쓰이는 부분이 가장 상태가 좋은 코드가 되도록 유지합니다.
• 개선 작업을 “추가 옵션”이 아니라, 딜리버리의 일부로 정상화합니다.

작게나마 성과를 드러내고 싶다면 이렇게도 해볼 수 있습니다.

• 스탠드업 미팅에서 의미 있었던 리팩터링 저널 엔트리를 공유한다.
• 팀 채널에 “이번 주의 리팩터링”을 하나 골라 올린다.
• 신규 팀원이 왔을 때, “이 코드가 어떻게, 왜 이런 모양이 되었는지”를 설명하는 온보딩 자료로 저널을 활용한다.

이렇게 되면 리팩터링은 “추가 작업”이 아니라, 시스템에 대한 지속적인 관리(stewardship) 로 인식됩니다.

시작하기: 최소 실행 가능 플레이북

이걸 시작하기 위해 허락이나 프로세스 개편이 필요하지는 않습니다. 2주만 이렇게 해 보세요.

1. 간단한 저널을 만든다

   • 레포에 refactor-journal.md 파일을 추가하거나,
   • 팀 워크스페이스에 공유 문서를 하나 만든다.

2. 시간 박스를 정한다

   • 코딩 세션의 시작 또는 끝에 10–20분.

3. 리팩터 범위를 정한다

   • 그 시간 안에 현실적으로 개선할 수 있는 것을 고른다.
   • 네이밍, 구조, 가독성 개선에 우선순위를 둔다.

4. 짧은 엔트리를 쓴다

   • 손댄 영역
   • 무엇이 바뀌었는지
   • 왜 더 나아졌는지
   • 선택 사항: 그때 어떤 느낌이었는지

5. 주말/주말 무렵에 한 번 리뷰한다

   • 그 주의 엔트리를 읽어 본다.
   • 반복해서 등장하는 패턴, 계속 아픈 부분, 더 깊게 들여다볼 가치가 있는 영역을 찾는다.

팀으로 일한다면, 다른 사람들도 같이 적게 해 보세요. 어디가 핫스팟인지, 어디가 모두의 스트레스 포인트인지, 또 어디에서 함께 승리하고 있는지 금방 보이기 시작합니다.

결론: 더 나은 코드, 더 가벼운 마음, 그대로인 속도

코드베이스가 훌륭해지는 건, 한 번의 영웅적인 리팩터링 때문이 아닙니다. 처음에 지저분해진 것과 똑같은 방식으로 좋아집니다. 바로, 매일의 작은 결정과 작은 변경들이 수백 번, 수천 번 쌓인 결과입니다.

원세션 리팩터링 저널은 이 현실을 당신 편으로 돌려 줍니다.

• 기술 부채를 머릿속이 아닌, 기록이라는 다른 공간에 옮김으로써 감정적 부담을 줄입니다.
• 작지만 지속적인 개선을 눈에 보이게, 추적 가능하게, 공유 가능하게 만듭니다.
• 조급한 영리함 대신 구조와 가독성을 중시하는 습관을 기릅니다.
• 미래의 당신과 팀에게, 더 명확하고 차분한 코드베이스를 남겨 줍니다.

거창한 이니셔티브는 필요 없습니다. 다음 코딩 세션에서, 이미 손대고 있는 코드의 한 부분을 10분만 들여서 더 좋게 만들어 보세요. 그리고 그걸 적어 두세요.

그렇게 해서 코드베이스는 실제로 더 좋아집니다. 한 번의 거창한 리팩터링이 아니라, 작지만 기록된 승리 하나하나가 쌓이면서 말입니다.