CLAUDE.md의 「정본 경로 지도」는 조용히 거짓말이 된다

에이전트용 지시 파일(CLAUDE.md / AGENTS.md)을 키워나가다 보면, 대개 정본 경로(Source of Truth Path) 표가 만들어집니다.

이 표는 "추측해서 Read 하지 말고, 여기를 봐라"라는 계약입니다. 그런데 디렉터리를 하나 리네임하면, 계약은 그 순간부터 거짓말이 됩니다. 게다가 아무것도 망가지지 않습니다. 테스트는 산문(prose)을 검사하지 않기 때문입니다.

곤란해지는 것은 다음에 그 표를 읽는 에이전트이며, 경로를 찾지 못하면 추측을 시작합니다. 추측된 경로는 이미 가지고 있는 것의 복사본이 하나 더 늘어나는 경로 그 자체입니다.

한 일: 표 자체를 검사 대상으로 만들기

읽기 전용 스크립트 1개(282행·의존성 없음)를 작성했습니다. 중심이 되는 것은 하나의 검사로, 지정한 헤더(heading) 아래에 있는 표를 읽고, 제2열의 백틱(backtick) 안의 경로가 실재하는지 Test-Path 하는 것뿐입니다.

<project>나 *.jsonl을 포함하는 행은 "파일이 아니라 형태"를 적고 있는 것이므로 스킵하며, 스킵 건수는 반드시 1행 출력합니다(가만히 넘어가면 "전부 통과했다"라고 보일 수 있기 때문입니다). 같은 메커니즘으로, 권장되지 않음(deprecated) 배너(앞쪽 12행에 "비권장"이 남아있는지)도 검사하고 있습니다.

실측: 표에 2행을 추가했더니, 검사가 2건 늘어났다

이것이 이번에 가장 효과를 본 성질이었습니다.

• 2026-07-31 (최초):
  20 checks / 0 fail / 0.3s
• 2026-08-03 (오늘):
  22 checks / 0 fail / 0.3s

그 사이에 무엇을 했느냐 하면, 정본 경로 지도에 행을 2개 추가했을 뿐입니다. 검사 코드는 한 글자도 쓰지 않았습니다. 주장을 적는 장소와 검사의 대상이 동일하기 때문에, 문서를 업데이트하는 순간에 검사 항목이 늘어납니다. 문서 검사를 별도 파일로 관리하면 그 별도 파일 자체가 드리프트(drift)하게 되는데, 이 방식은 그것을 방지해 줍니다.

설계에서 효과를 본 한 가지: 먼저 퇴각선을 적는다

이런 종류의 검사는 오검출(false positive)이 계속되면 아무도 보지 않게 되어 끝납니다. 그래서 도입 시에 "오검출이 누적 3회 발생한 해당 어서션(assertion)은 삭제한다", "전체가 30초를 초과하면 축소한다"를 먼저 결정하여 README에 적었습니다. 신뢰받지 못하는 검사는 검사가 없는 상태보다 나쁘기 때문입니다.

현재 시점에서 오검출은 0건입니다.

재현 절차

git clone https://github.com/yuka-repos/ops-assert.git
cd ops-assert
pwsh -NoProfile -File check-ops-assertions.ps1

동봉된 설정이 repo 자신의 example/를 검사하므로, clone 직후에 green(성공) 상태가 됩니다. 망가지는 쪽도 확인할 수 있습니다.

pwsh -NoProfile -File check-ops-assertions.ps1 -ConfigPath example/broken.json
# FAIL: ... tools/moved-away.ps1 does not exist
# ops-assert: 3 checks, 2 fail, 0.3s (exit 1)

자신의 repo에 적용할 때는 ops-assert.json의 root와 헤더의 정규 표현식을 바꾸기만 하면 됩니다. PowerShell 7 전용·의존성 없음·읽기 전용·통신 없음. MIT 라이선스입니다.

Discussion