코드 제거 작업의 grep 통과 조건과 문서 부패

코드 구조물을 지우는 작업에서 완료 기준을 "제거 대상 이름을 grep 하면 0건"으로 잡는 경우가 많다. 이 기준은 작업 목록이 실제로 고치는 파일 범위와 어긋나면 통과하지 못한다. 통과시켰다 해도, 제거한 구조물을 "지금 있는 것"으로 설명하는 문서가 그대로 남아 부패한다.

이 글은 제거 작업을 여러 단계로 나눠 진행할 때 생기는 두 가지 함정과 회피 방법을 정리한다. 특정 언어나 도구에 한정된 내용은 아니고, 클래스, 인스턴스, 엔드포인트 같은 구조물을 지우는 작업에 공통으로 적용된다.

grep 통과 조건이 작업 범위보다 넓을 때

제거 작업의 성공 기준을 grep -rn <심볼> 결과 0건으로 두면, 검색 범위가 곧 완료 범위가 된다. 작업 목록이 편집하는 파일보다 검색 범위가 넓으면, 편집 대상이 아닌 파일의 텍스트 참조가 통과를 막는다.

놓치기 쉬운 잔존 참조

• 제거 대상 심볼을 언급하는 모듈 docstring이 있다. 린터는 미사용 import 같은 코드 문제는 잡아도 docstring 안의 심볼 이름은 고쳐 주지 않는다. 그래서 자동 교정이 되지 않고 사람이 편집 작업으로 적어 두어야 한다.
• 한 단계가 지울 안내 문구를 다른 단계의 검증이 이미 검사하는 비대칭이 있다. 작업을 단계로 나누면 단계 A의 grep 이 단계 B가 아직 지우지 않은 파일까지 훑어 실패한다.

회피 방법

세 방법은 택일이 아니라 조합할 수 있다. 핵심은 "검증이 보는 범위"와 "작업이 고치는 범위"가 같은지 계획 단계에서 대조하는 것이다.

구조물을 지우면 문서 본문이 부패한다

class, 인스턴스, 엔드포인트를 제거하면 그것을 현재 존재하는 것처럼 서술하는 문서가 거짓이 된다. 코드는 테스트로 깨짐을 알 수 있지만 문서는 알려 주는 장치가 없어서 조용히 남는다. 특히 AI 에이전트가 문서를 컨텍스트로 읽고 작업하는 저장소에서는, 오래된 문서가 곧 잘못된 전제로 이어진다.

부패를 점검할 곳과 보존할 곳

ADR 과 changelog 는 "그때 그랬다"는 사실의 기록이라 부패가 아니다. 이것까지 현재 시점으로 고치면 결정의 근거와 이력이 지워진다.

예방

변경 유형별로 손대야 할 문서를 표로 정해 두고 설계 시점에 작업 목록에 반영한다. 예를 들어 "코드 구조물 제거"라는 변경 유형에는 위 점검 대상 세 종류를 묶어 둔다. 작업이 끝난 뒤에 찾는 것보다, 작업 목록을 만들 때 문서 편집을 같이 넣는 편이 누락이 적다.

정리

• 제거 작업의 grep 0건 기준은 작업이 편집하는 파일 범위와 맞춘다.
• 전역 0건 확인은 모든 제거 단계가 끝난 통합 검증 단계에 둔다.
• 구조물을 현재형으로 설명하는 문서는 부패 점검 대상이고, ADR 과 changelog 같은 시점 기록은 보존 대상이다.
• 변경 유형별로 손볼 문서를 표로 정해 설계 시점에 반영한다.