6개로 적힌 표의 7행: 문서 수치의 정적 검증
내가 만드는 건 한국 웹소설 집필용 Claude Code 플러그인이다. 그 문서에 이런 줄이 있었다.
"필력이 부족하다"는 진단이 아니다. 위 6개 중 하나로 좁혀라.
바로 위에 표가 있다. 순서 0, 1, 2, 3, 4, 5, 6. 일곱 행이다.
세어 보면 문장과 안 맞는다. 그런데 이 문장은 여섯 번의 릴리스를 통과해 나갔다. 자동 검사 아홉 종, 반영 후 자기검증, 독립 검토 레인 — 전부 통과했다.
처음엔 원인을 잘못 짚었다
패치노트에 이렇게 적었다. 「v1.0.0 에서는 참이었고, v1.1.0 에서 표에 행이 하나 늘면서 거짓이 됐다.」 그럴듯했다. 목록이 자라면 그 목록을 세는 문장은 조용히 거짓이 된다 — 교훈이 깔끔하게 떨어진다.
반영분을 커밋하고 독립 검토 레인 두 개를 띄웠다. 한 레인이 git show 97ebec7 을 돌렸다.
표는 최초 커밋부터 일곱 행이었다. v1.1.0 이 한 일은 행 0 과 1 의 이름을 바꾼 것뿐이다. 문장은 처음부터 「6개」였다.
목록이 늘어 거짓이 된 게 아니다. 쓸 때 세지 않았고, 그 뒤로도 아무도 세지 않았다.
증상은 내가 직접 확인했다 — 표를 세어 봤으니까. 원인은 확인하지 않았다. 앞선 검토에서 한 에이전트가 그 이력을 틀리게 보고했고, 나는 그것을 그대로 받았다. 그럴듯했기 때문이다.
거짓 문장을 막겠다는 릴리스의 진단이 거짓이었다.
규칙은 있었다
「개수를 세는 문장을 쓰지 마라」는 우리 저장소 문서에 이미 있었다. 반영 후 확인 절차에도 「개수를 세는 문장이 이번 변경으로 틀려졌는가」가 항목으로 들어 있었다.
규칙도 있었고 확인 절차도 있었다. 여섯 릴리스 동안 아무도 안 걸렸다.
문제는 규칙의 문장이었다. 「이번 변경으로 틀려졌는가」. 새로 쓰는 문장과 이번에 건드린 문장만 본다. 이미 있던 거짓말은 영원히 검토 범위 밖이다.
더 나쁜 것도 있다. v1.1.0 에서 우리는 CI 설정의 「(30단계)」라는 표기를 「검사 추가 때마다 어긋난다」는 이유로 지웠다. 같은 부류의 문장을 실제로 하나 지우면서, 같은 트리 안의 다른 문장은 안 봤다.
그래서 검사로 옮겼다
검사가 보는 건 둘이다.
선언과 항목을 대조한다. 제목이나 강조가 수를 선언하고 그 절에 목록이 있으면 센다. 번호 목록이 있으면 그것을, 없으면 표의 데이터 행을, 없으면 불릿을.
그리고 앞 목록을 수로 되받는 형태를 막는다. 「위 N개」, 「앞의 N항목」, 「총 N가지」. 지금 참이어도 막는다. 목록이 늘면 아무도 그 문장을 고치러 오지 않으니까 — 방금 확인한 그대로다.
검사를 넣고 원래 버그를 되돌려 물리는지 확인했다. 통과하는 것만으로는 아무것도 증명되지 않는다. 검사가 초록인데 결함이 남아 있는 상태가 규칙만 있던 상태보다 나쁘다. 초록이 다음 판단의 근거가 되기 때문이다.
검사를 만들면서 배운 것
첫 판은 오탐이 열넷 나왔다. 「결정이 20개를 넘어가면」의 이 를 지시어로 읽었다.
한국어 조사다.
두 번째 판은 「1단계」, 「2-1.」, 「최대 3개」를 개수 선언으로 읽었다. 서수와 수식어다.
세 번째 판은 「프로젝트 두 종류」 아래의 비교표를 틀렸다고 했다. 그 표는 종류가 열이고 행은 속성이다.
오탐을 내는 검사는 결국 꺼진다. 그래서 좁혔고, 좁힐 때마다 진짜 우회 경로가 늘었다. 독립 검토 레인이 그 경로를 실측으로 냈다 — 「위 13개」(1로 시작하는 수를 정규식이 빼먹었다), 「위 여섯 행」(단위 목록에 「행」이 없었다. 사고가 난 그 단어다), 「총 다섯 단계」(지시어가 없다).
넓히자 일곱 번째 거짓 문장이 나왔다. 다른 파일에서 「검사 3종」이라고 적고 표에 넷을 나열하고 있었다. 바로 아래 문장이 「마지막 항목이 중요하다」로 넷째를 가리킨다.
남은 것
이번 릴리스에서 자동 검사가 못 잡고 사람이 잡은 것이 셋이다. 전부 독립 검토 레인이 잡았고, 전부 「인용한 파일과 줄을 열어 확인하라」를 실제로 실행해서 잡았다.
반대로 검토자가 틀린 것도 셋이었다. 「고친 문장들은 새 검사가 못 잡는다」(넷 다 잡힌다), 「이 제목이 13종인데 12라고 적혀 거짓이다」(표는 하위 항목 12행이라 참이다), 「이 게이트를 새로 만들어라」(같은 게이트가 이미 있었다).
인용한 줄을 열지 않았으면 셋 다 새 결함이 됐을 것이다. 그래서 규약에 한 줄을 넣었다 —
검토자의 이력 주장은 git 으로 확인한 뒤 반영한다.
이번에 그걸 안 해서 릴리스 노트에 거짓을 실을 뻔했다.
webnovel-toolkit v1.5.1 작업 기록. 이 툴킷이 무엇인지는
네 번의 릴리스에서 배운 것에 적어 뒀다.