아프니까 개발자다 아프니까 개발자다

위키를 검증하는 정책을 여럿 갖춰 둘 수 있다. syntax 깨끗, anchor valid, coverage trend 안정, byte-identical 보장 등. 모두 매일 green이라고 하자. 그런데 이 모든 신호가 답하지 못하는 질문이 하나 남는다 — "이 위키로 AI 에이전트가 실제 task를 풀 수 있는가". 그게 위키 운영의 진짜 목적이다.현실에서 잘 발생하는 양상은 이렇다. 위키는 valid한 anchor 1,200개를 갖고 있고 함수 coverage 75%를 유지한다. 그런데 에이전트가 "이 라우터의 핸들러는 어디 있나"를 물으면, 정답이 위키 안에 분명히 있는데도, 에이전트는 wiki에 도달하지 못한다. 청크의 임베딩이 task 의도와 align되지 않거나, 검색 stage가 엉뚱한 페..

위키 페이지 한 장이 어제와 오늘 다르다. diff를 떠 보면 paragraph 두 개의 순서가 바뀌었다. 단어 한 두 개는 동의어로 치환됐다. 본질적인 내용은 똑같아 보인다. 그런데 — 원본 소스 코드는 한 글자도 안 바뀌었다. 어제와 오늘 LLM에 들어간 입력이 byte-identical이다. 그런데 위키 출력이 다르다.위키는 본질적으로 안정적인 참조여야 한다. 누군가 어제 본 페이지를 오늘 다시 열었을 때, 출처 코드가 그대로면 위키도 그대로여야 한다. 그래야 어제의 인용·링크·기억이 오늘 깨지지 않는다. 우리는 매일 위키를 새로 만들지 않는다 — 원본 소스가 실제로 바뀔 때만 해당 페이지를 다시 생성한다. 그 전제가 의미를 가지려면 "입력이 그대로면 출력도 그대로"가 먼저 보장돼야 한다.1. 같은..

위키를 한 달 운영해 보면 한 가지 이상한 양상이 보인다. 모든 페이지가 syntax 깨끗하고, 모든 anchor가 valid한 함수를 가리키며, 그런데 한 repo에 대한 질문에 RAG가 답하지 못한다. 들어가서 보면 그 repo의 함수 200개 중 위키에 등장한 게 5개뿐이다. 위키는 valid하지만 그 repo에 대해 사실상 아무 말도 하지 않는다.이 상황은 "적힌 줄"을 검증하는 다른 검증들로는 절대 잡히지 않는다. 그것들은 적힌 syntax가 valid한지, 적힌 좌표가 실재하는지를 본다. 한 번도 적히지 않은 함수에 대해서는 할 말이 없다.양의 차원 — 코드에 정의된 노드 수 대비 위키에 언급된 비율을 보는 coverage 검증이 그 자리에 있다. 이 글은 그 검증의 두 가지 결정을 본다. 첫..

코드 위키를 한 달 운영해 보면 같은 장면이 두세 번 반복된다. 누군가가 위키를 열어 "이 함수의 동작이 이렇다"라는 문장을 읽고, 안내된 위치로 가 보면 그 함수가 거기에 없다. 같은 이름의 다른 함수가 있거나, 함수가 다른 파일로 옮겨졌거나, 아예 삭제되었거나. 위키 본문은 자신만만하게 적혀 있고, 코드는 그 자신감을 배신한다.이 장면이 사람 독자에게는 짜증나는 정도지만, AI 에이전트에게는 다르다. 에이전트는 RAG(Retrieval-Augmented Generation) — 질문이 들어오면 외부 지식 베이스에서 관련 문서를 먼저 검색해 가져온 뒤 그걸 prompt에 끼워 답을 만드는 패턴 — 으로 동작한다. 위키가 가져다 준 문장을 ground truth(검증된 사실)로 받아 그 위에서 추론한다...

위키에 proxy.py:1247에서 인증 토큰을 검사한다라고 적었다. 그날 1247 줄은 def verify_token(req):이었다. 일주일 뒤 누가 그 위에 import 두 줄을 추가하고 함수를 위로 옮겼다. 위키 본문은 그대로 — proxy.py:1247. 그 줄은 이제 빈 줄이다.이 상태가 위험한 건 위키만의 문제가 아니다. AI 에이전트가 RAG로 이 페이지를 받아 "토큰 검증이 어디서 이뤄지나"를 물으면, 에이전트는 위키의 anchor를 인용해 답한다. 코드와 어긋난 좌표를 자신 있게 가리키며. 사용자가 그걸 따라가면 빈 줄을 본다. 위키가 가짜 좌표를 가르치는 순간 RAG의 신뢰가 한 번에 무너진다.이 글은 위키의 모든 file.py:LINE anchor를 매일 AST와 대조해 stale ..

코드 위키를 만들었다. 마크다운으로 페이지를 적고, SPA renderer가 페이지를 띄우고, 그 안의 mermaid 다이어그램이 브라우저에서 그려진다. 며칠 문제없이 작동하던 시스템에서 처음으로 보이는 깨짐은 "빈 박스"다. 페이지 한가운데에 다이어그램이 들어가야 할 자리에, 아무것도 없는 사각형이 있다. 에러 메시지도, 경고도, 콘솔 로그도 없다.그 빈 박스의 원인은 대개 한 가지다 — mermaid 코드 블록의 첫 줄 토큰이 오타거나 mermaid가 모르는 단어다. flochart TD(오타), flow TD(존재하지 않는 키워드), graph LR(존재함). 첫 줄이 깨지면 mermaid는 조용히 포기한다. SPA는 그 포기를 받아들이고 자리만 비워둔다.그런데 mermaid 다이어그램이 깨지는 양..