Rain Lag

디버그 레저: 혼란스러운 디버깅 세션을 추적 가능한 진행 상황으로 바꾸는 단순한 러닝 로그

간단하고 마찰이 적은 디버그 레저가 지저분한 코딩·디버깅 세션을 결정, 실험, 수정 과정을 명확하게 검색 가능한 기록으로 바꿔 유지보수성을 높이고, 디버깅을 가속하며, 장기적인 지식 베이스를 쌓는 방법을 소개합니다.

디버그 레저: 혼란스러운 세션을 추적 가능한 진행 상황으로 바꾸는 단순 러닝 로그

소프트웨어 프로젝트는 보통 한 번의 큰 실수 때문에 망가지지 않습니다. 대신, 잊혀진 결정들, 어렴풋이 기억나는 실험들, 그리고 “나중에 문서로 정리해야지” 하다가 영영 쓰이지 않는 순간들이 조금씩 쌓이며 서서히 부식됩니다.

**디버그 레저(debug ledger)**는 이런 엔트로피에 맞서는, 놀라울 만큼 단순한 습관입니다. 일하는 동안 계속 업데이트하는 일반 텍스트 기반의 러닝 로그입니다. 정식 설계 문서도 아니고, 커밋 메시지도 아니고, 티켓 설명도 아닙니다. 지금 무엇을 시도하고 있고, 무엇을 보고 있으며, 무엇을 결정하고 있는지를 실시간으로 적어 내려가는 나만의 라이브 내러티브입니다.

꾸준히 사용하면 디버그 레저는 다음과 같은 효과를 냅니다.

  • 혼란스럽고 컨텍스트 전환이 잦은 세션을 추적 가능한 진행 상황으로 바꿉니다.
  • 유지보수성과 장기적 가시성을 크게 향상시킵니다.
  • 같은 버그를 반복해서 파고드는 낭비를 줄입니다.
  • 더 나은 애플리케이션 로깅과 관측 가능성(observability) 설계에 도움을 줍니다.

거창한 시스템이 필요하지 않습니다. 텍스트 파일 하나와 그걸 적는 습관이면 충분합니다.

디버그 레저란 무엇인가?

디버그 레저는 개발과 디버깅을 하는 동안 유지하는 **러닝 로그(running log)**입니다. 이렇게 생각하면 쉽습니다.

  • 내가 한 일을 기록하는 타임스탬프가 붙은 노트북
  • 결정, 실험, 관찰을 실시간으로 적어 두는 장소
  • 내 머릿속 상태와 코드 상태를 이어 주는 다리

매끄럽게 다듬은 글이 아닙니다. 다소 지저분해도 괜찮지만, 일정한 형식만 유지되는 빠른 메모에 가깝습니다.

전형적인 레저 항목은 (Markdown이나 일반 텍스트로) 대략 이렇게 생겼습니다.

## 2026-01-04

[09:12] [BUG] 사용자 세그먼트 B에 대해서만 `/orders` API가 500을 반환함.
- 관찰: `promo_code`가 있을 때만 에러 발생.
- 가설: `promo_code` 검증(validation)이 실패하고 있을 가능성.

[09:25] [EXPERIMENT] 개발 환경에서 `promo_code` 검증을 임시로 비활성화.
- 결과: 500 에러는 사라졌지만, 잘못된 코드도 그대로 통과함.

[09:40] [FIX] null과 빈 문자열을 일관되게 처리하도록 검증 로직 수정.
- 테스트 추가: `test_orders_with_empty_promo_code_returns_200`.
- 커밋: `fix: handle empty promo code without 500`.

[09:55] [NOTE] 패턴: 인보이스 서비스에도 유사한 검증 이슈 존재.
- TODO: 모든 프로모션 관련 플로우에 대해 검증 로직을 재검토하는 티켓 추가.

정말 이게 전부입니다. 특별한 툴은 필요 없습니다. 하지만 이 단순한 구조가 일하는 방식을 바꿉니다.

단순 러닝 로그가 유지보수성을 극적으로 높이는 이유

유지보수성은 깨끗한 코드만의 문제가 아닙니다. 코드가 왜 지금 이런 형태가 되었는지 이해하는 것도 포함됩니다.

디버그 레저는 다음을 보존합니다.

  • 컨텍스트: 왜 여러 선택지 중 이 접근을 택했는지
  • 제약 조건: 당시 무엇을 우선적으로 최적화하고 있었는지
  • 트레이드오프: 일부러 완벽하게 만들지 않고 남겨 둔 부분은 무엇인지

몇 달이 지나 누군가가 이렇게 묻는 상황을 떠올려봅시다.

“이 엣지 케이스 처리가 왜 이렇게 이상하게 되어 있죠?”

그때 당신은 이렇게 할 수 있습니다.

  • 레저에서 함수 이름, 티켓 ID, 날짜 등으로 검색하고
  • 당시의 사고 과정과 제약을 다시 복원하며
  • 미묘하지만 중요한 문제를 해결하고 있는 로직을 덜컥 걷어내는 일을 피할 수 있습니다.

이렇게 디버그 레저는 일종의 기억 보조 장치(memory prosthesis) 역할을 합니다. “이 버그 예전에 본 것 같은데…”에서 오는 답답한 데자뷔는, 빠른 검색과 구체적인 답으로 바뀝니다.

시간이 흐르면서 레저는 가벼운 개인 변경 로그가 되어, Git 히스토리와 티켓 시스템을 보완합니다. Git이 “무엇이 바뀌었는지”를 보여 준다면, 레저는 “어떻게 생각했는지”를 기록해 줍니다.

혼란스러운 세션을 추적 가능한 진행 상황으로 바꾸기

대부분의 개발자는 깔끔하고 일직선 형태의 흐름으로 일하지 않습니다. 실제 하루는 대개 이렇습니다.

  • 메시지와 요청이 깊이 있는 작업을 끊고
  • 여러 버그가 동시에 우선순위를 다투고
  • 기능 개발, 코드 리뷰, 운영 이슈를 오가며 계속 컨텍스트를 전환합니다.

레저 없이 이런 날을 보내면 이렇게 됩니다.

  • 실타래를 놓침: “회의 전에 내가 무슨 작업 하고 있었지?”
  • 이미 시도했던 실험을 잊고 똑같은 걸 또 해봄
  • 회귀(regression) 버그를 추적할 때 타임라인을 복원하기 어려움

러닝 로그는 이런 상황에서 당신을 도와줍니다.

  1. 세션을 앵커링(anchoring)한다
    하루를 시작할 때 짧은 기록을 남깁니다.

    ## 2026-01-04
[08:55] [PLAN] 오늘 목표: 주문 500 에러 수정 및 신규 할인 플로우 테스트 작성.

  2. 컨텍스트 전환을 표시한다
    방해를 받을 때 다음처럼 적습니다.

    [10:10] [INTERRUPTION] 주문 버그 작업 잠시 중단, PR #482 리뷰로 전환.

  3. 다시 시작할 때 빠르게 복구한다
    돌아왔을 때, 마지막 로그 항목만 보면 어디까지 했고 어떤 생각을 하고 있었는지 바로 떠올릴 수 있습니다.

이렇게 하면 하루가 여러 조각으로 끊겼다 하더라도, 결과적으로는 일관된 진행 기록이 남습니다. “오늘 뭐 한 거지?” 하는 흐릿한 기억 대신요.

실제로 도움이 되는 실용적인 기록 기법

디버그 레저를 효과적으로(그리고 지속 가능하게) 만들려면, 단순하지만 약간의 구조를 갖추는 것이 좋습니다.

1. 타임스탬프를 붙이기

각 항목 앞에 대략적인 시간을 붙입니다.

[14:03] [BUG] 상품 업데이트 시 캐시가 무효화되지 않음.

이렇게 하면:

  • 장애나 인시던트 발생 시 타임라인을 재구성하기 쉽고
  • CI 실행, 배포 시점, 운영 로그와 나의 활동을 서로 대조할 수 있습니다.

2. 짧고 명확한 라벨 사용하기

항목을 분류하기 위해 소수의 라벨만 정해 두고 사용합니다. 예를 들면:

  • [BUG] – 관찰된 문제 상황
  • [HYPOTHESIS] – 무엇이 일어나고 있는지에 대한 가설
  • [EXPERIMENT] – 시도한 변경(코드, 설정, 데이터 등)
  • [OBSERVATION] – 실제로 관찰된 결과
  • [FIX] – 문제를 해결한 변경
  • [NOTE] – 일반적인 인사이트나 메모, 참고 사항
  • [PLAN] / [TODO] – 계획과 후속 작업

이런 라벨은 나중에 로그를 훑어보고 검색하기 쉽게 만들어 줍니다.

3. 짧고 집중된 메모를 유지하기

장문의 문단은 피하고, 다음 세 가지만 간결하게 적습니다.

  • 무엇을 바꿨는지
  • 무엇을 기대했는지
  • 실제로 어떻게 되었는지

예를 들면:

[11:22] [HYPOTHESIS] 인증 오류는 스테이징 환경의 JWT 시크릿(secret) 만료 때문일 수 있음.
[11:30] [OBSERVATION] 시크릿은 90일 전에 마지막 회전; 앱과 인증 서비스 간 설정 불일치 발견.
[11:37] [FIX] 앱 설정을 최신 시크릿으로 업데이트; 스테이징 로그인 정상 동작 확인.

짧고 구조화된 항목은 장문의 문서보다 유지하기 훨씬 쉽습니다.

개인 레저가 애플리케이션 로깅을 개선하는 방식

개인 디버그 레저를 적다 보면, 자연스럽게 더 나은 애플리케이션 로그를 설계하는 훈련이 됩니다.

레저를 쓰다 보면 머릿속이 점점 이렇게 구조화됩니다.

  • 시간에 따라 흘러가는 이벤트의 흐름
  • 원인과 결과
  • 가설과 관찰의 쌍

어려운 버그를 디버깅하면서 로그를 들여다볼 때, 무엇이 빠져 있는지 금방 보이기 시작합니다.

“지금 필요한 건 user ID, 적용된 feature flag, 요청 path인데, 로그에는 일반적인 에러 메시지밖에 없네.”

그러면 다음을 할 수 있습니다.

  • 그 인사이트를 바로 코드의 구조화된 로그(structured log) 개선으로 옮기고
  • 실제 디버깅할 때 자주 묻는 질문에 맞게 필드를 추가하며
  • 로그 메시지를 이미 개인 레저에서 사용하는 **정신 모델(mental model)**과 정렬시킵니다.

시간이 지나면 이렇게 됩니다.

  • 애플리케이션 로그가 일관된 스토리를 들려주고
  • 코드 변경 사항(Git과 레저에 기록된 것)과 런타임 동작(로그 집계 시스템에 보이는 것)을 연결하기 쉬워지며
  • 운영 환경에서의 근본 원인 분석(RCA)이 훨씬 빨라집니다.

디버그 레저는 이렇게 하나의 피드백 루프가 됩니다. 개인적인 관찰이 더 나은 앱 로그 설계를 낳고, 개선된 로그는 다시 이후 디버깅 세션과 레저 기록을 더 효과적으로 만들어 줍니다.

마찰을 최소화하라: Plaintext, Markdown, 그리고 최소 도구

가장 좋은 시스템은 계속 쓰게 되는 시스템입니다. 습관을 유지하려면 마찰을 최대한 줄여야 합니다.

Plaintext 또는 Markdown 사용하기

Plaintext와 Markdown은 다음과 같은 장점이 있습니다.

  • 즉시 열리고
  • 어떤 에디터, 어떤 플랫폼에서도 잘 동작하며
  • grep 검색이나 전체 검색, 버전 관리를 하기 쉽고
  • 특정 서비스나 툴에 종속되지 않습니다.

루트 디렉터리에 debug-log.md 한 파일만 두어도 되고, logs/2026-01-04.md처럼 날짜별 파일을 만들어도 충분합니다.

방해 요소가 적은 툴 고르기

다음 조건을 만족하는 도구를 선택하세요.

  • 실행/열림 속도가 빠르고
  • UI가 단순하며
  • 서식이나 꾸미기에 빠져들 유혹이 적은 것

예시:

  • 단순 텍스트 에디터(VS Code, Vim, Sublime, Notepad++)
  • 최소 기능의 노트 앱
  • 로컬 우선(local-first) 혹은 셀프 호스팅 기반의 Markdown 지원 도구

목표는 기록 과정이 포스트잇에 휘갈겨 쓰는 것처럼 가볍게 느껴지게 하는 것이지, 폼을 채우는 과제가 되게 만드는 게 아닙니다.

일일 습관에서 검색 가능한 지식 베이스로

처음에는 디버그 레저가 그저 하루를 함께하는 동반자일 뿐입니다. 하지만 몇 주, 몇 달이 지나면 점점 더 커집니다. 어느새 검색 가능한 지식 베이스가 되어 있습니다.

시간이 지날수록 얻는 이점은 기하급수적으로 늘어납니다.

  • 특정 서비스나 라이브러리, 워크플로우에서 반복되는 패턴을 인지하게 되고
  • 예전에 해결했던 “그 이상한 직렬화(serialization) 버그”를 다시 겪어도, 같은 삽질을 반복하지 않고 곧장 해결법을 찾아낼 수 있으며
  • 팀에 새로 합류한 사람은 (공유 가능한 범위 안에서) 과거 로그를 훑어보는 것만으로 시스템의 현실적인 특이점과 함정을 빠르게 파악할 수 있습니다.

이를 강화하는 방법:

  • 하루 또는 일주일 단위로 파일을 나누어 탐색성을 높이고
  • 라벨과 섹션 헤더를 일관되게 사용하며
  • 가끔 큰 이슈나 배운 점을 요약 정리하는 섹션을 추가합니다.

이렇게 하면 처음에는 “그냥 끄적이는 메모”였던 것이, 어느 순간 가벼운 내부 위키로 진화합니다. 그것도 의도적으로 만든 것이 아니라, 사고하며 일한 결과물이 자연스럽게 쌓인 형태로 말이죠.

오늘 당장 시작하는 방법

디버그 레저의 효과를 보려면 대단한 도입 절차가 필요 없습니다. 다음 일주일 동안 이렇게 해 보세요.

  1. 파일 하나 만들기: logs/ 폴더 안에 debug-2026-01-04.md 같은 파일을 만듭니다.
  2. 하루를 시작할 때 [PLAN] 항목으로 오늘의 계획을 간단히 적습니다.
  3. 디버깅 중에는 의미 있는 가설, 실험, 수정이 있을 때마다 로그를 남깁니다.
  4. 컨텍스트를 전환할 때마다 무엇을 멈추고, 왜 멈추는지 짧게 적어 둡니다.
  5. 하루를 마무리할 때 오늘 마친 일, 남은 일을 간단히 요약합니다.

일주일이 지나면 스스로에게 물어 보세요.

  • 중단했던 작업을 다시 이어갈 때, 이 로그가 얼마나 시간을 절약해 줬는가?
  • 커밋 메시지, 티켓, 문서를 쓸 때 이 로그가 도움이 되었는가?
  • “이거 예전에 본 적 있는데…” 했던 순간들을 얼마나 더 빨리 해결할 수 있었는가?

답이 “조금이라도 그렇다”라면, 이 습관은 유지할 가치가 충분합니다.

결론

디버그 레저는 작지만 영향력이 큰 실천입니다.

  • 지저분하고 자주 끊기는 일을 추적 가능하고 이해 가능한 진행 과정으로 바꿉니다.
  • 컨텍스트와 결정을 보존해 유지보수성을 직접적으로 높입니다.
  • 이벤트 중심의 구조적 사고를 훈련시켜 더 나은 애플리케이션 로그를 만들게 합니다.
  • 시간이 흐르면서 개인(또는 팀) 지식 베이스로 성장합니다.

새로운 플랫폼이나 복잡한 프로세스, 멋진 플러그인이 필요하지 않습니다. 텍스트 파일 하나와, 자신의 일을 스스로에게 들려주는 짧은 내레이션을 남기겠다는 의지만 있으면 됩니다.

다음 디버깅 세션을 시작할 때, 새 로그 파일을 열고 한 줄만 적어 보세요. 타임스탬프와 지금 하려는 일. 그리고 계속해서 쓰면 됩니다. 미래의 당신, 그리고 당신의 팀이 그 기록에 고마워할 것입니다.

디버그 레저: 혼란스러운 디버깅 세션을 추적 가능한 진행 상황으로 바꾸는 단순한 러닝 로그 | Rain Lag