Rain Lag

당신의 코드베이스에 숨겨진 할 일 목록: TODO를 진짜 로드맵으로 바꾸는 법

코드 곳곳에 숨겨진 TODO와 FIXME 주석은 사실 보이지 않는 작업 목록입니다. 자동화, 이슈 트래킹, 팀 워크플로우를 활용해 이 숨은 메모들을 눈에 보이는 우선순위 로드맵으로 전환하는 방법을 알아봅니다.

코드베이스에 숨겨진 할 일 목록: TODO를 진짜 로드맵으로 바꾸는 법

대부분의 엔지니어링 팀은 제대로 인지조차 하지 않는 조용한 백로그를 하나씩 안고 있습니다. 바로 코드 전반에 흩어져 있는 TODO, FIXME, 그리고 “나중에 개선하자” 같은 주석들입니다.

이런 작은 메모들은 그 순간에는 무해하고 도움이 되는 것처럼 느껴집니다. 하지만 시간이 지나면서, 버그·기술 부채·아이디어·반쯤 끝난 개선 작업들로 이루어진 보이지 않는 로드맵으로 쌓여갑니다. 문제는 아무도 이걸 체계적으로 추적하지 않는다는 점입니다.

이 글에서는 그 보이지 않는 백로그를 눈에 보이고, 우선순위가 매겨지고, 실제로 실행 가능한 로드맵으로 바꾸는 방법을 다룹니다. 그렇다고 팀을 복잡한 프로세스로 질식시키지는 않을 겁니다.

문제: 주석 속에 숨겨진 보이지 않는 일감

// TODO: optimize this 나 # FIXME: handle nulls properly 같은 인라인 주석은 일종의 프로젝트 관리 수단입니다. 다만, 별로 좋은 방식은 아닙니다.

왜 문제일까요?

  • 파일 밖에서는 안 보입니다: 그 특정 파일을 열어보지 않는 이상, 해당 작업은 어떤 계획 도구에도 존재하지 않는 것과 같습니다.
  • 우선순위가 없습니다: TODO: log errors 와 TODO: rewrite payment flow 는 주석에서는 똑같아 보이지만, 실제 영향도는 완전히 다릅니다.
  • 주인이 없습니다: 보통 주석에는 누가 맡을지, 언제까지 할지에 대한 정보가 없습니다.
  • 측정할 수 없습니다: 보이지 않는 TODO는 진행 상황을 추적할 수 없고, 그 사이 기술 부채는 조용히 불어나기만 합니다.

그렇다고 이런 주석이 쓸모없다는 뜻은 아닙니다. 오히려 이 안에는 이런 것들이 잘 담겨 있습니다.

  • 시간이 부족해 처리하지 못한 엣지 케이스
  • 빠르게 출시하기 위해 의도적으로 만든 기술 부채
  • 보안이나 성능에 대한 우려 사항
  • 제품 아이디어나 리팩터링 기회

목표는 TODO/FIXME 주석을 금지하는 것이 아닙니다. 목표는 이들을 체계적으로 끌어올려 정식 작업 항목으로 만드는 것입니다.

1단계: 보이지 않는 로드맵을 눈에 보이게 만들기

첫 단계는 인식입니다. 주석을 데이터로 취급해야 합니다.

1.1. 코드베이스 전체에서 TODO/FIXME 검색하기

먼저 단순한 크로스 리포지토리 검색부터 시작해 보세요.

  • 코드 검색 도구(예: GitHub, GitLab, Sourcegraph, ripgrep 등)를 이용해 다음을 검색합니다.
    • TODO
    • FIXME
    • 팀에서 사용한다면 XXX, HACK 등
  • 이 검색을 모든 리포지토리에 걸쳐 실행해, 조직 전체에 잠재된 작업을 드러냅니다.

이 작업만으로도 꽤 충격을 받을 수 있습니다.

  • TODO가 총 몇 개나 있나요?
  • 어느 서비스·모듈·언어에 특히 몰려 있나요?
  • 주석만 봐도 보안이나 안정성 측면에서 위험해 보이는 것들이 있나요?

1.2. 발견한 TODO를 카테고리로 묶기

검색하다 보면 자연스럽게 패턴이 보이기 시작합니다. 대부분의 TODO는 다음과 같은 범주 중 하나에 들어갑니다.

  • 버그 및 정확성: FIXME: off-by-one when month changes
  • 기술 부채 및 리팩터링: TODO: extract this into a separate service
  • 성능 및 확장성: TODO: avoid full table scan
  • 보안 및 컴플라이언스: TODO: sanitize user input here
  • 개발자 경험(DX): TODO: improve error messages
  • 제품 및 기능 아이디어: TODO: support bulk operations

이런 카테고리는 나중에 우선순위를 정하거나, 적절한 팀에 일을 라우팅할 때 큰 도움이 됩니다.

2단계: 주석을 자동으로 이슈로 전환하기

TODO 하나하나를 사람이 일일이 티켓으로 옮기는 건 비현실적이고 고된 작업입니다. 대신, “주석 → 로드맵” 플로우를 자동화하세요.

2.1. CI나 GitHub Actions로 TODO 추출하기

자동화는 대략 이런 일을 하게 만들 수 있습니다.

  1. 일정 주기(예: 매일 밤)나 main 브랜치 변경 시, 코드베이스에서 TODO/FIXME를 스캔합니다.
  2. 주석과 메타데이터(파일, 라인, 작성자, 타임스탬프, 주변 코드)를 파싱합니다.
  3. 추출한 내용을 기반으로 이슈 트래커(GitHub Issues, Jira, Linear 등)에 이슈를 생성하거나 갱신합니다.

최소한 스크립트나 액션이 수집해야 할 정보는 다음과 같습니다.

  • 주석 내용 텍스트
  • 파일 경로 및 라인 번호
  • 리포지토리 이름
  • 커밋 해시(당시의 히스토리 컨텍스트로 바로 이동할 수 있게)

예: 자동 파싱에 적합하게 포맷된 TODO 주석:

// TODO[security][P1]: Validate JWT audience claim before using it

이 주석은 다음과 같은 이슈로 변환될 수 있습니다.

  • 이슈 제목: “Validate JWT audience claim before use”
  • 라벨: security, priority:high
  • 소스 파일로 돌아갈 수 있는 링크 포함

2.2. 중복 이슈 방지하기

이슈 트래커가 도배되는 것을 막으려면 다음과 같은 전략이 필요합니다.

  • 이슈 본문에 해당 주석 위치(파일·라인·커밋)를 식별할 수 있는 정보를 함께 저장합니다.
  • 이후 스캔 시, 동일한 주석에 대해 이미 생성된 이슈가 있는지 먼저 확인한 뒤, 없을 때만 새로 만듭니다.

이렇게 하면 이슈 트래커는 단일 소스 오브 트루스가 되고, 코드 주석은 로컬 컨텍스트 역할을 계속 유지할 수 있습니다.

3단계: TODO를 워크플로우의 1급 시민으로 만들기

TODO와 FIXME가 이슈로 전환되는 순간, 이들은 더 이상 배경 소음이 아니라 관리 가능한 작업이 됩니다.

3.1. 담당자 지정, 추정, 우선순위 부여

각 TODO/FIXME가 이슈가 되면 이제 다음과 같은 일들을 할 수 있습니다.

  • 담당자 지정: “언젠가 누군가 고치겠지”에서 “누가 언제까지 할지”로 바뀝니다.
  • 컨텍스트 추가: 관련 인시던트, PR, 문서 등을 링크합니다.
  • 영향도 평가: 보안 이슈인지, UI 다듬기인지, 성능 개선인지 구분합니다.
  • 기능 개발과 함께 같은 보드에서 우선순위 비교

팀은 의도적으로 다음을 선택할 수 있게 됩니다.

  • 각 스프린트에 어떤 TODO를 포함할지
  • 주요 릴리스 전에 어떤 고위험 FIXME를 반드시 처리할지
  • 어떤 기술 부채를 관련 기능 개발과 함께 묶어 처리할지

3.2. CI/CD 파이프라인에 통합하기

TODO/FIXME 관리를 파이프라인과 더 강하게 연결할 수도 있습니다.

  • 특정 태그에 대해 빌드를 실패·경고 처리: 예를 들어, 새로운 FIXME[security] 주석이 추가되면 머지를 막도록 할 수 있습니다.
  • 기술 부채 예산 관리: 스프린트 용량 중 주석 기반 이슈에 사용한 비율을 추적합니다.
  • 추세 모니터링: TODO/FIXME 기반 오픈 이슈 개수를 시간에 따라 추적해 건강성 지표로 활용합니다.

이렇게 하면 기술 부채를 더 이상 부가적인 문제로 취급하지 않고, 측정 가능하고 관리되는 엔지니어링의 한 부분으로 만들 수 있습니다.

4단계: 노이즈를 줄이는 정기적인 트라이아지

모든 TODO가 영원히 이슈로 남을 가치가 있는 것은 아닙니다. 이미 의미가 없어졌거나, 모호하거나, 더 이상 관련 없는 것들도 많습니다.

4.1. 트라이아지 리듬 만들기

다음과 같은 정기적인 의식을 도입해 보세요.

  • 팀별 월간 TODO/FIXME 검토 회의
  • 분기별 크로스 리포 보안·신뢰성 점검

각 세션에서 팀은 다음을 수행합니다.

  • 코드가 이미 크게 바뀐 경우, 의미를 잃은 이슈를 닫습니다.
  • 너무 모호한 주석은 구체적이고 실행 가능한 티켓으로 다시 작성합니다.
  • 현재 로드맵과 최근 인시던트를 기준으로 우선순위를 재조정합니다.
  • 관련된 항목들을 하나의 큰 리팩터링/개선 에픽으로 묶습니다.

4.2. 인시던트 및 버그 리포트와 연결하기

인시던트 리뷰(사후 분석)를 진행할 때마다 다음을 수행해 보세요.

  • 영향받은 코드 영역 안에서 TODO/FIXME를 검색합니다.
  • 관련 있는 주석 기반 이슈를 해당 인시던트에 링크합니다.
  • 인시던트에 기여했거나, 유사 사고를 예방할 수 있는 TODO의 우선순위를 상향 조정합니다.

이렇게 하면 잠재된 작업과 실제 사고 사이의 연결 고리가 단단해져, 회귀를 줄이고, 트라이아지를 더 데이터 기반으로 만들 수 있습니다.

5단계: 크로스 리포 검색으로 조직 전체 가시성 확보하기

코드베이스가 여러 서비스와 리포지토리로 확장되면, TODO와 FIXME는 중요한 시스템적 문제의 신호가 될 수 있습니다.

크로스 리포 코드 검색을 활용해 다음과 같은 질문에 답해 보세요.

  • 모든 서비스 전체에 보안 관련 TODO가 몇 개나 있는가?
  • 어떤 리포가 FIXME 주석으로 가장 포화 상태인가?
  • 여러 서비스에 걸쳐 같은 문제(예: 에러 처리, 피처 플래그, 인증 플로우)에 대한 TODO가 흩어져 있지는 않은가?

조직 전체 관점에서 보면 다음과 같은 일을 할 수 있습니다.

  • 기술 부채·위험이 집중된 핫스팟을 찾아냅니다.
  • 대규모 리팩터링이나 플랫폼 투자에 대한 근거를 마련합니다.
  • 단일 리포 수준에서는 보이지 않는 패턴을 포착합니다.

이걸 앞서 말한 자동화와 결합하면, 크로스 리포 검색 결과를 크로스 리포 이슈 생성으로 이어 붙여 조직 전체 잠재 작업에 대한 포트폴리오 뷰를 만들 수 있습니다.

이 흐름을 정착시키는 실용적인 규칙들

“주석 → 로드맵” 플로우를 규모 있게 운영하려면 가벼운 규칙 몇 가지만 도입해도 큰 도움이 됩니다.

  1. 구조화된 TODO 포맷 사용

    • 예: // TODO[area][priority]: 구체적이고 실행 가능한 설명
    • area 예시: security, perf, ux, refactor, infra 등

  2. 이미 이슈가 있으면 연결 링크 남기기

    • // TODO: see ISSUE-1234 for full context
    • 자동화 도구는 이런 TODO는 건너뛰게 할 수 있습니다(이미 이슈가 존재하므로).

  3. 언제 TODO/FIXME를 남길지에 대한 가이드라인

    • 실제로 처리할 가능성이 높은 작업에만 TODO/FIXME를 사용합니다.
    • 막연한 아이디어나 실험적인 생각은 문서나 제품 백로그에 남기는 편이 낫습니다.

  4. PR 체크 도입

    • 라벨이나 컨텍스트 없이 새 TODO를 추가하면 워닝을 띄우도록 만들 수 있습니다.

이런 간단한 습관만으로도 주석 기반 작업의 신호 품질을 크게 높일 수 있습니다.

효과: TODO를 진짜 작업으로 다룰 때 얻는 이점들

TODO와 FIXME를 1급 시민으로 다루기 시작하면, 시간이 갈수록 여러 가지 이점이 쌓입니다.

  • 더 빠르고 의도적인 기술 부채 상환
    • 기술 부채가 더 이상 추상적인 개념이 아니라, 담당자와 우선순위가 있는 백로그가 됩니다.
  • 회귀 및 프로덕션 사고 감소
    • 영향도가 큰 FIXME가 코드 구석 어딘가에 방치되지 않습니다.
  • 코드 품질의 지속적인 개선
    • TODO가 “청소 주간”에만 처리되는 게 아니라, 평소 계획의 일부로 꾸준히 해결됩니다.
  • 코드와 로드맵 간의 정렬 강화
    • 엔지니어가 코드에서 보는 작업과 보드에서 보는 작업이 점점 일치하게 됩니다.
  • 조직 전체 위험 가시성 향상
    • 리더십은 보안·성능·신뢰성 위험이 어디에 집중되어 있는지 한눈에 볼 수 있습니다.

무엇보다도, “언젠가 정리하자”는 반응적인 부채 관리에서 벗어나, 선제적이고 측정 가능한 접근 방식으로 옮겨갈 수 있습니다.

결론: 속삭이듯 적힌 메모를 진짜 계획으로 바꾸기

당신의 코드베이스에는 이미 어디가 아프고, 어디가 취약하고, 어디를 개선해야 할지에 대한 대략적인 지도가 들어 있습니다. 그 지도는 TODO, FIXME, HACK 같은 작고 쉽게 무시되는 주석들 속에 암호처럼 숨어 있습니다.

이 메모들을 제자리에 방치해 썩게 두는 대신, 다음과 같이 다뤄 보세요.

  1. 크로스 리포 검색으로 드러내기
  2. CI나 GitHub Actions로 자동 캡처해 이슈로 만들기
  3. 계획·담당·우선순위에서 1급 시민으로 대우하기
  4. 정기적인 리뷰와 트라이아지로 신호 품질 유지하기

이 흐름을 잘 구축하면, “보이지 않던 할 일 목록”은 강력하고 살아 있는 로드맵으로 변모합니다. 그 로드맵은 기술 부채 상환 속도를 높이고, 위험을 줄이며, 여러분이 배포하는 소프트웨어의 품질을 꾸준히 끌어올리는 데 도움을 줄 것입니다.

당신의 코드베이스에 숨겨진 할 일 목록: TODO를 진짜 로드맵으로 바꾸는 법 | Rain Lag