배포 전에 조용히 버그를 죽이는 작은 습관

대부분의 버그는 무지 때문에 생기지 않습니다.

대부분은 서두름 때문에 생깁니다.

빈 배열을 처리해야 한다는 걸 알고 있었죠. 에러 체크를 하나 더 추가하려고 하고 있었죠. 테스트를 하나만 더 쓰겠다고 마음먹고 있었죠. 그러다 슬랙이 울리고, 스탠드업이 시작되고, 덜 정리된 커밋이 그대로 main에 들어가 버립니다.

이 글은, 코드가 레포에 들어가기 직전에 마지막 "품질 게이트" 역할을 하는 터무니없이 작은 실천에 대한 이야기입니다.

원노트 코딩 넛지(One-Note Coding Nudge) — 1분도 안 걸리는, 단 하나의 노트로 하는 커밋 전 의식. 잠깐 멈춰 서서, 흔한 버그 원인을 훑어보게 만들고, 미래의 나를 덜 고생하게 만드는 습관입니다.

이건 툴도 아니고, 프레임워크도 아니고, 거창한 프로세스 개편도 아닙니다. 아주 간단한 체크리스트 + 아주 조금 느려진 커밋 플로우일 뿐인데, 조용히 결함률을 크게 줄여 줍니다. 많은 팀에서 이런 습관만 잘 굴려도 예방 가능했던 버그의 절반 이상이 사라집니다.

“이런 건 다 아는데”도 왜 커밋 전 의식이 필요한가

다 이런 베스트 프랙티스들은 들어봤을 겁니다:

• null / 빈 입력 처리하기
• 엣지 케이스 생각하기
• 에러 경로 확인하기
• 커밋 메시지를 명확하게 쓰기

문제는 이걸 모르는 게 아닙니다.

문제는 이걸 정말 중요한 그 순간, 즉 코드가 레포의 히스토리가 되기 직전에 기억하지 못한다는 겁니다.

커밋 전 의식(pre-commit ritual)은 세 가지 중요한 일을 합니다:

1. 잠깐의 멈춤을 만든다. 타이핑 → 커밋 → 푸시 오토파일럿을 끊어 줍니다.
2. 놓친 걸 떠올리게 한다. 짧은 체크리스트가 눈에 안 보이는 실패 지점을 상기시켜 줍니다.
3. 흔적을 남긴다. 좋은 커밋 메시지는 당신의 가정, 트레이드오프, 위험 요소를 문서화합니다.

며칠만 보면 별것 아닌 것 같지만, 몇 달이 지나면 엄청나게 깨끗한 코드베이스로 복리 효과처럼 쌓입니다.

원노트 체크리스트: 마지막 순간의 버그 필터

위키도, PDF도, 회사 전체 이니셔티브도 필요 없습니다.

노트 한 개면 충분합니다.

메모 앱을 열거나, 레포에 PRE_COMMIT.md 파일을 하나 만들고, 이런 식의 짧은 목록을 적어 두세요:

Pre-Commit Nudge

1. 입력 & 엣지 케이스 확인했나?
   - null / undefined / None
   - 빈 문자열 / 리스트 / 컬렉션
   - 특이한 크기 (0, 1, 최대, 매우 큼)

2. 에러 & 실패 상황 처리했나?
   - 네트워크/DB/IO 실패 시 어떻게 동작하지?
   - 의미 있는 에러를 로그로 남기거나 노출하나?

3. 현실적인 스케일에서 성능 괜찮나?
   - 큰 데이터셋에서 눈에 띄는 N+1 루프나 O(n^2) 구간 없나?

4. 클린 코드 한 번 훑었나?
   - 이름이 명확한가?
   - 함수가 작고 한 가지에 집중하나?
   - 책임이 잘 분리돼 있나?

5. 빠른 디버그/검증 했나?
   - 관련 테스트 돌렸나?
   - 불변 조건(invariant)들을 assert 했나?
   - 실패 경로를 머릿속으로라도 따라가 봤나?

6. 커밋 메시지 준비됐나?
   - “왜” 이 변경이 필요한지, 가정, 트레이드오프가 드러나나?

이게 전부입니다. 이게 바로 의식입니다.

모든 커밋 전에, 이 노트를 한 번 훑으면서 각 항목을 머릿속으로 톡톡 건드려 주세요. 작은 변경이면 1분도 안 걸리고, 커져도 2분 내외일 겁니다.

이건 완벽해지자는 게 아닙니다. 프로덕션에서 80%의 고통을 만드는, 20%의 대표적인 이슈만 잡아내자는 겁니다.

에디터로 ‘잠깐 멈춤’을 강제로 만들기

이 습관을 몸에 익히는 가장 쉬운 방법은, 도구가 당신을 조금만 느리게 만들게 하는 겁니다.

커맨드라인에서 메시지까지 한 번에 치며 커밋하는 대신, 에디터 기반 플로우를 쓰세요:

git commit

그러면 Git이 설정된 에디터(VS Code, Vim 등)를 열고, 비어 있는 커밋 메시지 파일을 보여줍니다. 이게 두 가지 효과를 만듭니다:

1. 무조건 한 번 멈추게 된다. 더 이상 git commit -m "fix" 같은 근육 기억에 의한 커밋이 어렵습니다.
2. 에디터 안에 있다. 즉, 스플릿 뷰로 옆에 원노트 체크리스트를 띄워 놓기 쉽습니다.

추천 세팅:

• 왼쪽 패널: 코드 diff
• 오른쪽 패널: PRE_COMMIT.md(또는 노트) + 커밋 메시지 파일

그러면 플로우는 이렇게 바뀝니다:

1. 변경 사항을 stage 한다.
2. git commit을 실행한다.
3. 체크리스트를 한 번 훑으면서 각 항목을 머릿속으로 점검한다.
4. 의미 있는 제목(subject)과 본문을 쓴다.
5. 저장 후 닫아서 커밋을 완료한다.

이 작은 마찰은 버그가 아니라 기능입니다. 앞으로 몇 시간, 며칠의 디버깅을 아끼기 위해, 지금 몇 초의 생각 시간을 사는 겁니다.

커밋 메시지를 ‘혼자 하는 코드 리뷰’처럼 대하기

대부분의 커밋 메시지는 별 쓸모가 없습니다:

• fix bug
• update stuff
• changes

이런 메시지는 코드가 왜 바뀌었는지, 무엇을 걱정했는지, 어떤 숨은 가정이 있는지 아무것도 말해 주지 않습니다.

대신, 각 커밋 메시지를 짧지만 진짜 1인 코드 리뷰라고 생각해 보세요.

제목(50–72자 정도):

"빈 검색어는 API를 호출하지 않고 처리"

본문에는 이런 걸 담습니다:

• 이 변경이 왜 필요했는지
• 어떤 접근을 선택했는지
• 가정과 트레이드오프는 무엇인지
• 위험 구간이나 못 쓴 테스트가 있다면 무엇인지

예시:

빈 검색어는 API를 호출하지 않고 처리

- 검색어가 비어 있으면 핸들러에서 바로 단락 처리
- API 호출 대신 즉시 빈 결과셋 반환
- 빈 검색어는 백엔드를 타지 않는다는 가정 (PM과 확인 완료)
- 트레이드오프: 이제 빈 검색어는 분석(analytics)에 기록되지 않음
- 누락: 공백만 있는 검색어(whitespace-only) 엣지 케이스 테스트 (TODO)

이게 만들어 내는 효과는 이렇습니다:

• 미래의 나는 커밋만 봐도 의도를 바로 이해할 수 있습니다.
• 숨은 가정들이 문서에 박혀 나옵니다.
• 알면서도 못 한 부분이 분명하게 표시됩니다.

몇 주 뒤 버그가 생겨서("왜 빈 검색어가 분석에 안 찍이지?")를 파헤칠 때, 완전 처음부터 추적하지 않아도 됩니다. 이미 그때의 판단과 트레이드오프가 기록돼 있으니까요.

베스트 프랙티스를 체크리스트에 ‘굽혀 넣기’

코딩 베스트 프랙티스를 적용하기 가장 좋은 시점은, 코드가 정말로 히스토리가 되기 직전입니다.

그래서 원노트 의식에 “클린 코드” 항목을 하나 넣어 두는 겁니다:

• 네이밍

  • 각 함수/변수 이름이 무엇을 의미하는지 드러나는가?
  • data, info, handle 같은 모호한 이름 대신 도메인 언어를 쓰고 있는가?

• 작은 함수

  • 한 함수가 3–4가지 일을 한 번에 처리하고 있지는 않은가?
  • 잘 이름 붙인 작은 헬퍼 함수로 하나 분리할 수는 없나?

• 명확한 책임 분리

  • 이 함수/모듈이 I/O 도 하고, 비즈니스 로직 도 하고, 포맷팅 도 하고 있지는 않은가?
  • 더 명확한 경계로 책임을 나눌 수는 없나?

매 커밋마다 시스템 전체를 리팩터링하자는 게 아닙니다. 적어도 이번 변경이 새 혼돈이나 복잡도를 추가하지만은 않게 하자는 겁니다.

마음가짐은 간단합니다: 새로운 지저분함은 만들지 말자.

선제 디버깅 패스: 머릿속에서 먼저 실패해 보기

대부분의 개발자는 해피 패스(happy path) 위주로만 머릿속 실행을 합니다.

커밋 전 의식은 실패 경로에도 같은 시간을 주라는 리마인더입니다:

• 이게 null을 반환하면 어떻게 되지?
• API가 타임아웃 나거나 이상한 데이터를 주면?
• 입력이 아주 커지면? (10개가 아니라 10,000개라면?)
• 이 함수가 빡빡한 루프 안에서 계속 호출되면?

이걸 짧은 선제 디버깅 패스로 바꿔 보세요:

1. 타깃 테스트 실행

   • 이번에 손댄 함수에 대한 유닛 테스트
   • 새 동작을 실제로 태워 보는 통합 테스트 1–2개

2. 불변 조건(invariant) 추가/확인

   • id는 절대 null이 아니다, 배열 길이는 서로 맞는다, 상태는 일관된다… 같은 assert
   • 함수 맨 앞에 잘못된 입력을 거르는 guard clause 추가

3. 실패 경로를 머릿속으로 따라가기

   • DB가 죽어 있으면 사용자는 무엇을 보게 될까?
   • 설정(config)이 없으면 앱은 뻗을까, 아니면 점잖게 degrade 할까?

이 과정은 30–60초면 충분한데, 효과는 묘하게 큽니다:

• 사용자가 발견하기 전에 빠진 체크를 내가 먼저 발견합니다.
• 아직 안 쓴 테스트가 무엇인지 선명해집니다.
• 쉬운 곳이 아니라 취약한 곳을 강화하게 됩니다.

1분짜리 의식이 어떻게 버그를 줄이는가

커밋마다 30–60초를 더 쓰는 게 부담처럼 느껴질 수 있습니다.

실제로는, 코드 품질 측면에서 가장 ROI가 높은 투자 중 하나입니다.

• 많은 팀이, 이런 간단한 체크리스트 + 더 나은 커밋 메시지만으로 결함을 50–80%까지 줄이기도 합니다.
• 설령 버그가 새어 나가도, 커밋 메시지가 가정을 기록하고 있어서 역추적이 훨씬 쉬워집니다.
• 네이밍, 구조, 책임을 매 커밋마다 다시 점검하기 때문에, 코드가 시간이 지나도 유지보수 가능한 상태를 더 잘 유지합니다.

이게 바로 ‘복리 효과’입니다:

• 오늘은 null 포인터 버그 하나를 막습니다.
• 내일은 N+1 성능 문제를 피합니다.
• 다음 주에는, 깔끔한 커밋 히스토리 덕분에 3시간 걸릴 디버깅을 10분 만에 끝냅니다.

새 툴도, 무거운 프로세스도 필요 없습니다. 아주 작지만, 꾸준한 “잠깐의 멈춤”이면 충분합니다.

오늘 바로 시작해서, 진짜 습관으로 만드는 법

원노트 코딩 넛지는 10분 안에 도입할 수 있습니다:

1. 나만의 원노트 체크리스트 만들기

   • 위에 나온 예시를 그대로 써도 좋고, 팀에서 자주 터지는 버그 유형에 맞게 커스터마이즈해도 됩니다.

2. 에디터 기반 커밋으로 전환하기

   • 예: git config --global core.editor "code --wait" (또는 사용하는 에디터)
   • -m 없이 git commit을 써서, 항상 에디터가 뜨도록 하세요.

3. 노트를 항상 보이게 두기

   • 에디터에서 고정(pin)하거나,
   • 레포 안에 PRE_COMMIT.md를 두고 스플릿 뷰로 항상 열어 두세요.

4. 7일만 진지하게 해 보기

   • 딱 1주일 동안, 모든 커밋에 이 의식을 적용해 보세요.
   • 일주일이 끝날 때, 이 잠깐의 멈춤 덕분에 잡아낸 버그/설계 문제를 적어 보세요.

아마 적어도 하나 이상, 그대로 배포했을 법한 버그나 설계 구멍을 발견했을 겁니다. 그게 이 습관이 ‘먹히고 있다’는 증거입니다.

결론: 가장 작은 프로세스로 얻는 가장 큰 수확

더 좋은 코드를 위해 새로운 방법론이 꼭 필요한 건 아닙니다.

필요한 건, 아주 작지만 반복 가능한 멈춤입니다. 그리고 그 멈춤이 이렇게 묻는 겁니다:

• 이상한 입력들도 처리했는가?
• 에러와 실패 상황을 충분히 생각했는가?
• 이 코드는 작은 단위로, 읽기 쉽게, 명확하게 나뉘어 있는가?
• 중요한 경로를 검증했는가?
• 이 변경이 왜 존재하는지 설명했는가?

원노트 코딩 넛지는 그 질문을 던져 주는 장치입니다.

노트 한 개. 1분. 아주 작은 습관 하나가, 시간 속에서 엄청난 수의 미래 버그를 레포 바깥에 머물게 합니다. 그리고 미래의 내가 git blame을 보며 과거의 나를 욕할 일을 크게 줄여 줍니다.

다음 커밋부터 바로 시작해 보세요.