Claude Code 메모리 운영법: CLAUDE.md와 auto memory를 팀 규칙으로 쓰는 방법

AI 코딩 도구가 같은 실수를 반복한다면 메모리 설계 문제입니다

Claude Code를 쓰다 보면 “지난번에도 말했는데”라는 순간이 생깁니다. 테스트 명령을 잘못 쓰거나, 프로젝트 폴더 규칙을 어기거나, 팀에서 금지한 패턴을 다시 제안하는 식입니다. 이때 매번 채팅으로 설명하면 사람도 지치고 도구도 일관성을 잃습니다. 공식 문서 기준으로 Claude Code는 세션마다 fresh context로 시작하고, 지식을 이어가기 위해 CLAUDE.md와 auto memory라는 두 가지 메커니즘을 씁니다.

CLAUDE.md는 사용자가 작성하는 지속 지시문입니다. 프로젝트 구조, 빌드 명령, 코딩 규칙, 팀 워크플로우처럼 매번 알아야 하는 내용을 담습니다. auto memory는 Claude가 사용자의 correction과 preference를 바탕으로 쌓는 학습 메모입니다. 둘 다 세션 시작 시 context로 로드되지만, 강제 보안 정책은 아닙니다. 문서는 차단이 필요한 행동은 PreToolUse hook 같은 별도 장치를 쓰라고 설명합니다.

즉 메모리는 “기억”이지 “방화벽”이 아닙니다. 이 차이를 이해해야 팀 규칙을 제대로 설계할 수 있습니다.

CLAUDE.md에 넣을 것과 넣지 말 것

CLAUDE.md에는 새 팀원이 프로젝트에 들어왔을 때 반드시 알아야 할 사실을 넣는다고 생각하면 됩니다. 예를 들어 빌드 명령, 테스트 명령, 디렉터리 구조, 브랜치 전략, 코드 스타일, 금지된 라이브러리, 배포 절차입니다. 문서에는 같은 실수가 두 번째 반복되거나, 코드 리뷰에서 Claude가 알아야 했던 내용이 잡히거나, 매 세션 반복해서 설명하는 내용이 있으면 CLAUDE.md에 넣으라고 설명합니다.

반대로 너무 긴 절차나 특정 하위 디렉터리에만 적용되는 규칙은 CLAUDE.md에 다 넣으면 안 됩니다. 모든 세션에 불필요한 규칙이 들어가면 오히려 중요한 정보가 묻힙니다. 문서 역시 multi-step procedure나 코드베이스 일부에만 관련된 내용은 skill 또는 path-scoped rule로 옮기라고 안내합니다.

실무 기준으로는 세 문장 규칙을 추천합니다. 하나의 규칙은 “언제, 무엇을, 왜”가 드러나야 합니다. 예를 들어 “DB 마이그레이션 코드는 scripts/migrations에 두고, 실행 전 dry-run 로그를 남긴다. 운영 데이터 손실을 막기 위해서다.”처럼 씁니다. “조심해라”, “깔끔하게 해라” 같은 문장은 기억 가치가 낮습니다.

auto memory는 correction을 저장하는 곳입니다

auto memory는 사용자가 직접 모든 것을 문서화하지 않아도 Claude가 선호와 패턴을 저장하게 하는 장치입니다. 하지만 여기에 모든 프로젝트 규칙을 맡기면 안 됩니다. auto memory는 경험 기반 학습에 가깝고, 팀 합의 문서의 대체물이 아닙니다.

예를 들어 “우리 팀은 PR 설명에 테스트 결과를 꼭 넣어”라는 규칙은 CLAUDE.md에 들어가는 편이 낫습니다. 반면 “내가 리뷰 요청할 때는 결론부터 말해줘” 같은 개인 선호는 auto memory에 어울립니다. “지난번처럼 긴 설명보다 diff 중심으로 보여줘” 같은 correction도 auto memory가 유용합니다.

중요한 점은 auto memory도 context일 뿐이라는 사실입니다. 민감한 보안 정책, 금지 명령, 승인 요구사항은 hook이나 CI, branch protection으로 강제해야 합니다. AI에게 기억시키는 것과 시스템이 막는 것은 다릅니다.

scope를 나누면 규칙 충돌이 줄어듭니다

공식 문서는 CLAUDE.md가 여러 scope에 존재할 수 있다고 설명합니다. user instructions, project instructions, local instructions, managed policy처럼 위치에 따라 적용 범위가 달라집니다. 실무에서는 이 구조를 활용해야 합니다.

전역 사용자 규칙에는 개인 작업 방식만 둡니다. 예를 들어 “응답은 한국어로”, “명령 실행 전 위험도를 설명” 같은 규칙입니다. 프로젝트 CLAUDE.md에는 팀 전체가 공유해야 하는 빌드·테스트·아키텍처 규칙을 둡니다. local instructions에는 개인 환경 경로, 테스트 계정, 로컬 서버 포트처럼 공유하면 안 되거나 공유할 필요가 없는 내용을 둡니다.

이렇게 나누지 않으면 문제가 생깁니다. 개인 로컬 경로가 팀 문서에 들어가거나, 프로젝트 고유 규칙이 모든 저장소에 적용되거나, 보안상 공유하면 안 되는 정보가 repository에 올라갈 수 있습니다. 메모리 운영은 생산성 문제이면서 동시에 정보 경계 문제입니다.

좋은 메모리 규칙의 예시

나쁜 규칙은 추상적입니다. “코드를 잘 작성해라”, “보안을 고려해라”, “테스트를 잊지 마라”는 실행 기준이 없습니다. 좋은 규칙은 판단 기준과 명령을 함께 줍니다.

예시는 다음과 같습니다.

• API route를 수정하면 관련 integration test를 먼저 찾고, 없으면 최소 smoke test를 추가한다.
• 결제 관련 파일은 변경 전 owner approval을 요청하고, 테스트 카드 외 실제 결제 키를 사용하지 않는다.
• Next.js App Router에서 dynamic route 데이터는 cache key에 route parameter가 포함되는지 확인한다.
• 긴 migration 스크립트는 dry-run 모드와 rollback 계획을 같은 PR에 포함한다.
• UI 변경은 스크린샷 또는 접근성 체크 결과를 PR 설명에 남긴다.

이런 규칙은 Claude뿐 아니라 사람에게도 유용합니다. AI 도구 전용 문서가 아니라 팀 운영 문서로 취급해야 오래 갑니다.

운영 루프: 수정, 기록, 검증

메모리는 한 번 작성하고 끝나는 문서가 아닙니다. 팀에서 반복되는 correction을 모아 주기적으로 정리해야 합니다. 같은 실수가 두 번 나오면 규칙을 추가합니다. 규칙이 너무 길어지면 scope를 쪼갭니다. 규칙이 지켜지지 않으면 문장이 모호한지, 너무 많은 규칙이 한꺼번에 로드되는지, 실제로 hook이나 CI로 강제해야 할 문제인지 확인합니다.

검증도 필요합니다. Claude Code가 규칙을 읽었다고 가정하지 말고, 새 세션에서 “이 프로젝트의 테스트 명령과 금지 패턴을 요약해줘”처럼 확인할 수 있습니다. 프로젝트 규칙이 바뀌면 PR에 CLAUDE.md 변경도 포함하고, 왜 바뀌었는지 커밋 메시지에 남깁니다.

실행 체크리스트

• 같은 correction이 두 번 반복되면 CLAUDE.md 또는 auto memory에 기록합니다.
• 팀 공통 규칙은 프로젝트 CLAUDE.md, 개인 선호는 user/auto memory, 로컬 경로는 local instructions에 둡니다.
• 규칙은 “언제, 무엇을, 왜”가 드러나는 한두 문장으로 씁니다.
• 보안 차단, 위험 명령 제한, 배포 승인 같은 강제 정책은 memory가 아니라 hook, CI, branch protection으로 막습니다.
• 규칙이 길어지면 skill 또는 path-scoped rule로 분리합니다.
• 새 세션에서 핵심 규칙이 제대로 로드됐는지 요약을 요청해 검증합니다.

Claude Code 메모리 운영의 목표는 AI가 똑똑해 보이게 만드는 것이 아닙니다. 팀이 같은 설명을 반복하지 않고, 같은 실수를 줄이며, 책임 있는 자동화를 만드는 것입니다. 다음에 “이거 지난번에도 말했는데”라는 말이 나오면, 그 순간이 바로 문서화할 타이밍입니다.