일괄 치환과 dry-run 으로 안 걸린 한 줄

파일 이름을 한글에서 영문으로 바꾸면 문서 안 링크가 옛 이름을 가리킨다. 2026-08-07 밤에 볼트 문서 안의 링크 453개를 일괄로 고쳤다. 파이썬으로 치환했고, dry-run 으로 바뀔 줄을 먼저 확인했다. 잘 끝난 줄 알았다.

한 줄이 이상해져 있었다. 하필 이 문제를 설명해둔 문장이었다.

"파일명을 영문화했는데 문서 안 링크는 [[00_허브]] 그대로다"

이 줄의 00_허브 까지 새 이름으로 바뀌었다. 그래서 "영문화했는데 링크는 [[00_hub]] 그대로다" 라는, 말이 안 되는 문장이 됐다.

한 곳뿐이라 고쳤다. 그리고 재발을 막으려고 규칙 파일에 항목을 하나 추가했다.

"일괄 치환은 그 이름을 설명하는 문장도 깨뜨린다. 백틱 안에 든 그 단어를 훑어라."

다음 날, 그 항목 자체가 같은 사고를 당했다

번호 규격을 바꾸느라(00_hub → 01_hub) 또 일괄 치환을 돌렸다. 어제 적어둔 예시 문장이 새 번호로 덮어써졌다. 규칙은 이렇게 남았다 — "00_허브→01_hub 로 고쳤더니". 어제 그런 일은 없었다. 없는 역사가 만들어졌다.

처음엔 내가 덜 조심했다고 생각했다. dry-run 을 보긴 봤는데 86개 rename 목록에 눈이 가 있었고, 그 아래 116개 파일의 링크 치환은 요약 숫자로만 봤다. 더 꼼꼼히 봤으면 걸렸을 것이다.

그런데 이 설명이 안 맞는다. 어제도 같은 생각을 했고, 그래서 규칙을 적었다. 규칙을 적은 다음 날 같은 일이 났으면 문제는 조심성이 아니다.

주의 문구는 내가 그 순간 떠올릴 걸 전제한다

치환을 돌리는 순간 머릿속에 있는 건 「바꿀 대상」이지 「그 대상을 설명한 문장」이 아니다. 설명 문장은 치환 목록에 따로 올라오지 않고, dry-run 출력에서도 다른 86줄과 똑같이 생겼다.

같은 병을 다른 자리에서 이미 겪었다. 「밖으로 나가는 글은 교정을 거친다」는 규칙이 만든 날 세 번 안 걸렸는데, 원인은 조건을 「내가 쓰는 글의 성격」 에 걸어놨던 점이었다. 글을 쓰는 동안엔 글 내용을 생각하지, 지금 배포용을 쓰고 있다는 자각은 안 온다. 그때 처방은 조건을 「내가 지금 무슨 명령을 치려 하는가」 로 옮기는 것이었다.

바꾼 것 — 주의에서 코드로

규칙에서 처방을 한 단계 올렸다. 「백틱 안을 훑어라」(주의)에서 「치환 스크립트에 백틱 보호를 넣어라」(코드) 로.

# 코드 표기(`...`)는 빼두고 치환한 뒤 되돌린다
held = re.sub(r"`[^`\n]*<대상>[^`\n]*`", hold, text)

사실 링크 치환 스크립트에는 이 보호가 이미 들어 있었다. 어제 사고 직후에 넣었다. 그런데 다음 날 번호 규격을 바꿀 땐 다른 스크립트를 새로 짰고 거기엔 안 넣었다. 보호는 스크립트에 붙어 있었지 규칙에 붙어 있지 않았다.

그래서 규칙 쪽에 코드 조각을 박아넣었다. 다음에 치환 스크립트를 짤 때 그 규칙을 읽으면 붙여넣을 게 있도록.

두 번째 사고가 첫 번째보다 값이 있었다. 첫 번째는 "치환이 문장을 깨뜨린다"만 알려줬는데, 두 번째는 "주의 문구를 적는 것으로는 안 막힌다" 를 보여줬다. 같은 규칙이 하루 만에 자기 자신에게 당했으니 반증할 여지가 없다.

규칙을 적을 때 한 번 물어볼 만하다 — 이건 내가 그 순간 떠올려야 걸리는 규칙인가, 아니면 도구가 대신 걸어주는 규칙인가.