Claude Code가 수정을 망각하는 이유와 해결 방법 (2026)

수정 사항이 아예 기록되지 않는 경우가 대부분입니다

채팅창에 입력한 수정 사항은 대화의 컨텍스트일 뿐입니다. 해당 세션의 나머지 부분에만 영향을 미치고 세션이 종료되면 사라집니다. Claude Code는 다음 세션을 시작할 때 CLAUDE.md, 레포지토리 등 사용자가 지정한 파일에서부터 다시 시작하며, 이전의 수정 사항은 그 어디에도 남아있지 않습니다.

이것이 대부분의 경우이며 매우 흔한 일입니다. 사용자는 가르치는 경험을 했기 때문에 마치 배운 내용을 잊어버린 것처럼 느껴집니다. 하지만 기계적으로 보면 아무것도 저장되지 않은 것입니다. 이는 Claude Code가 프로젝트 컨텍스트 없이 각 세션을 시작하는 문제와 동일한 공백입니다. 이 도구는 설계상 상태를 유지하지 않으며(stateless), 오직 파일만이 세션 간의 가교 역할을 합니다.

기록되었다고 해서 실행되는 것은 아닙니다

여기서부터 해결책이 달라집니다. 이는 일화적인 주장이 아니라 문서화된 사실입니다.

2026년 3월 22일, anthropics/claude-code 레포지토리에 "Claude가 자체 메모리/피드백을 적용하는 데 반복적으로 실패함 — 세션 간에 동일한 실수가 재발함"이라는 제목의 이슈가 제기되었습니다. 제보자의 설명은 정확합니다. "Claude Code의 메모리 시스템은 피드백과 규칙을 올바르게 저장하지만, 모델은 이를 일관되게 적용하지 못합니다. 메모리 파일이 여러 번 업데이트(동일한 문제에 대해 5회 이상 업데이트)되었음에도 불구하고 세션 전반에 걸쳐 동일한 유형의 오류가 반복됩니다."

제시된 예시는 누구나 공감할 만한 내용들입니다:

• 메모리에는 백엔드 명령어를 실행하기 전에 항상 `backend/`로 이동할 것, `vite build` 전에 항상 `frontend/`로 이동할 것이라고 적혀 있습니다. 하지만 여전히 잘못된 디렉토리에서 명령어가 실행되어 빌드 실패나 아무 반응 없는 결과를 초래합니다.
• 메모리에는 `App.jsx`가 변경되면 항상 `dist`를 다시 빌드할 것, 항상 `public/` 파일을 `dist/`로 복사할 것이라고 적혀 있습니다. 하지만 이 단계들이 생략되어 오래된 번들이 제공됩니다.
• 메모리에는 커밋되지 않은 변경 사항은 동기화 시 유실된다고 적혀 있습니다. 그럼에도 커밋 없이 임시로 파일이 프로덕션에 복사되고, 다음 동기화 때 변경 사항이 소리 없이 되돌아갑니다.
• 이전 세션의 수정 사항(marmot.svg를 marmot.png로 교체)이 커밋되지 않아 되돌아갔고, 다시 요청해야 했습니다.

제보자의 요약 중 기억해야 할 문장은 바로 이것입니다. "메모리 시스템은 지식을 캡처하지만 행동에 안정적으로 영향을 미치지는 못합니다." 제보자는 이를 Opus 4.6 및 파일 기반 메모리를 사용하는 Claude Code CLI의 "알츠하이머 문제"라고 불렀습니다.

두 가지를 분명히 짚고 넘어가야 합니다. 이 이슈는 해결 예정 없음(not planned)으로 종결되었으므로, 이는 공식적으로 인정된 결함이라기보다는 사용자 보고서에 가깝습니다. 그리고 이 사례는 뻔한 결론에 반하는 불편한 진실을 보여줍니다. 이 경우에는 저장 공간을 더 늘렸어도 도움이 되지 않았을 것입니다. 규칙은 이미 저장되어 있었습니다. 그것도 무려 다섯 번이나요.

긴 세션은 처음에 설정한 규칙을 묻어버립니다

반항처럼 보이지만 실제로는 그렇지 않은 세 번째 메커니즘이 있습니다. 긴 세션에서는 초반의 지시사항이 신뢰할 수 있는 범위를 벗어날 수 있습니다. 이 분야의 실무자들은 이를 정확하게 설명합니다. 모델이 세션 시작 부분에서 말한 내용을 무시하는 것이 아니라, 이를 검색할 수 있을 만큼 충분히 인지하지 못하는 것입니다. 한 시간 전에 지시한 수정 사항은 기술적으로는 대화에 남아 있지만, 기능적으로는 사라진 것과 다름없습니다.

이것이 바로 동일한 수정 사항이 20분 동안은 유지되다가 90분째에 사라지는 이유이며, 세션이 길어짐에 따라 프로젝트 지식 파일이 컨텍스트에서 밀려나는 현상의 원인이기도 합니다.

트리거가 없는 수정 사항은 단순한 잡학 지식에 불과합니다

대부분의 수정 사항은 조건부입니다. 배포할 때, 백엔드 명령어를 실행하기 전에, App.jsx를 수정했을 경우 등입니다. 계속 늘어나는 지침 파일에 기록된 조건은 모델이 스스로 적용 여부를 알아차려야 하는 텍스트로만 존재합니다. 명령어가 실행되기 직전에 "항상 먼저 cd를 하라"는 규칙을 표면으로 끌어올리는 메커니즘은 존재하지 않습니다.

따라서 실패의 원인은 단순히 규칙의 존재 여부 때문만이 아닙니다. 규칙이 필요한 순간과 아무런 연관이 없는 곳에 존재하기 때문입니다.

`CLAUDE.md`에 추가하기. 가장 먼저 취하기 좋은 조치이며, 안정적이고 무조건적인 규칙에는 실제로 잘 작동합니다. 하지만 한계는 위에서 언급한 바와 같습니다. 파일이 커지고 전체가 로드되며, 180번째 줄에 묻힌 규칙은 주의를 끌기 위해 다른 모든 정보와 경쟁해야 합니다. 이슈 #37314 보고서가 바로 이 접근 방식의 극단적인 결과를 보여줍니다.

수정 사항을 더 강력하게 반복하기. 대문자 사용, "중요:", "절대 금지" 등의 표현을 씁니다. 약간의 효과는 있지만 확장성이 없습니다. 6개의 규칙이 모두 소리를 지르고 있으면 그 어떤 것도 강조되지 않기 때문입니다.

수정이 두 번 실패한 후 `/clear` 실행하기. 숙련된 사용자들이 추천하는 실제 기술입니다. 두 번의 시도 후에도 수정이 적용되지 않으면, 실패한 컨텍스트를 계속 쌓아두기보다 세션을 초기화하는 것이 좋습니다. 효과적이고 확실한 방법이지만, 해당 세션에서 유용했던 정보까지 모두 잃게 됩니다.

세션을 명확하게 유지하기 위해 `/compact` 사용하기. 대화를 압축하여 모델이 계속 진행할 수 있도록 함으로써 긴 세션 문제를 해결하는 데 도움이 됩니다. 하지만 압축은 정의상 손실이 발생하므로, 이 과정에서 수정 사항이 누락될 수도 있습니다.

수정 사항을 코드로 변환하기. 과소평가되어 있지만, 특정 유형의 수정 사항에는 이것이 가장 올바른 해답입니다. 이에 대해서는 아래에서 자세히 다루겠습니다.

복사해서 붙여넣을 수 있는 실행 노트 파일 유지하기. 외부적이고 영구적이기 때문에 작동하지만, 매 세션마다 어떤 수정 사항이 관련이 있는지 결정하고 붙여넣는 검색 시스템 역할을 사용자 본인이 직접 수행해야 합니다.

먼저 수정 사항을 두 개의 더미로 분류하세요. 이 단계가 차이를 만듭니다.

첫 번째 더미: 기계화할 수 있는 수정 사항. "항상 먼저 backend/로 이동할 것." "App.jsx를 변경한 후에는 항상 dist를 다시 빌드할 것." "배포 전에 커밋할 것." GitHub 이슈에 등장하는 모든 예시가 이 더미에 속합니다. 이 경우 솔직한 권장 사항은 메모리 레이어가 아닙니다. 대신 이동을 대신 해주는 npm 스크립트, 재빌드를 수행하는 Makefile 타겟, pre-commit 훅, 커밋되지 않은 배포 시 실패하는 CI 검사 등을 구축하는 것입니다. 에이전트가 위반할 수 없는 규칙이 기억해야 하는 규칙보다 훨씬 강력하며, 미래의 자신으로부터 스스로를 보호해 줍니다. 이 글에서 단 한 가지만 얻어가야 한다면 바로 이것을 선택하세요.

두 번째 더미: 기계화할 수 없는 수정 사항. "업스트림이 실패 시 200을 반환하므로 어댑터 레이어에서 해당 패턴을 허용합니다." "고객이 3월에 모달 방식을 거절했습니다." "레거시 임포터는 4분기에 교체될 예정이므로 리팩토링하지 마세요." 어떤 스크립트도 이러한 판단을 강제할 수 없습니다. 이것이 바로 영구적인 곳에 기록하고, 짧게 유지하며, 관련이 있을 때 표면화해야 하는 정보들입니다. 그리고 여기서 외부 메모리 레이어가 진가를 발휘합니다. 수정 사항은 개별 세션 외부에 존재하며, 매 요청마다 로드되는 대신 관련 주제가 나올 때 검색되고, 주의를 끌 수 있을 만큼 충분히 짧게 유지됩니다.

MemoryLake는 두 번째 더미를 위해 구축되었습니다. 에이전트가 MCP나 API를 통해 읽을 수 있는 단일 저장소로, 매주 길어지는 지침 파일에 결정을 누적하는 대신 작업 과정에서 도출된 결정과 제약 조건을 보관합니다.

경계를 분명히 밝힐 필요가 있습니다. 이슈 #37314가 바로 이를 증명하는 사례이기 때문입니다. 메모리 레이어가 모델의 준수를 보장하지는 않습니다. 에이전트가 읽은 내용에 따라 행동할지 여부는 모델의 동작 방식에 달려 있으며, 어떤 저장 시스템도 이를 제어할 수 없습니다. 달라지는 것은 가용성과 형태입니다. 제약 조건이 완전히 누락되거나 180번째 줄에 묻히는 대신, 관련이 있는 순간에 최신의 상태로 짧게 제공됩니다. 이는 실질적인 개선이며 보장책은 아닙니다. 그렇지 않다고 말하는 사람이 있다면 그것은 과장 광고입니다.

1단계: API 키 생성

키를 생성하고 약 30초 만에 첫 번째 요청을 완료하세요. 커밋할 위험이 있는 설정 파일 대신 환경 변수나 보안 관리자(secret manager)에 보관하세요.

2단계: 첫 번째 메모리 업로드

두 번째 더미의 수정 사항이 담긴 문서, 이미지, 파일을 업로드하세요. 결정 사항과 그 이유, 아키텍처 노트, "이것을 시도했으나 실패한 이유"에 대한 기록 등이 해당됩니다. 깔끔하게 요약된 내용보다는 원본 소스를 업로드하는 것이 좋습니다. 수정 사항 뒤에 숨겨진 이유는 대개 요약 과정에서 생략되기 마련이며, 그 이유야말로 불필요한 재논쟁을 막아주는 핵심 요소이기 때문입니다.

3단계: AI 및 에이전트 연결

Claude, Codex, OpenClaw 및 기타 AI 에이전트가 MCP 또는 API를 통해 메모리에 액세스할 수 있도록 설정하세요. Claude Code는 MCP 서버를 지원하므로 설정 항목만 추가하면 됩니다. 이렇게 하면 다른 에이전트에서도 동일한 저장소를 읽을 수 있습니다. 도구를 바꾼다고 해서 수정 사항의 유효성이 사라지는 것은 아니기 때문에 이는 매우 중요합니다.

가장 즉각적인 변화는 CLAUDE.md 파일의 크기가 더 이상 늘어나지 않는다는 점입니다. 기계화할 수 있는 규칙은 스크립트와 훅이 되고, 판단이 필요한 수정 사항은 저장소로 이동합니다. 남는 것은 모델이 실제로 집중할 수 있는 짧은 상시 규칙 파일뿐이며, 이는 주의력 결핍 문제에 대한 임시방편이 아닌 근본적인 해결책입니다.

두 번째는 다섯 번째 반복이 멈춘다는 것입니다. 모델이 더 유순해졌기 때문이 아니라, 두 가지 범주가 각각에 적합한 메커니즘으로 처리되기 때문입니다. 빌드 순서 오류는 발생할 수 없게 되었고, 판단이 필요한 결정 사항은 기억에 의존하는 대신 검색이 가능해졌습니다.

세 번째는 수정 사항이 감사 가능한 형태로 세션 경계를 넘어 유지된다는 점입니다. 문제가 발생했을 때 어디에 기록했는지 찾아 헤매는 대신 단 하나의 레코드를 편집하면 됩니다. 또한 수정 사항이 실제로 캡처되었는지 여부를 확인할 수 있는데, 대개의 경우 이것이 문제의 원인입니다.

그리고 도구의 경계도 넘어섭니다. "레거시 임포터를 리팩토링하지 말라"는 규칙은 Cursor와 Codex에서도 동일하게 적용됩니다. CLAUDE.md에 보관하면 Claude Code 전용 사실이 되지만, 공유 저장소에 보관하면 프로젝트 전체의 사실이 됩니다. 이는 Claude Code에 메모리 레이어를 추가하는 것이 이번 분기에 사용하는 에이전트보다 더 오래 지속되는 이유이기도 합니다.

기계화할 수 있는 것은 모두 기계화하세요

수정 사항을 기록하기 전에 스크립트, 훅, 또는 CI 검사를 통해 오류 발생을 원천 차단할 수 있는지 자문해 보세요. 가능하다면 그렇게 하세요. 위에 보고된 사례의 모든 예시는 기계화가 가능했음에도, 제보자는 한 줄짜리 npm 스크립트를 추가하는 대신 메모리를 다섯 번이나 업데이트했습니다. 이는 제보자를 비판하려는 것이 아닙니다. 규칙을 작성하는 행위가 코드를 작성하는 것과 유사하게 느껴지기 때문에 빠지기 쉬운 함정입니다.

지침만 적지 말고 트리거를 함께 작성하세요

"데이터베이스 컬럼에 snake_case를 사용하세요"라는 지침은 약합니다. "db/migrations/에 마이그레이션을 추가할 때 컬럼 이름에 snake_case를 사용하세요. ORM 매핑이 이를 전제합니다"라고 작성하면 모델이 인식할 수 있는 조건과 의심 없이 따를 수 있는 이유를 제공하게 됩니다. 트리거를 명시한 수정 사항이 단순한 선호도만 나열한 수정 사항보다 훨씬 더 잘 유지됩니다.

항상 로드되는 파일은 의도적으로 짧게 유지하세요

CLAUDE.md 파일의 모든 줄은 모든 작업마다 로드되며 다른 모든 줄과 주의력을 두고 경쟁합니다. 이를 희소 자원으로 취급하세요. 직접 다시 읽어볼 만한 분량으로 제한하고 상시 규칙만 남겨두세요. 그 외의 모든 것은 검색 시스템으로 보내야 합니다. 300줄짜리 지침 파일이 60줄짜리 파일보다 다섯 배 더 효과적인 것은 아닙니다. 오히려 긴 세션에서의 주의력 결핍 문제로 인해 상황이 더 악화될 뿐입니다.

수정이 두 번 실패하면 중단하고 접근 방식을 바꾸세요

수정 사항이 두 번 적용되지 않았다면 세 번째 반복한다고 해서 해결되지 않습니다. 기계화하거나, 검색 가능한 짧은 레코드로 이동하거나, 세션을 초기화하고 새로 시작하세요. 이미 수정에 실패한 컨텍스트가 가득한 곳에 동일한 수정을 반복하는 것은 가장 비효율적인 방법입니다.

넘어가기 전에 수정 사항을 커밋하세요

해당 이슈의 marmot.svg 사례는 깊이 새겨볼 만합니다. 수정 사항이 적용되었으나 커밋되지 않아 유실된 경우입니다. "망각했다"고 생각한 것 중 일부는 실제로는 "그 어디에도 영구 저장되지 않았다"는 뜻이며, 여기에는 git도 포함됩니다.

Claude Code가 수정을 망각하는 데는 두 가지 서로 다른 이유가 있으며, 그 해결책은 서로 대체될 수 없습니다. 대부분의 경우 수정 사항이 영구적인 곳에 기록되지 않아 기억할 대상 자체가 없었습니다. 때로는 — 2026년 3월 claude-code 레포지토리에 보고된 이슈처럼, 동일한 문제에 대해 메모리 파일을 다섯 번 이상 업데이트했음에도 제보자가 메모리 시스템이 "지식을 캡처하지만 행동에 안정적으로 영향을 미치지는 못한다"고 결론지은 것처럼 — 기록되었음에도 실행되지 않는 경우가 있습니다.

그러므로 이 둘을 분리하세요. 스크립트나 훅으로 강제할 수 있는 것은 기계화하세요. 위반할 수 없는 규칙이 기억해야 하는 규칙보다 강력하기 때문입니다. 판단이 필요한 수정 사항은 필요한 순간에 짧고 최신의 상태로 검색할 수 있는 저장소에 보관하고, 항상 로드되는 지침 파일은 모델이 실제로 집중할 수 있을 만큼 작게 유지하세요. 이 조합만이 두 가지 실패 모드를 모두 해결할 수 있습니다. 어느 하나만으로는 불가능합니다.