Claude Code가 기능 구현 여부를 4번이나 틀려서 규칙을 만들었습니다. 추가적인 실패 사례를 찾습니다.

TL;DR: Claude Code가 한 세션에서 4번이나 '기능 구현 안 됨'이라고 했는데, 4번 다 틀렸습니다. 이름 검색 대신 구조적 흔적(structural footprint) 검색을 강제하는 규칙을 만들었습니다. 제 루프 밖에서는 테스트해보지 않았습니다. 제가 놓치고 있는 실패 모드를 찾고 있습니다.

Cursor 사용자들도 같은 부류의 문제를 겪기 때문에 여기 올립니다. 에이전트가 실제로는 구현되어 있는데도 자신 있게 'X는 구현 안 됨 / 미구현 상태'라고 말하고, 사용자가 계속 반박해야 진짜 답을 내놓는 상황 말입니다. 아래 규칙은 그 '반박' 과정을 결정론적으로 만들기 위한 제 시도입니다.

설정. 두 달 동안 만들어온 개인 자동화 프로젝트에서 Claude Code를 사용 중입니다. 중간 규모의 코드베이스이고 문서화가 잘 되어 있으며, 세션 시작 시 에이전트가 읽는 자매 메모리 디렉토리가 있습니다. 기능은 대부분 작동합니다.

패턴. 어느 날 아침 4번이나 '이 기능 이미 구현되어 있나?'라는 질문을 했습니다. 4번 다 에이전트는 자신 있게 '아니요, 이렇게 만들면 됩니다'라고 답했습니다. 4번 다 진실은 '네, 부분적으로 구현되어 있고, 제대로 확인했으면 봤을 텐데'였습니다. 매번 진짜 답을 얻어내기 위해 반박해야 했습니다.

진단. 에이전트가 검색을 거부한 게 아닙니다. 이름으로 검색해야 할 때 이름으로 검색한 게 문제였습니다. 기능은 어떤 이름으로든 불릴 수 있습니다. 하지만 기능은 구조적 잔여물 없이는 존재할 수 없습니다. 라우트, 스키마, 등록된 도구, 예약된 작업, 문서화된 결정 사항 같은 것들 말이죠. 이름은 변하지만 흔적은 변하지 않습니다. 이름으로 검색하는 건 '이 기능이 어떤 문자열을 사용할까?'(어휘)라고 묻는 것이고, 구조로 검색하는 건 '이 기능이 어떤 아티팩트를 필요로 할까?'(아키텍처)라고 묻는 것입니다. 후자만이 안정적으로 올바른 답을 내놓습니다.

왜 단순히 '더 좋은 키워드를 써라'가 아닌지. 더 좋은 동의어를 검색하는 것도 여전히 이름으로 검색하는 것입니다. 동의어 버전은 오늘 발생한 실패(이전 코드가 에이전트가 생성할 생각조차 못한 이름을 가지고 있었음)를 여전히 놓칩니다. 흔적 버전은 그걸 잡아냅니다(이전 코드가 플러그인 도구를 등록했고, '어떤 플러그인 도구가 존재하는가?'는 신호가 강하고 좁은 검색이기 때문입니다).

규칙 (4라운드에 걸친 8번의 비평을 통해 합성됨 — 구조적 흔적 전환이 가장 큰 기능적 업그레이드였습니다):

"기능 X는 구현 안 됨 / 미구현 상태 / 누락됨"이라고 주장하기 전에:

1. 매핑: 프로젝트 저장소와 에이전트 메모리 디렉토리 전체에서 키워드를 rg -li로 검색하십시오. 둘 중 하나라도 5개 이상의 파일이 나오면, 무엇을 먼저 읽을지 범위를 정하십시오.

2. 구조적 흔적 스캔 (단순 동의어 검색 금지): 이 기능 클래스가 요구할 아키텍처 불변 요소를 식별하십시오 — API 엔드포인트 / 스키마 파일 / 크론 항목 / 플러그인 도구 목록 / project_*.md 결정 문서. 각 불변 요소를 Grep하십시오. 하나라도 일치하는 항목이 나오면, 그 일치 항목을 읽기 전까지는 "구현 안 됨"이라는 주장은 반박된 것으로 간주하십시오.

   스택 규율: 흔적은 스택에 적절해야 합니다. 어떤 아키텍처 패턴이 적용되는지 확실하지 않으면, 2~3개의 대안을 나열하고 각각 검색하십시오.

3. 인식론적 분류: 각 일치 항목을 다음 중 하나로 분류하십시오:

   • 직접적 증거 (정확한 로직 읽기)
   • 인프라 힌트 (스키마/타입만)
   • 부분적 구현 (일부 흔적은 존재하지만 나머지는 누락)
   • 전체 부재 (저장소 전체의 모든 불변 요소를 검색했으나 아무것도 찾지 못함)