문서가 늘어난 저장소에서 링크가 깨지는 것을 막으려면, 링크 검사기 하나를 더 붙이기보다 「파일 목록과 색인을 양방향으로 대조하는 스크립트」를 커밋 훅에 거는 편이 낫습니다. 파일은 있는데 색인에 없는 경우와, 색인에는 있는데 파일이 없는 경우(유령 참조)를 따로 세고, 절마다 독립으로 짠 검사를 동시에 돌려서 하나라도 걸리면 종료 코드 1 로 알립니다.
AI 생성 이미지
지난 편에서 검사 스크립트를 시험하는 법을 다뤘습니다. 이번 편은 그 시험의 대상이 되는 검사 스크립트 본체, 무결성검사 이야기입니다.
폴더를 옮길 때마다 왜 어딘가가 끊어졌을까?
에이전트에게 주는 규칙 문서를 한 저장소에 모아 두고 쓰고 있습니다. 2026년 11월 12일에 세어 보니 docs/ 아래 마크다운이 186개, 단축 명령 문서가 75개, skill 이 23개였습니다. 이 정도가 되면 한 파일의 이름을 바꾸거나 폴더를 옮길 때 그 파일을 가리키던 곳이 어딘가 하나는 남습니다.
문제는 어디에 남았는지 눈으로는 찾기 어렵다는 점입니다. 색인 문서는 파일 이름을 글자로만 적어 두기 때문에, 파일이 사라져도 색인은 아무 오류 없이 그 이름을 계속 보여 줍니다. 읽는 쪽은 그 줄을 믿고 따라갔다가 없는 파일을 만납니다.
링크 검사기만으로는 왜 모자랐을까?
웹에서 「마크다운 링크 자동 검사」를 찾아보면 CI 에서 링크 검사 도구를 돌리는 방법이 대부분입니다(Lychee 의 GitHub 설정 안내, Docs-as-code 프로젝트의 링크 검사). 외부 주소 검사는 느리고 불안정해서, 네트워크 없이 내부 링크만 먼저 보는 도구를 소개한 글도 있었습니다.
제 경우에 필요했던 것은 조금 다른 검사였습니다. 색인이 마크다운 링크가 아니라 백틱으로 감싼 경로 표기로 파일을 가리키고, 「파일은 있는데 색인에 등록을 빠뜨렸다」는 반대 방향의 어긋남도 잡아야 했습니다. 그래서 이 저장소의 표기 규칙에 맞춰 직접 만든 검사를 쓰고 있습니다.
바꾼 방법: 양방향으로 세고 절마다 따로 짠다
핵심은 방향이 둘이라는 점입니다. 아래는 색인 대조 절의 핵심만 줄여 옮긴 것입니다.
index = read("docs/INDEX.md")
for path in md_files("docs"):
if path not in index: # 파일은 있는데 색인에 없음 -> WARN
warn("색인에 없음: " + path)
for ref in set(re.findall(r"`(docs/[\w./,-]+\.md)`", index)):
if not os.path.isfile(ref): # 색인에는 있는데 파일이 없음 -> FAIL
fail("유령 레퍼런스: " + ref)
등록을 빠뜨린 것은 경고, 없는 파일을 가리키는 것은 실패로 나눕니다. 이 절 말고도 심볼릭 링크가 기대한 곳을 가리키는지, skill 문서 머리글이 있는지, 단축 명령 표와 실제 명령 파일이 양방향으로 맞는지 같은 검사가 각각 한 절을 이룹니다. 2026년 11월 12일 기준으로 절 함수가 21개입니다.
절끼리는 서로 독립이라, 21개를 동시에 시작하고 출력만 번호 순서대로 모아 찍습니다.
SECTIONS = [s01, s02, s03] # 실제로는 21개
with ThreadPoolExecutor(max_workers=len(SECTIONS)) as pool:
futures = [pool.submit(fn) for fn in SECTIONS]
for fut in futures:
sec = fut.result()
print("\n".join(sec.lines), flush=True) # 출력은 절 번호 순서
total += sec.issues
return 1 if total else 0 # 경고·실패 모두 센다
이 검사는 원래 셸 스크립트였습니다. 첫 커밋은 2026년 7월 26일이고, 987줄까지 커진 것을 2026년 10월 22일에 파이썬으로 옮기면서 절 단위 병렬 실행으로 바꿨습니다. 같은 파일을 2026년 11월 12일에 세어 보니 1,194줄입니다.
훅에서만 틀린 결과가 나온 이유는?
커밋 훅 안에서 돌리면 git 이 환경 변수 GIT_DIR 같은 값을 넘겨 줍니다. 검사 안에는 다른 저장소나 임시 저장소를 대상으로 git 을 부르는 절이 있는데, 이 변수가 새어 들어가면 그 절이 엉뚱한 저장소를 보게 됩니다. 손으로 돌리면 문제가 없고 커밋 훅에서만 「발견된 문제 1건」이 나오는 증상이었고, 2026년 9월 29일에 재현해 원인을 찾았다고 스크립트 머리에 적어 두었습니다. 해결은 시작할 때 세 변수를 지우는 것이었습니다.
for _k in ("GIT_DIR", "GIT_INDEX_FILE", "GIT_WORK_TREE"):
os.environ.pop(_k, None)
지금 하루는 어떻게 달라졌을까?
폴더를 옮기거나 이름을 바꾸는 작업은 이제 「옮기고 → 검사 돌리고 → 걸린 곳 고치기」 순서입니다. 2026년 10월 27일과 28일에 스크립트·명령·skill 폴더를 단계별로 다시 나눴을 때, 세 번의 이동 커밋이 모두 이 검사 파일을 함께 고쳤습니다. 검사도 새 위치를 알아야 하기 때문입니다.
대가도 있습니다. 같은 날 전체를 한 번 돌려 보니 154.3초(2분 34초)가 걸렸고, 문제가 48건으로 나왔습니다. 색인 대조 말고도 낡은 문서나 규칙 줄 수 초과 같은 절이 함께 경고를 내기 때문입니다. 커밋 훅은 문제가 있어도 요약만 보여 주고 커밋은 계속 진행하며, 전체 목록은 스크립트를 직접 실행해서 봅니다.
자주 묻는 질문
링크 검사 도구를 두고 왜 직접 만들었나요?
검사해야 할 대상이 마크다운 링크가 아니라 백틱 경로 표기와 색인 표였고, 방향도 둘이었기 때문입니다. 「문서 안의 링크가 살아 있는가」만 보는 도구로는 색인 등록 누락까지 잡기 어려워서, 이 저장소의 표기에 맞춰 직접 대조하는 쪽이 간단했습니다.
경고를 실패와 왜 따로 세나요?
색인 등록을 빠뜨린 것은 문서를 읽는 데 바로 문제가 되지 않아 경고로 두고, 없는 파일을 가리키는 것은 읽는 사람을 막다른 길로 보내므로 실패로 둡니다. 둘 다 종료 코드에서는 문제로 세지만, 출력에서 구분해 두면 급한 것부터 고칠 수 있습니다.
검사를 병렬로 돌리면 출력이 섞이지 않나요?
각 절이 줄을 바로 찍지 않고 자기 안에 쌓아 두었다가 결과로 돌려주고, 메인이 절 번호 순서대로 꺼내 찍기 때문에 섞이지 않습니다. 느린 절이 있어도 앞 번호 절의 결과부터 순서대로 나옵니다.