AX 팁 18 — 깨진 링크와 유령 참조를 한 번에 잡는 검사

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • 무결성 검사

문서가 늘어난 저장소에서 링크가 깨지는 것을 막으려면, 링크 검사기 하나를 더 붙이기보다 「파일 목록과 색인을 양방향으로 대조하는 스크립트」를 커밋 훅에 거는 편이 낫습니다. 파일은 있는데 색인에 없는 경우와, 색인에는 있는데 파일이 없는 경우(유령 참조)를 따로 세고, 절마다 독립으로 짠 검사를 동시에 돌려서 하나라도 걸리면 종료 코드 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 commit → pre-commit 훅이 검사 호출; pre-commit 훅이 검사 호출 → 21개 절을 동시에 실행; 21개 절을 동시에 실행 → 절 번호 순서로 출력 모으기; 절 번호 순서로 출력 모으기 → 경고·실패가 하나라도 있나?; 경고·실패가 하나라도 있나? → 종료 코드 0 (없음); 경고·실패가 하나라도 있나? → 종료 코드 1, 건수 출력 (있음)없음있음git commitpre-commit 훅이 검사호출21개 절을 동시에 실행절 번호 순서로 출력모으기경고·실패가 하나라도있나?종료 코드 0종료 코드 1, 건수 출력
커밋 한 번이 거치는 무결성검사 — 훅은 문제를 요약해 보여 주지만 커밋은 막지 않는다

훅에서만 틀린 결과가 나온 이유는?

커밋 훅 안에서 돌리면 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 폴더를 단계별로 다시 나눴을 때, 세 번의 이동 커밋이 모두 이 검사 파일을 함께 고쳤습니다. 검사도 새 위치를 알아야 하기 때문입니다.

어긋남을 알아채는 방식검사 이전: 색인을 눈으로 다시 읽어 확인, 같은 문제를 여러 번 수동으로 재발견 → 검사 이후: 커밋 때마다 21개 절이 자동으로 대조, 경고·실패 건수가 종료 코드로 남음검사 이전색인을 눈으로 다시읽어 확인같은 문제를 여러 번수동으로 재발견검사 이후커밋 때마다 21개 절이자동으로 대조경고·실패 건수가종료 코드로 남음
어긋남을 알아채는 방식

대가도 있습니다. 같은 날 전체를 한 번 돌려 보니 154.3초(2분 34초)가 걸렸고, 문제가 48건으로 나왔습니다. 색인 대조 말고도 낡은 문서나 규칙 줄 수 초과 같은 절이 함께 경고를 내기 때문입니다. 커밋 훅은 문제가 있어도 요약만 보여 주고 커밋은 계속 진행하며, 전체 목록은 스크립트를 직접 실행해서 봅니다.

자주 묻는 질문

링크 검사 도구를 두고 왜 직접 만들었나요?

검사해야 할 대상이 마크다운 링크가 아니라 백틱 경로 표기와 색인 표였고, 방향도 둘이었기 때문입니다. 「문서 안의 링크가 살아 있는가」만 보는 도구로는 색인 등록 누락까지 잡기 어려워서, 이 저장소의 표기에 맞춰 직접 대조하는 쪽이 간단했습니다.

경고를 실패와 왜 따로 세나요?

색인 등록을 빠뜨린 것은 문서를 읽는 데 바로 문제가 되지 않아 경고로 두고, 없는 파일을 가리키는 것은 읽는 사람을 막다른 길로 보내므로 실패로 둡니다. 둘 다 종료 코드에서는 문제로 세지만, 출력에서 구분해 두면 급한 것부터 고칠 수 있습니다.

검사를 병렬로 돌리면 출력이 섞이지 않나요?

각 절이 줄을 바로 찍지 않고 자기 안에 쌓아 두었다가 결과로 돌려주고, 메인이 절 번호 순서대로 꺼내 찍기 때문에 섞이지 않습니다. 느린 절이 있어도 앞 번호 절의 결과부터 순서대로 나옵니다.

사이트를 만들어볼까요?

무료 상담 받기