Obsidian 플러그인의 /ingest, /refactor(merge·split), /status, /sync —
파일을 실제로 쓰는 모든 명령어의 로직을 통째로 다시 설계하기로 한 날이었다.
국소 패치 대신 처음부터 재조사하기로 했고, 조사 자체는 그날 안에 꽤
꼼꼼하게 끝났다. 문제는 그다음이었다 — 이미 완성된 조사 문서를 놓고
브레인스토밍하면서 구두로 다시 요약하거나 재구성할 때마다, 뭔가 하나씩
빠졌다.
네 번, 매번 다른 자리에서
스코프를 6개 버킷으로 나눠서 제시했는데, refactor-suggest(제안 단계)가
통째로 빠지고 refactor-execute(실행 단계)만 있었다. “왜 그 과정은
완전히 빠진 것처럼 보이지?”라는 지적을 받고서야 알아챘다.
출처 확정 로직을 실제로 누가 쓰게 되는지 물었을 때는 /status만
소비자라고 답했다가, /sync도 소비자라는 걸 문서에도 없는 본인
추측으로 정정해야 했다. “확인해봐, 분명하게 해서 진행하자”는 요청을
받고 코드를 다시 읽고서야 /sync도 확정할 수 있었다.
데이터 흐름을 표로 처음 정리했을 때는 refactor-execute(merge/split)가
어느 단계에서 끼어드는지 아예 안 보였다. “여기 왜 안 나오지?”라는
질문에 다시 넣었다.
흐름도를 다시 쓴 다음에도, NoteExporter(채팅에서 “노트로 저장” 버튼을
눌렀을 때 실행되는 별도 경로)의 스코프가 아직 정해지지 않은 상태라는
사실이 또 묻혀 있었다. “혹시 다른 곳에서는 없나?”라는 질문으로 다시
드러났다.
조사는 끝났는데, 왜 매번 빠질까
투자(조사)는 이미 끝나 있었다. 실패 지점은 항상 “요약” 그 자체였다. 방대한 조사 결과를 한 번에 구두로 재구성하려고 할 때마다, 머릿속에 남은 인상만으로 다시 쓰다 보니 뭔가가 조용히 빠졌다. 완성된 문서가 바로 옆에 있어도 그걸 참고 삼아 요약하는 것과, 그 문서를 매번 다시 펼쳐서 원문과 대조하며 새로 구성하는 것은 전혀 다른 작업이었다.
네 번 다 처방은 같았다 — 기억으로 요약하지 말고, 매번 원문을 다시 펼쳐서 대조할 것. 두 번째 사례(“확인해봐”)에서 이 처방이 통한다는 걸 확인한 뒤로는, 세 번째·네 번째 사례에서도 같은 방식으로 빠진 부분을 되찾을 수 있었다. 재발 자체는 막지 못했지만, 재발했을 때 되찾는 방법만큼은 이미 검증돼 있었던 셈이다.
계획으로 옮겨 적을 때도 똑같은 일이 벌어졌다
스코프를 확정한 뒤, 첫 번째 하위 프로젝트(/ingest 적용)를 브레인스토밍
→ 설계 → 계획 → 구현 순서로 진행했다. 구현은 서브에이전트가 맡았고,
계획 문서에 적어둔 코드를 그대로 옮기기만 하면 되는 태스크였다. 그런데
리뷰에서 진짜 결함 3개가 나왔다.
리뷰어가 찾은 문제는 세 가지였다 — 참조 해석에 실패해서 재시도할 때 로그가 중복으로 남는 것, 따옴표로 감싸인 ID를 교정하는 과정에서 따옴표 문자 자체가 유실되는 것, 위키링크 전체를 무차별적으로 raw 파일 레지스트리 대상으로 퍼지매칭해버리는 것. 셋 다 실제로 재현 가능한 결함이었다.
근데 확인해보니 구현자는 계획 문서에 적힌 코드를 정확히 그대로 옮겼을 뿐이었다. 문제의 원인은 구현이 아니라, 그 계획을 쓸 때 집어넣은 코드 자체에 있었다.
“계획대로 정확히 구현했다”는 사실이 “결과가 옳다”를 보장하지 않는다는 걸 이때 처음 체감했다. 계획을 쓰는 단계에서는 코드가 논리적으로 그럴듯해 보이면 통과시키기 쉽다 — 실제로 돌려보거나 엣지 케이스를 하나씩 짚어보지 않으면, 오타 수준의 결함이나 놓친 분기가 그대로 “완전한 코드”라는 이름으로 계획서에 박제된다. 그리고 구현 단계의 서브에이전트는 그 코드를 의심하지 않고 그대로 옮긴다 — 그게 정확히 요청받은 일이니까.
발견된 세 가지를 전부 수정하는 서브에이전트를 다시 보냈고, 각 결함을 재현하는 회귀 테스트 세 개를 추가한 뒤 재리뷰를 받아서 통과했다. 중요한 건 “구현자를 탓하지 않았다”는 점이 아니라, 리뷰 루프 자체가 계획 문서의 결함까지 걸러낼 수 있었다는 것 — 태스크 단위 리뷰가 있었기 때문에 이 세 가지를 다음 하위 프로젝트로 넘기기 전에 잡을 수 있었다.
배운 점
두 사건은 서로 다른 단계(구두 요약 vs. 계획 문서 작성)에서 벌어졌지만 같은 실패 패턴이었다 — 원문을 그대로 참조하는 대신 옮겨 적거나 재구성하는 순간, 그 재구성 자체가 새로운 오류를 만들 수 있는 자리가 됐다. 정리된 조사 문서가 있다는 사실이 “그 내용을 정확히 기억하고 있다”는 뜻이 아니었던 것처럼, “계획에 완전한 코드를 써넣었다”는 사실도 “그 코드가 옳다”는 증거가 아니었다. 옮겨 적는 모든 지점이 검증 대상이었다.