[Claude Code] 클로드 코드 rules란 무엇인가? - 모듈형 메모리 활용법

[Claude Code] 클로드 코드 CLAUDE.md 메모리 파일 사용법 총정리

 

이전 포스팅에서는 클로드 코드의 기본 메모리 파일인 CLAUDE.md의 종류와 import 문법, 작성 모범사례를 다뤘습니다. 대부분의 프로젝트에서는 이 정도만으로도 충분하지만, 프로젝트가 커지고 규칙이 많아지면 두 가지 불편함이 생기게 됩니다.

• 규칙 파일을 새로 만들 때마다 CLAUDE.md 파일에 import 문을 계속 추가해야 하는 불편함이 있습니다. 한두 개면 괜찮지만 다섯 개, 열 개 이상이 되면 관리가 번거로워집니다.
• 특정 규칙을 특정 디렉터리나 특정 확장자 파일에만 적용하고 싶은 경우가 있습니다. import 문법은 해당 파일이 무조건 로드되는 방식이기 때문에, 조건부로 규칙을 적용하고 싶은 요구사항은 만족시킬 수 없습니다.

이럴 때 사용할 수 있는 것이 바로 모듈형 메모리입니다.

 

모듈형 메모리 기본 구조

모듈형 메모리의 기본 구조는 간단합니다. 프로젝트 안의 .claude 디렉터리에 rules라는 디렉터리를 만들고, 그 하위에 주제별로 md 파일을 위치시키면 됩니다.

.claude/
  rules/
    code-style.md
    git-rules.md

.claude/rules 디렉터리는 특별한 디렉터리로, 이 디렉터리 안에 있는 모든 마크다운 파일은 클로드 코드가 실행될 때 자동으로 프로젝트 메모리에 로드됩니다. 즉 앞서 살펴본 CLAUDE.md 파일과 동일한 우선순위를 갖는 메모리 파일이라고 볼 수 있습니다. 다만 rules 디렉터리를 활용하면 특정 주제별로 파일을 깔끔하게 나눠서 관리할 수 있다는 장점이 있습니다.

 

실제로 /memory 명령어를 통해 현재 프로젝트에 로드되어 있는 메모리를 확인할 수 있으며, rules 디렉터리 안에 파일을 새로 만들고 다시 확인하면 모듈형 메모리가 로드된 것을 볼 수 있습니다. 코드 스타일, 깃 규칙, 디자인 시스템 등 특정 주제와 관련된 규칙은 CLAUDE.md 메인 파일에 기재하지 않고 이렇게 rules 디렉터리로 분리해서 관리하면 매우 편리합니다.

 

정리하면, 프로젝트 안에 이미 존재하는 특정 파일을 참고하고 싶을 때는 import 문법을 사용하고, 특정 주제별로 지침을 나눠서 관리하고 싶을 때는 rules 디렉터리를 활용한 모듈형 메모리를 사용하는 것입니다.

 

특정 파일에만 규칙 적용하기: path frontmatter와 glob 패턴

모듈형 메모리 파일에는 본문에 지침을 기재하고, 상단에는 프론트매터를 지정할 수 있습니다. 이 프론트매터의 path 필드를 활용하면 특정 파일에만 규칙을 적용할 수 있습니다.

---
path: src/api/**/*.ts
---

이 디렉터리의 API 코드는 다음 규칙을 따릅니다.
- 모든 함수는 에러 핸들링을 포함해야 합니다.
- 응답 타입은 반드시 인터페이스로 정의합니다.

위 예시처럼 path 필드에 src/api/**/*.ts라는 글롭(glob) 패턴을 지정하면, src/api 디렉터리 하위의 어떤 깊이에 있든 확장자가 .ts인 파일에만 해당 규칙이 적용됩니다. 여기서 별표 두 개(**)는 하위 폴더의 깊이와 무관하게 모든 경로를 의미하고, 그 뒤의 *.ts는 확장자가 ts인 모든 파일을 의미합니다.

 

글롭 패턴은 파일 경로를 하나하나 나열하는 대신 조건에 맞는 파일을 한꺼번에 지정하는 문법입니다. 몇 가지 예시는 다음과 같습니다.

• *.md: 프로젝트 루트에 있는 모든 마크다운 파일
• **/*.ts: 모든 디렉터리에 있는 모든 타입스크립트 파일

이러한 글롭 패턴은 개발에서 자주 사용되는 표현이므로 알아두면 여러모로 유용합니다. 규칙이 많아지면 rules 디렉터리 하위에 다시 폴더를 나눠서 관리할 수도 있습니다. 예를 들어 프론트엔드와 백엔드 코드를 함께 관리하는 프로젝트라면 frontend, backend라는 폴더를 만들어 그 하위에 각각의 규칙 파일을 묶어서 관리할 수 있습니다.

 

이러한 모듈형 규칙은 프로젝트 레벨뿐만 아니라 사용자 레벨에서도 설정할 수 있습니다. 사용자 홈 디렉터리의 .claude/rules 하위에 파일을 위치시키면 나만의 코딩 선호도나 작업 방식을 별도로 관리할 수 있으며, 이 역시 클로드 코드가 실행될 때 자동으로 로드됩니다.

 

모듈형 메모리 모범사례

공식 문서에서 권장하는 모듈형 메모리 작성 모범사례는 다음과 같습니다.

• 각 파일은 하나의 주제만 다룹니다. 파일 이름만 보고도 내용을 알 수 있도록 짓는 것이 좋습니다. rule1.md처럼 짓기보다는 code-style.md처럼 이름만으로 어떤 규칙인지 알 수 있게 지어야 합니다.
• path 프론트매터는 꼭 필요할 때만 사용합니다. 조건부 규칙이 많아지면 오히려 관리가 복잡해질 수 있으므로, 정말 특정 파일에만 적용되어야 하는 규칙에만 사용하는 것이 좋습니다.
• 관련된 규칙끼리 그룹화합니다. 앞서 설명한 것처럼 관련 있는 규칙들을 하위 폴더로 묶어서 관리하면 관리가 쉬워집니다.

 

언제 무엇을 쓸까

지금까지 살펴본 메모리 관리 방법을 한 줄로 요약하면 다음과 같습니다.

• CLAUDE.md 파일로 시작합니다. 대부분의 프로젝트는 이거 하나로도 충분합니다.
• 이미 프로젝트에 존재하는 문서(README.md, package.json 등)는 import 문법으로 연결합니다.
• 규칙이 많아져서 CLAUDE.md 파일이 길어지면 rules 디렉터리를 활용한 모듈형 메모리로 나눕니다.

 

참고: 오토 메모리(실험적 기능)

추가로 클로드 코드에는 오토 메모리라는 기능도 있는데요. 이 기능은 현재 영문 공식 문서에만 소개되어 있으며, 아직 리서치 프리뷰 단계인 실험적 기능입니다. 사용자가 직접 작성하는 CLAUDE.md 파일과 달리, 오토 메모리는 클로드 코드가 세션 중에 학습한 내용을 스스로 기록하는 노트라고 볼 수 있습니다.

 

/memory 명령어에서 오토 메모리를 선택하면, 사용자 홈 디렉터리의 .claude/projects 하위 해당 프로젝트 폴더 안에 있는 memory 디렉터리를 확인할 수 있습니다. 오토 메모리는 이 디렉터리 안에 memory.md 파일 형태로 기록되며, 프로젝트 패턴, 자주 발생하는 문제와 해결법, 아키텍처, 사용자의 선호사항 등을 저장합니다.

 

작동 방식은 다음과 같습니다. 세션을 시작할 때 memory.md 파일의 앞부분 200줄까지만 자동으로 로드되며, 200줄을 초과하는 내용은 자동으로 로드되지 않습니다. 200줄을 넘길 것 같은 경우에는 클로드가 스스로 특정 주제별 파일로 분리하며, 이렇게 분리된 파일은 필요한 순간에만 선택적으로 로드됩니다. 이 기능은 /memory 명령어에서 온오프 전환이 가능합니다.

 

다만 아직 실험 단계인 기능이라 항상 기록이 남는 것은 아니며, 크게 신경 써서 다뤄야 하는 기능은 아닙니다. 이러한 기능이 있다는 정도로 가볍게 참고해두면 충분합니다.