검증 스크립트가 있는데도 왜 계속 빠뜨렸을까 — 위키 관리 Skill 쪼개기

위키 관리의 문제점과 목표

퇴사를 앞두고 마케팅·MD 실무를 후임에게 넘기려고 로컬 마크다운 위키를 만들고 있습니다. Johnny Decimal 번호 체계로 93개 문서가 쌓였고, 문서를 추가할 때 지켜야 할 절차를 wiki-add라는 Skill 하나에 다 넣어 뒀습니다.

그런데 이 Skill에는 제가 직접 써넣은 문장이 하나 있습니다.

"## 4. 갱신 3종 세트 (여기서 자주 빠뜨린다)"

자주 빠뜨린다는 걸 알고 있었습니다. 그래서 5단계에 파이썬 검증 스크립트까지 붙여 놨고요. 그런데도 계속 빠뜨렸습니다. 2주차 목표는 여기서 시작했습니다 — 왜 검증기가 있는데도 계속 새는지.

시작 전 위키 상태

• wiki-add.md 한 파일에 절차 0~7단계가 전부 들어 있음 (5,791 bytes)

• 5단계에 링크 검증 파이썬 스크립트 내장. "깨진 링크 0개 나올 때까지 고쳐"라고 명시

• 실행 이력은 작업일지(00.03) 245행에 2주치 누적

• 막연한 불안: 뭔가 빠지는 것 같은데 뭐가 빠지는지 특정을 못 함

W1 Skill과 사본 경계 설정

• 대상: ~/.claude/commands/wiki-add.md

• 원본은 읽기 전용으로 두고 분해 산출물은 전부 별도 폴더(GPTERS-W2-과제/)에 만들었습니다.

• 실행 리허설은 위키를 /tmp에 사본으로 뜬 뒤 거기서만 했습니다. 실제 위키는 한 글자도 바뀌지 않았습니다.

전체 절차 분석

작은 Skill 이름을 먼저 정하고 나머지를 욱여넣지 않으려고, 처음 입력부터 최종 보고까지 전 절차를 먼저 나열했습니다. Skill 본문 + 연결 문서 4개 + 작업일지 실행 기록을 근거로 삼았습니다.

후보가 14개 나왔습니다.

문서에 적힌 8개 절 외에, 문서에는 없는데 실제로는 매번 돌고 있던 절차가 3개 발견됐습니다.

이 셋은 작업일지에 흔적이 잔뜩 남아 있었습니다. 16.02·27.01·27.03·12.07 문서의 빈칸이 전부 12번 절차로 채워졌는데, 정작 Skill 본문엔 그 절차가 한 줄도 없었습니다. "문서에 없다"가 "절차가 아니다"는 뜻이 아니었습니다.

절차의 실패 소유자와 검증 방법

14개 행마다 실패 소유자 / 검증 방법 / 수리 방법 / 변경 주기를 붙였습니다. 여기서 진짜 문제가 드러났습니다.

"갱신 3종 세트"의 verifier 커버리지가 1/3이었습니다.

자주 빠뜨리는 걸 알아서 검증기를 붙였는데, 정작 검증기는 3분의 1만 보고 있었습니다. 그리고 스크립트가 "깨진 링크 0개"를 출력하면 저는 통과한 줄 알았습니다. 새는 이유가 이거였습니다.

절차 분해와 절단선 설정

이름이 아니라 실패 소유자 / 검증 방법 / 변경 주기가 다르면 다른 Skill로 봤습니다. 판단이 갈렸던 지점 둘:

하나 — 기존 검증 스크립트(#9)를 독립시킬 것인가. 독립 실행이 가능하니 standalone으로 볼 수도 있었습니다. 하지만 검사 범위가 1/3인 채로 독립시키면 "검증했다"는 잘못된 안심을 파는 셈이라 판단해서, 독립시키지 않고 새 검증기 안으로 흡수하고 나머지 2/3을 덧붙였습니다.

둘 — 본문 작성(#5)은 왜 안 쪼갰나. 가장 커 보이는 절차지만 실패 소유자가 저(사람)이고 verifier도 사람입니다. 떼어내면 부모에 남는 게 없습니다. 부모 안에 뒀습니다.

확정된 작은 Skill

wiki-sync — 갱신 3종 세트 동기화

• 호출 조건: 위키 문서를 만들거나 고친 직후 / 또는 단독으로 "갱신 빠진 데 있나?" 점검할 때

• 입력: 이번에 고친 문서 목록 + 작업일지에 남길 요약 (모르면 audit 모드로 위키 전체 스캔)

• 출력: 갱신된 3곳 + before/after 검증 리포트

• verifier: 새로 만든 wiki-sync-check.py — 5개 검사 중 3개가 신규

4번은 파일시스템의 실제 수정 시각과 문서에 적힌 updated 날짜를 대조합니다. 위키에 git이 없어서 "언제 바뀌었나"의 유일한 외부 근거가 mtime이었습니다.

wiki-fact-update — 파급 정정

• 호출 조건: 이미 적혀 있는 사실이 바뀌었을 때 (중단·종료·이관·범위변경·수치갱신)

• 입력: 옛 진술 / 새 진술 / 검색어 2개 이상 (표기 흔들림 때문에 하나로는 반드시 빠뜨립니다)

• 출력: 인용 유형별 분류 + 정정 목록 + 의도적으로 남긴 목록과 사유

• verifier: 재grep에서 잔존 0. 단, 과거 이력은 남아 있어야 정상

이 Skill의 핵심은 인용을 5가지로 나누는 것입니다. 유형마다 처리가 다릅니다.

D를 고치면 안 된다는 게 중요했습니다. 과거에 그랬던 건 사실이라 정정 대상이 아니고, 이력을 고치면 왜 바뀌었는지 추적이 끊깁니다.

후보 2개에서 멈추지 않았다는 확인

과제 최소 기준은 2개지만 그건 하한선이라, 근거가 있는 후보는 전부 펼쳤습니다.

• 전체 14개 중 standalone 후보 8개

• 이번 주 실제 생성: 2개 (#7, #13)

• 후보로 확정했으나 이번 주 미생성: 6개 — #2 배치 판단, #3 번호 배정, #6 원칙 승격, #10 파일명 변경, #12 빈칸 Q&A, #14 외부 공유 검토

• 부모 유지 3개 / support script·template 3개

미생성 6개는 근거가 없어서 뺀 게 아니라 순서를 미룬 것이고, census에 근거가 그대로 남아 있습니다.

Umbrella Tree와 연결 순서

Open optionstext

wiki-add  (Umbrella)
├─ 부모 유지 : #1 규칙 로딩 · #5 본문 작성 · #11 보고
├─ 생성됨    : #7 wiki-sync · #13 wiki-fact-update
├─ 후보(미생성): #2 · #3 · #6 · #10 · #12 · #14
└─ support   : #4 프론트매터 템플릿 · #8 updated 갱신 · #9 링크 검증

Open optionstext

[경로 1] 문서 추가
  요청 → 규칙로딩 → 배치판단 → 번호배정 → 본문작성 → wiki-sync
                                                      ├ PASS → 보고 → 종료
                                                      └ FAIL → 수리 → 재실행

[경로 2] 사실 변경 (독립 진입)
  감지 → wiki-fact-update (grep → 유형분류 → 승인 → 반영 → 재grep)
                                                      └ 잔존 0 → wiki-sync

[경로 3] 단독 점검
  "빠진 데 있나?" → wiki-sync audit 모드 → 검증기

census 14행이 전부 Tree/Circuit 또는 support 분류에 연결됐습니다. 미분류 0.

실행 및 시뮬레이션 결과

1차 — 원본 위키에 검증기 실행 (읽기 전용)

Open optionsauto

JDS 페이지 93개 · 내부 링크 625개

[1] 내부 링크          : 깨짐 0개
[2] Category 개요 등재 : 누락 0개
[3] README 지도 등재   : 누락 0개
[4] updated 프론트매터 : 갱신누락 의심 4개   ← 검출
[5] 작업일지 날짜 섹션 : 누락 0개

판정: FAIL

기존 스크립트로는 하나도 못 잡던 4건이 나왔습니다.

작업일지 97·174·207행과 교차 확인해서 4건 전부 진짜인 걸 확인했습니다. 12.02는 3종 중 2종이 동시에 빠진 케이스입니다 — 수정은 됐는데 updated도 안 바뀌었고 작업일지에도 없습니다. 무엇을 고쳤는지 복원할 근거가 없어서 기록 유실로 남겼습니다.

2차 — 파급 정정 Skill로 실제 grep (읽기 전용)

작업일지에 기록된 27.01 네이버 베스트 리뷰 중단 건을 입력으로 넣었습니다. 8개 문서에서 인용이 나왔고, 작업일지에 "정정했다"고 적힌 건 6곳이었습니다.

16.00이 그 목록에 없었습니다.

Open optionsauto

"네이버 베스트 리뷰·29CM 포토 리뷰처럼 채널이 제공하는 리뷰 이벤트 기능을 쓰는 건은 27에 있다"

사실을 틀리게 말하진 않습니다. B2S와 B2C 리뷰 업무를 구분해주는 길안내 문장이니까요. 그래서 사람이 훑을 때 자연스럽게 넘어갔을 겁니다. 다만 중단된 프로그램을 대표 예시로 쓰고 있어서 읽는 사람이 살아 있다고 오해할 여지가 있습니다. 유형 E(사람 판단)로 올라올 행이었습니다.

3차 — Circuit 경로 1 전체를 사본에서 리허설

위키를 /tmp에 통째로 복사한 뒤, 문서 추가부터 검증까지 전 구간을 돌렸습니다.

Open optionsauto

문서 94개 · 링크 629개

[1] 0개  [2] 0개  [3] 0개  [4] 0개  [5] 0개
판정: PASS — 갱신 3종 세트 전부 통과

원본 위키는 리허설 후에도 STALE 4건 그대로였고 12.11은 생기지 않았습니다. 사본 경계가 지켜졌습니다.

실패와 수정 과정

실패 1 — 사본을 잘못 떠서 위키 전체를 오탐했습니다. cp -R로 복사했더니 mtime이 전부 복사 시각으로 갱신돼서 검사 [4]가 93개 문서를 몽땅 STALE로 잡았습니다. cp -Rp로 해결. 웃긴 건 이 한계를 제가 Skill 문서에 이미 경고로 적어놨다는 겁니다. 그러고도 첫 실행에서 그대로 밟았습니다. 경고를 써두는 것과 그 경고를 피해 가는 것은 다른 일이었습니다.

실패 2 — 제 수리 방법이 틀렸고, 검증기가 그걸 잡았습니다. updated가 안 바뀐 4건을 고칠 때 "실제 수정일(08-03)을 넣어야 이력이 정확하다"고 판단했습니다. 그런데 파일을 쓰는 순간 mtime이 오늘이 되니까 검증기가 즉시 다시 STALE로 잡았습니다. 무한 루프.

다시 보니 wiki-add.md §4에 이미 "수정한 문서들의 updated도 오늘 날짜로"라고 규칙이 있었습니다. 실제 수정일은 updated가 아니라 작업일지에 남기는 자리였고요. 제가 부모 Skill의 규칙을 어긴 거였습니다.

이게 이번 주에 제일 크게 남은 지점입니다. 사람이 훑었으면 "과거 날짜를 넣는 게 더 정확해 보이는데?"에서 멈췄을 겁니다. 기계 verifier가 제 판단이 규칙과 어긋난다는 걸 잡아줬습니다.

막힘 — 파급 정정은 기계로 완결이 안 됩니다. 유형 A·B·C는 자동 판정이 되는데 E(예시 인용)는 안 됩니다. 16.00 케이스가 정확히 그렇습니다. "틀린 말은 아닌데 오해를 부르는" 상태를 기계가 판정할 방법을 못 찾았고, 사람에게 올리는 걸로 뒀습니다.

위키 관리 결과

• 절차 census 14개 (문서에 없던 절차 3개 발견)

• 작은 Skill 2개 생성 + 후보 6개 확정

• 검증기 커버리지 1/3 → 3/3

• 실제 누락 4건 검출, 그중 1건은 기록 유실 확정

• 파급 정정 미검토 1건(16.00) 발견

• 리허설 PASS, 원본 무손상

가장 크게 바뀐 건 도구가 아니라 판단 기준입니다. "검증기가 있다"와 "검증기가 그 실패를 본다"는 완전히 다른 얘기였고, 저는 두 달 동안 앞의 것만 믿고 있었습니다.