📝 한줄 요약
지식체계(논문 10편 + 개념 페이지)가 SCHEMA 규칙을 잘 지키고 있는지 확인하는 점검 명령(npm run lint:knowledge)을 만들었어요. 만들고 나서 “잘 통과하네” 하고 끝내는 대신 코드 리뷰를 요청했더니, 제 점검 도구가 놓치고 있던 실제 버그 — 논문 3편이 개념 페이지로 링크를 걸었는데 개념 페이지에서는 그 논문들로 돌아오는 링크가 없던 것 — 가 나왔어요. 점검 항목을 하나 더 추가해서 다시 잡아내고, 데이터도 고쳤어요.
바쁘시면 이것만 읽어도 돼요:
- “링크가 안 끊겼는지”와 “링크가 규칙대로 양방향으로 걸려 있는지”는 완전히 다른 검사예요. 하나를 검사한다고 다른 하나도 저절로 확인되는 게 아니에요.
- 자동 점검 도구를 만들고 나면, 그 도구 자체가 맞게 짜였는지도 검증해야 해요 — 일부러 틀린 데이터를 넣어보는 게 제일 확실해요.
- AI에게 “이거 다 됐어?”가 아니라 “허술한 데 없어? 제일 효과 큰 거부터 짚어줘”라고 물으면, 더 구체적이고 우선순위 있는 답이 와요.
Before — 왜 점검 도구가 필요했나
논문 노트 10편과 개념 페이지 1개를 만들고 나니, SCHEMA.md에 정해둔 규칙(빈 칸 없이 7항목 채우기, 원문에 없는 문장 인용 금지, 위키링크 양방향 연결)을 매번 사람 눈으로 확인하기가 버거워졌어요. 다음에 논문을 더 넣을 때마다 이걸 매번 손으로 확인할 순 없으니, 한 번 명령으로 문제 목록이 나오는 도구가 세부계획 7단계에 이미 정해져 있었어요.
과정 — 만들고, 테스트하고, 리뷰 요청하고, 실제 버그를 찾음
1단계 — lint 명령 만들기
knowledge/lint.mjs를 만들어서 세 가지를 검사하게 했어요: 빈 항목, 끊긴 링크, 원문에 없는 인용. npm run lint:knowledge 한 줄이면 돌아가게 했고요.
2단계 — 진짜 작동하는지 가짜 오류로 테스트
만들었다고 믿지 않고, 일부러 문제 4개를 심은 가짜 논문 파일을 넣어봤어요.
npm run lint:knowledge
## 빈항목 (1건)
- 2099-test-broken.md — '## 6. 한계' 항목이 비어있음
## 끊긴링크 (1건)
- 2099-test-broken.md — /papers/no-such-paper 대상 페이지 없음
## 인용확인필요 (1건)
- 2099-test-broken.md — 원문에서 못 찾음: "이건 원문에 절대 없는 지어낸 문장이다..."
총 3건 발견.
넷 다 잡혔어요. 실제 논문 10편으로 돌리니 문제 0건 — 여기까지는 순조로웠어요.
3단계 — “허술한 데 없어?” 라고 리뷰 요청
여기서 멈추지 않고 이렇게 물었어요:
“지금까지 만든 걸 봐줘. 돌아가긴 하는데 어딘가 허술한 것 같아. 어디가 부족한지 짚어주고, 그중 지금 고치면 제일 효과 큰 것부터 알려줘.”
돌아온 답 중 1순위가 뜻밖이었어요 — **“링크가 죽었는지 확인하는 것과, 링크가 SCHEMA §7의 양방향 규칙을 지키는지 확인하는 것은 다른 검사인데, lint가 후자를 아예 안 보고 있다”**는 지적이었어요. 그리고 실제 데이터를 확인해보니 진짜로 깨져 있었어요: BNNT 벽수제어·수질정화·오소리기름 세 논문이 “TEM 관찰” 개념 페이지로 링크를 걸었는데, 그 개념 페이지의 “어느 논문에서 나왔나” 절에는 4편만 있고 이 셋이 빠져 있었던 거예요.
4단계 — 검사 항목 추가하고, 데이터도 고침
lint에 양방향 링크 검사(④ 일방통행)를 추가했더니 정확히 그 3건이 잡혔고, 개념 페이지에 빠진 역링크 3개를 채워 넣고 나서 다시 돌리니 문제 0건이 됐어요.
After — 뭐가 달라졌나
| Before | After | |
|---|---|---|
| lint 검사 항목 | 3가지 (빈항목·끊긴링크·인용) | 5가지 (+ 일방통행 링크, + 원본 frontmatter 대조) |
| 개념 페이지 역링크 | 4편만 연결 (3편 누락, 아무도 모르던 상태) | 7편 전부 양방향 연결 |
| ”점검 통과”의 의미 | ”링크가 안 끊겼다”만 보장 | ”규칙대로 쌍을 이룬다”까지 보장 |
배운 것
점검 도구가 있다는 사실 자체가 안심의 근거가 되면 안 돼요. “lint를 돌렸는데 통과했다”는 말은 “그 lint가 보는 항목에 한해서” 문제가 없다는 뜻일 뿐, 애초에 lint가 안 보는 종류의 문제는 여전히 숨어 있을 수 있어요. 제가 처음 만든 lint는 “링크가 존재하는가”만 봤지 “링크가 규칙대로 쌍을 이루는가”는 안 봤고, 그 틈에 실제 버그가 몇 시간째 숨어 있었어요.
“다 됐어?” 대신 “허술한 데 짚어줘, 효과 큰 것부터”라고 물으니 답이 달라졌어요. 그냥 검토해달라고 하면 막연한 칭찬으로 끝나기 쉬운데, 우선순위를 매겨 달라고 구체적으로 물으니 실제로 고칠 가치가 있는 지점을 순서대로 받을 수 있었어요.
재사용 자산 — 내가 만든 점검 도구를 다시 점검하는 체크리스트
- 검사 항목마다 “이게 정확히 뭘 보고, 뭘 안 보는지” 한 줄로 적어볼 수 있나요? (못 적으면 항목이 애매한 거예요)
- 일부러 틀린 데이터를 만들어서 진짜로 잡히는지 테스트했나요?
- “링크/참조가 존재하는가”와 “그 관계가 규칙대로 완전한가(양방향, 필수 항목 등)“를 따로 구분해서 검사하고 있나요?
- 만든 뒤 “허술한 데 없어?”라고 다시 검토를 요청했나요? (같은 사람/AI가 만든 그대로 “됐다”고 끝내지 않기)
- 리뷰에서 나온 지적을 실제 데이터로 확인해봤나요? (짚어준 게 진짜 버그인지, 우려일 뿐인지는 확인해야 알아요)