[Claude 메모리] CLAUDE.md와 /memory 운영법

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Claude 메모리을 현업 개발자 관점에서 정리해보겠습니다. Claude Code를 어느 정도 쓰기 시작하면 단순 질문보다 팀 규칙, 권한, 비용, 메모리처럼 운영에 가까운 문제가 더 중요해집니다.

Claude Code에서 좋은 결과가 나오기 시작하면 다음 고민은 “이 지시를 매번 다시 말하지 않게 할 수 없을까?”입니다. 이때 핵심이 CLAUDE.md와 /memory입니다.

Claude 메모리는 Claude Code가 세션을 넘어 프로젝트 규칙, 개인 선호, 조직 정책을 기억하도록 CLAUDE.md 계층과 /memory 명령으로 관리하는 기능입니다.

---

1. Claude 메모리이 중요한 이유

AI 코딩 도구는 컨텍스트가 좋아야 잘 일합니다. 하지만 매번 빌드 명령, 코드 스타일, 금지 패턴, 테스트 규칙을 대화로 설명하는 것은 낭비입니다.

공식 메모리 문서는 enterprise policy, project memory, user memory, local project memory 같은 계층을 설명합니다. 각 위치의 목적을 나누면 팀 규칙과 개인 선호가 충돌하지 않습니다.

• 프로젝트 공통 규칙은 `./CLAUDE.md`로 공유할 수 있습니다.
• 개인 선호는 `~/.claude/CLAUDE.md`에 둘 수 있습니다.
• 조직 정책은 enterprise memory로 배포할 수 있습니다.
• `@path` import로 README, package.json, 별도 지침 파일을 불러올 수 있습니다.

구분	개인 사용	팀 운영
규칙 전달	매 대화마다 설명	CLAUDE.md로 자동 로드
개인 취향	프로젝트 파일에 섞임	user memory 또는 import로 분리
문서 연결	Claude가 파일을 찾아야 함	@README, @docs/*.md import 사용

---

2. 공식 구조로 이해하기

Claude Code는 시작 시 메모리 파일을 자동으로 컨텍스트에 로드합니다. 현재 작업 디렉터리에서 상위 경로를 재귀적으로 확인하고, 하위 디렉터리의 CLAUDE.md는 해당 하위 파일을 읽을 때 포함될 수 있습니다.

구성 요소	공식 동작 기준	실무 적용 포인트
Enterprise memory	조직 전체 정책	보안, 컴플라이언스, 회사 표준
Project memory	./CLAUDE.md	아키텍처, 테스트 명령, 팀 규칙
User memory	~/.claude/CLAUDE.md	개인 스타일과 선호 도구

메모리는 많이 넣을수록 좋은 것이 아닙니다. 오래된 규칙과 중복 지시가 쌓이면 Claude가 어떤 기준을 따라야 할지 모호해집니다.

Start Claude Code
  -> Load enterprise memory
  -> Load project CLAUDE.md
  -> Load user memory
  -> Follow imports up to allowed depth
  -> Use /memory to inspect or edit

---

3. 실무 설정 예시

프로젝트 메모리는 짧고 구조화된 지침으로 시작하는 것이 좋습니다. 빌드 명령, 테스트 명령, 코드 스타일, 금지 행동을 먼저 적습니다.

# Project Instructions

- Run npm test before reporting completion.
- Prefer small PRs under 300 changed lines.
- Do not edit generated files in dist/.
- Use src/api/client.ts for external API calls.

문서가 이미 있다면 import를 활용하세요. README, package.json, 별도 테스트 가이드가 바뀌어도 CLAUDE.md 본문을 계속 복사할 필요가 줄어듭니다.

# Project Context

See @README.md for overview.
Use @package.json for scripts.
Follow @docs/testing.md for test strategy.

추천 적용 순서

1. `/init`으로 기본 CLAUDE.md를 만들거나 직접 작성합니다.
2. 팀 공통 규칙과 개인 선호를 분리합니다.
3. 긴 문서 내용은 복사하지 말고 import합니다.
4. `/memory`로 로드된 메모리를 확인합니다.
5. 월 1회 오래된 규칙과 중복 지시를 정리합니다.

---

4. 팀 워크플로우에 넣는 방법

팀에서는 CLAUDE.md를 README처럼 관리하는 것이 좋습니다. 코드와 함께 리뷰되고, 변경 이유가 커밋에 남아야 합니다.

반면 개인 취향은 프로젝트 메모리에 넣지 않는 편이 좋습니다. 에디터 선호, 임시 URL, 개인 테스트 데이터는 user memory나 별도 import 파일로 분리하는 것이 안전합니다.

상황	추천 방식	주의점
새 프로젝트 시작	/init 후 정리	자동 생성 내용을 그대로 방치하지 않기
팀 규칙 변경	PR로 CLAUDE.md 수정	개인 취향 섞지 않기
개인 선호 추가	# shortcut 또는 /memory	팀 파일에 커밋하지 않기

• 메모리는 구체적 문장으로 작성합니다.
• 명령어는 실제 프로젝트에서 통과하는 명령만 넣습니다.
• 중복 규칙은 하나로 합칩니다.
• 폐기된 CLAUDE.local.md 방식보다 import 기반 분리를 우선합니다.

---

5. 비슷한 기능과 비교하기

Claude 메모리는 Slash Command나 Hooks와 목적이 다릅니다. 메모리는 배경 규칙, 커맨드는 반복 작업, Hooks는 실행 전후 제어입니다.

대안	강점	한계	추천 사용처
CLAUDE.md	프로젝트 배경과 규칙을 자동 제공	오래되면 오히려 혼란 유발	팀 표준과 아키텍처 설명
Slash Command	반복 프롬프트 실행	배경 규칙 저장에는 부적합	PR 리뷰, 테스트 작성
Hooks	도구 실행 시점에 자동 개입	지침 문서 역할은 약함	위험 명령 차단과 검증

비교의 핵심은 기능 이름이 아니라 운영 경계입니다. 같은 자동화라도 개인 로컬 편의인지, 프로젝트 공통 규칙인지, 조직 보안 정책인지에 따라 저장 위치와 승인 흐름이 달라져야 합니다.

---

6. 도입 전 체크리스트와 실수 방지

메모리 운영의 실패는 대부분 과잉 저장에서 나옵니다. “언젠가 도움 될 것 같은 말”을 다 넣으면 Claude는 중요한 규칙을 구분하기 어려워집니다.

체크 항목	좋은 기준	위험 신호
구체성	명령과 파일 경로를 명시	좋은 코드 작성 같은 추상 문구
분리	팀 규칙과 개인 선호 분리	모든 취향을 프로젝트에 커밋
정리	정기적으로 업데이트	초기 생성 후 방치

흔한 실수

• CLAUDE.md에 긴 문서를 복사해 컨텍스트를 낭비하는 실수
• 개인 환경 경로를 팀 파일에 넣는 실수
• 바뀐 테스트 명령을 수정하지 않는 실수
• 모순되는 규칙을 여러 위치에 남기는 실수

---

7. 앞으로의 활용 방향

Claude 메모리는 앞으로 AI 코딩 온보딩의 핵심 문서가 될 가능성이 큽니다. 새 팀원이 README를 읽듯, AI도 CLAUDE.md를 통해 프로젝트 문화를 배웁니다.

특히 대규모 저장소에서는 루트 메모리와 하위 디렉터리 메모리를 나눠 모듈별 규칙을 제공하는 방식이 더 중요해질 것입니다.

• 프로젝트별 AI 온보딩 문서 표준화
• 모듈별 CLAUDE.md 운영
• 개인 선호의 import 기반 분리
• 메모리 변경 리뷰와 품질 관리

---

마무리

정리하면 Claude 메모리은 Claude Code를 개인 생산성 도구에서 팀 개발 워크플로우로 끌어올리는 핵심 운영 주제입니다. 처음부터 완벽한 표준을 만들기보다, 반복되는 작은 문제 하나를 규칙으로 고정하는 방식이 가장 현실적입니다.

Claude 메모리는 거창한 지식베이스가 아닙니다. Claude가 매번 물어보지 않아도 되는 팀의 약속을 짧고 정확하게 적어두는 운영 문서입니다.

이 글이 도움이 되셨다면 댓글로 현재 Claude Code에서 가장 자주 반복하는 작업을 남겨주세요. 다음 글에서 Claude 메모리을 더 실전적인 예제로 이어가겠습니다.