지난 글에서 재현율 숫자와 실사용 경험 사이의 간극을 다시 짚었다. 이번엔 이슈 두 개를 처리하면서, 코드를 고치기 전에 실제 API로 먼저 검증부터 해본 이야기다.
태그가 노트 수보다 두 배 가까이 빠르게 늘고 있었다
/ingest가 새 노트를 만들 때마다 태그를 그 노트 하나만 보고 새로
지어냈다. 예전엔 위키 카탈로그를 프롬프트에 같이 넣어서 기존 태그를
참고할 수 있었는데, 그 경로를 없앤 이후로는 그럴 방법 자체가 없었다.
실사용 vault를 뒤져보니 노트 964개에 고유 태그가 1715개 — 노트
하나당 평균 1.8개꼴로, 노트 수보다 훨씬 빠르게 쌓이고 있었다.
고칠 방향은 뻔했다 — 기존 태그 목록을 프롬프트에 같이 넣어주면 될 일이었다. 그런데 실제로 재사용될지, 그리고 그 목록을 통째로 넣었을 때 노트 생성 품질이 떨어지지는 않을지는 짐작이었다.
실측으로 먼저 확인했다
git 히스토리에 남아있던 실제 스냅샷(1715개 태그)과, 이미 한 번 프로덕션으로 처리된 적 있는 원본 14개를 그대로 재사용해서, 태그 목록을 넣은 조건과 안 넣은 조건을 여러 모델·reasoning effort 조합으로 비교했다. 컨텍스트를 넣은 세 조건 전부 재사용률이 97~98%대로 나왔다 — 모델이 뭐든 일관됐다. 노트당 평균 본문 길이도 줄지 않고 오히려 늘었다. 우려했던 품질 저하는 없었다.
숫자로 확인한 다음에야 설계를 확정하고 구현했다. 청크마다 태그 목록을 다시 조회해서, 같은 배치 안에서 앞 청크가 만든 태그를 뒷 청크가 바로 재사용할 수 있게 했다.
이번엔 교차 링크가 문제였다 — 분할(split) 실행 시 위키링크 누락
같은 세션에서 또 다른 이슈를 봤다. /refactor가 문서 하나를 여러
개로 분할할 때, 분할 제안 단계는 “이 두 문서를 서로 [[A]]와 [[B]]로
교차 연결한다”고 근거에 명시적으로 적어두는데, 실제 분할 실행 결과에는
그 링크가 없었다. 실사용 vault를 리뷰하다가 직접 발견한 사례였다.
코드를 열어보니 원인이 두 갈래였다. 첫째, 제안 단계가 만든 근거
텍스트(item.reason)가 실행 단계의 프롬프트 조립 코드에 아예
전달되지 않고 버려지고 있었다. 둘째, 분할 프롬프트 자체의 링크 지침도
“언급하게 되면 링크를 걸어라”는 조건부 문장이었지, “형제 조각을 서로
연결하라”는 능동적 지시가 아니었다.
후보 두 개를 따로 실험해봤다
이슈 본문 자체가 수정 후보를 두 개 제시하고 있었다 — 근거 텍스트를 실행 단계에 전달하기, 그리고 링크 지침을 능동형으로 강화하기. 둘 다 말이 되는 수정이라 어느 하나만 해도 될 것처럼 보였다.
그런데 실제로 재현된 사례(원본 문서와 이슈에 적힌 그대로의 근거 텍스트)로 네 가지 조건을 실제 API로 비교했다 — 아무것도 안 한 조건, 근거만 전달한 조건, 지침만 강화한 조건, 둘 다 적용한 조건. 각 조건을 두 번씩 반복했다.
결과는 예상과 달랐다. 근거만 전달한 조건도, 지침만 강화한 조건도 교차 링크가 한 번도 안 생겼다(2번 다 실패). 둘을 같이 적용한 조건만 양방향 교차 링크를 만들어냈고, 그것도 2번 다 일관되게 성공했다. 그럴듯한 후보 두 개 중 어느 하나만으로는 전혀 효과가 없었고, 반드시 같이 적용해야만 실제로 작동했다.
실측 결과 그대로 구현했다
설계는 실측 결과 그대로 확정했다 — 근거 전달과 지침 강화를 함께 적용하는 것으로. 서브에이전트에게 작업을 나눠 맡겨 구현을 진행했고, 같은 날 안에 두 수정 다 반영해서 릴리즈까지 마쳤다.
남는 생각
두 이슈 다, 고치기 전에는 어느 쪽이 진짜 원인인지 꽤 확신하고 있었다. 태그는 “목록을 넣어주면 당연히 재사용하겠지”였고, 링크는 “둘 중 하나만 고쳐도 되지 않을까”였다. 둘 다 실제로 API를 불러서 확인하기 전까지는 근거 없는 확신이었다. 특히 두 번째 이슈에서는 후보를 하나씩 따로 떼어 실험한 게 결정적이었다 — 둘 다 넣은 결과만 보고 넘어갔다면, 사실은 둘 중 하나만으로 충분했는지, 아니면 정말 같이 있어야만 하는지 끝내 몰랐을 것이다.