당신의 CLAUDE.md가 에이전트에게 거짓말을 하고 있습니다

비어 있는 CLAUDE.md는 정직합니다.

파일이 없을 때, 당신의 에이전트는 합리적인 행동을 합니다. 즉, 주변을 둘러보는 것입니다. 코드를 읽습니다. 당신에게 질문을 던집니다. 아직 모른다는 사실을 조용히 인정하고, 직접 가서 알아냅니다.

하지만 오래된 CLAUDE.md는 정반대로 행동합니다. 아주 자신만만하게 방에 들어와서, 과거에는 사실이었던 내용을 당신의 에이전트에게 말합니다. 그리고 당신의 에이전트는 그것을 믿습니다. 믿지 않을 이유가 있을까요? 당신이 직접 적었으니까요. 당신이 커밋(commit)했으니까요. 그것은 바로 _컨텍스트 파일(context file)_입니다.

이것이 아무도 경고해주지 않는 부분입니다. 우리는 CLAUDE.md를 마치 공짜 보험처럼 이야기합니다. 한 번 작성해 두면 에이전트가 멍청한 짓을 멈출 것이라고 말이죠. 하지만 아무도 이 파일에 반감기(half-life)가 있다는 사실과, 퇴색된 지침이 침묵하지 않는다는 사실을 언급하지 않습니다. 지침은 계속 말을 합니다. 다만 틀린 말을 하기 시작할 뿐입니다.

내가 내 메모에 배신당했던 어느 금요일

제가 이 사실을 어떻게 배웠는지 말씀드리겠습니다. 아주 창피한 방식으로 배웠거든요.

몇 달 전 금요일 오후, 저는 프로젝트를 정리하는 데 시간을 보냈습니다. 어떤 오후인지 아실 겁니다. 아주 뿌듯한 그런 오후 말이죠. 저는 비대해진 utils.ts 파일에서 인증(authentication) 로직을 분리하여 별도의 공간을 만들어 주었습니다. 몇 주 동안 신경 쓰였던 모듈의 이름을 변경했습니다. 더 이상 사용하지 않는 헬퍼(helper) 함수를 삭제하고 더 깔끔한 것으로 교체했습니다. 이 모든 것을 커밋(commit)하고 노트북을 덮으며, 책임감 있는 성인이 된 것 같은 기분을 느꼈습니다.

하지만 제가 하지 않은 일은 CLAUDE.md를 여는 것이었습니다. 그 파일은 3주 전 것이었습니다. 여전히 "인증은 utils.ts에 있다"라고 적혀 있었습니다. 방금 이름을 바꾼 모듈의 이름을 그대로 유지하고 있었습니다. 방금 삭제한 헬퍼 함수를 여전히 추천하고 있었습니다.

월요일 아침, 나는 에이전트에게 인증 흐름 (auth flow) 근처에 작은 기능을 추가해 달라고 요청했습니다. 그리고 에이전트는 내가 시킨 대로 정확히 수행했습니다 — 더 이상 존재하지 않는 프로젝트 버전의 방식대로 말이죠. 에이전트는 utils.ts에서 인증 (auth) 로직을 찾으려 했습니다. 이미 사라진 헬퍼 함수 (helper function)를 호출하려 했습니다. 그것들을 찾을 수 없었을 때, 에이전트는 멈춰서 질문하지 않았습니다. 대신 그것들을 재구성 (reconstructed) 했습니다. 에이전트는 지난달 코드베이스의 작은 유령을 자신 있게 다시 만들어냈습니다. 왜냐하면 내가 신뢰하라고 지시한 유일한 문서에 상황이 그렇다고 적혀 있었기 때문입니다.

모델은 고장 난 것이 아니었습니다. 추론 (reasoning) 과정도 괜찮았습니다. 에이전트는 지침을 완벽하게 따랐습니다. 단지 그 지침이 에이전트에게 거짓말을 하고 있었을 뿐입니다 — 그리고 그 거짓말을 쓰고 서명한 사람은 바로 저였습니다.

CLAUDE.md의 반감기 (half-life)

이 파일에 대한 불편한 진실은 이것입니다: 파일을 저장하는 순간부터 죽기 시작한다는 것입니다.

CLAUDE.md는 정지된 사진과 같습니다. 반면 당신의 코드베이스는 움직이는 유기체입니다. 모든 커밋 (commit), 모든 이름 변경 (rename), 모든 "사실, 그 방식 말고 다른 방식으로 하자"라는 결정은 실제 프로젝트를 사진으로부터 반 걸음씩 멀어지게 만듭니다. 이러한 움직임 중 그 어떤 것도 파일에 알려주지 않습니다. 파일은 금요일이 지나갔다는 사실조차 알지 못합니다.

그렇게 간극은 조용히 벌어집니다. 첫째 날에는 사진이 완벽합니다. 둘째 주에는 몇 가지 세부 사항이 어긋납니다. 둘째 달에는 문단 전체가 이미 리팩터링 (refactored) 되어 사라진 프로젝트를 설명하고 있습니다. 그리고 가장 최악인 점은, 그것이 여전히 아주 잘 _읽힌다_는 것입니다. 오래된 문서 (stale documentation)는 낡아 보이지 않습니다. 오히려 권위 있어 보입니다. 바로 그 점이 그것을 위험하게 만듭니다.

이것은 제가 컨텍스트 부패 (context rot)에 대해 썼던 것과 동일한 질병입니다 — 텍스트가 많다고 해서 진실이 더 많은 것은 아닙니다. 더 긴 CLAUDE.md가 더 신뢰할 수 있는 문서를 의미하지 않습니다. 그것은 단지 부패가 퍼져나갈 수 있는 더 넓은 표면일 뿐입니다.

왜 "틀린 것"이 "비어 있는 것"보다 더 나쁜가

우리는 어떤 컨텍스트 (context)라도 있는 것이 아예 없는 것보다 무조건 낫다고 생각합니다. 하지만 정적 파일 (static files)의 경우, 그 계산법은 거꾸로 되어 있습니다.

Anthropic의 자체 데이터가 그 이유를 말해줍니다. 에이전트 실패의 가장 큰 단일 카테고리는 창의성이나 환각 (hallucination)이 아닙니다. 바로 지속적인 잘못된 해석 (consistent wrong interpretation), 즉 에이전트가 매 실행마다 동일한 잘못된 가정을 하는 것입니다. 오래된 CLAUDE.md는 정확히 그러한 실패를 양산하는 공장입니다. 그것은 에이전트에게 잘못된 가정을 건네주고 거기에 "공식적"이라는 도장을 찍어버립니다. 이제 실수는 일회성으로 끝나지 않습니다. 그것은 구조를 지탱하는 핵심 요소 (load-bearing)가 됩니다. 모든 세션은 동일한 잘못된 지점에서 시작하여, 동일한 잘못된 방향으로 자신 있게 나아갑니다.

두 가지 실패 모드를 솔직하게 비교해 보십시오:

• 파일 없음: 에이전트가 불확실해하므로, 탐색하고, 질문하고, 확인합니다. 속도는 느리고 때로는 짜증스러울 수 있지만, 스스로 수정 (self-corrects)합니다.
• 오래된 파일: 에이전트가 "확신"하므로, 확인하지 않습니다. 그저 실행할 뿐입니다. 빠르고 매끄럽지만, 커밋이 세 번이나 쌓일 때까지는 알아차릴 수 없는 방식으로 틀립니다.

불확실성은 회복 가능합니다. 잘못된 확신은 버그를 배포하게 만드는 주범입니다.

그것이 부패하는 세 가지 방식

결코 극적으로 일어나지 않습니다. 항상 사소하게 일어납니다. 제 경험상 거의 항상 다음 세 가지 중 하나입니다:

1. 지도가 지형과 일치하지 않게 됨. 파일을 이동하거나, 모듈 이름을 바꾸거나, 폴더 구조를 재편성합니다. CLAUDE.md는 여전히 옛 주소를 가리키고 있으므로, 에이전트는 더 이상 존재하지 않는 문을 계속 두드리고, 길을 잃었다고 인정하는 대신 새로운 문을 만들어 버립니다.
2. 뒤집힌 결정이 계속 명령을 내림. "우리는 라이브러리 X를 사용합니다." 3주 후, 런타임 (runtime)을 지원하지 않아 라이브러리 X를 제거합니다. 파일에는 아무도 알려주지 않습니다. 파일은 당신이 오후 내내 공들여 제거한 것을 계속해서 쾌활하게 추천합니다.
3. 어제의 관습이 수명을 다함. 혼자일 때는 맞았던 규칙이 팀원이 합류하거나, 프로젝트가 기록했을 당시의 형태를 넘어 성장하는 순간 틀린 것이 됩니다.

각각은 아주 미미합니다. 에이전트가 그에 따라 행동하기 전까지는 각각 눈에 보이지 않습니다. 그리고 이 세 가지를 수동으로, 영원히 동기화 상태로 유지해야 하는 마찰 (friction) — 그것이 실제 문제입니다.

"그냥 계속 업데이트하세요"는 계획이 아닙니다

여러분이 무슨 생각을 하는지 저도 압니다. 저 또한 똑같이 생각했으니까요. _'알았어, 그냥 파일을 최신 상태로 계속 유지하면 되잖아.'_라고 말이죠.

하지만 그러지 못할 겁니다. 여러분이 게을러서가 아니라, 아무도 그렇게 하지 못하기 때문입니다. 수동으로 업데이트해야 하는 문서(Documentation)는 지금까지 존재했던 모든 팀에서 결국 최신 상태를 벗어나게 마련이며, CLAUDE.md는 에이전트의 옷을 입고 있는 문서일 뿐입니다. 배운 것을 기록하려는 본능은 정확합니다. 문제는 메커니즘입니다. 방금 그 일을 하느라 손이 바쁜 바로 그 순간에, 반드시 편집해야 한다는 사실을 기억해야만 하는 평면 파일(flat file) 방식 자체가 고장 나 있는 것입니다.

이것은 제가 왜 당신의 AI는 모든 것을 잊어버리는가에서 계속해서 되풀이해 말했던 것과 동일한 간극입니다. 문제는 에이전트에게 기억이 없다는 것이 아니었습니다. 문제는 그 기억이 당신의 속도를 따라잡을 수 없는 곳에 머물러 있다는 것이었습니다. 정적 파일(static file)은 따라잡을 수 없습니다. 애초에 그렇게 만들어지지 않았습니다.

살아있는 기억(living memory)의 실제 모습

해결책은 더 나은 파일이 아닙니다. 완전히 다른 형태여야 합니다.

여러분의 절제력(discipline)이 아니라, 작업으로부터 직접 업데이트되는 기억을 상상해 보십시오. 여러분이 에이전트에게 한 번만 수정 사항을 알려주면 — "인증(auth) 기능이 이동했어, 이제 별도의 모듈에 있어" — 그 수정 사항은 _고정(sticks)_됩니다. 그리고 여러분이 문단을 편집하러 가야 한다는 사실을 기억할 때까지 기다리는 대신, 다음에 관련 상황이 생겼을 때 자연스럽게 나타납니다. 모듈의 이름이 변경되면, 여러분이 나중에 마크다운 파일을 따로 열어서 수정했기 때문이 아니라, 실제로 이름을 변경했기 때문에 업데이트됩니다. 결정이 뒤집히는 순간, 이전의 결정에 따른 명령도 즉시 중단됩니다.

또한 이것은 특정 도구의 설정 파일(config file)에 갇혀 있지 않기 때문에 여러분을 따라다닙니다. 월요일에는 Claude Code, 화요일에는 Cursor, 수요일에는 PR 리뷰를 위한 Copilot을 사용하더라도 — 동일한 기억, 동일한 진실을 공유합니다. 세 개의 오래된 파일이 세 명의 에이전트에게 지난달의 서로 다른 세 가지 버전을 말해주는 삼각 표류(three-way drift) 현상은 발생하지 않습니다.

그 살아있는 계층(living layer)이 바로 제가 ContextForge를 만든 목적입니다. 즉, MCP를 통해 Claude Code, Cursor, Copilot에 연결되어 사용자의 수정 사항과 결정을 한곳에 보관하고, 에이전트에게 한 달 전의 사진을 건네주며 그것을 컨텍스트(context)라고 부르는 대신, 적절한 순간에 적절한 정보를 제공하는 메모리입니다.

제 것을 사용할 필요는 없습니다. 직접 만드셔도 됩니다. 하지만 당신이 할 수 없는 일 — 제가 그 금요일에 시도했다가 실패했던 일 — 은 순전한 의지력만으로 정적인 파일의 정직함을 유지하는 것입니다.

이번 주에 해야 할 일

세 가지가 있으며, 첫 번째는 지금 당장 10분 안에 시작할 수 있습니다:

1. CLAUDE.md의 거짓말을 감사(Audit)하세요. 파일을 열고 낯선 사람처럼 읽어보세요. 모든 경로, 모든 "우리는 ~를 사용한다", 모든 컨벤션(convention) — 이들이 오늘날에도 여전히 사실인가요? 사실이 아닌 것들의 개수를 세어보세요. 그 숫자가 이번 달에 당신의 에이전트가 얼마나 자주 확신을 가지고 잘못된 정보에 속았는지를 나타냅니다.
2. 지속적인 것과 부패하는 것을 분리하세요. 그 파일의 내용 중 일부는 진정으로 안정적입니다 (프로젝트의 목적, 엄격한 제약 조건 등). 일부는 단지 코드의 현재 형태를 캐싱하는 상태(state)일 뿐입니다. 그리고 상태는 당신이 일일이 관리해야 하는 파일이 아니라, 스스로 업데이트되는 곳에 있어야 합니다.
3. 메모리 계층(memory layer)을 시도해보세요. ContextForge는 MCP를 통해 Claude Code, Cursor, Copilot에 연결되는 무료 티어를 제공합니다. 설정하는 데 5분이면 충분합니다. 당신의 수정 사항이 썩어가는 대신 효과를 발휘하기 시작할 것입니다.

비어 있는 CLAUDE.md는 자신이 모른다는 것을 인정합니다. 하지만 오래된 파일은 알고 있는 척을 하며, 당신의 에이전트는 그 차이를 구별할 수 없습니다.

에이전트에게 사진을 믿으라고 요구하는 것을 멈추세요. 당신의 속도를 실제로 따라올 수 있는 무언가를 제공하세요.