CLAUDE.md 가이드 - 파일 위치, Rules, 메모리 구조 한 번에 보기

2026-03-29

#Etc#AI

CLAUDE.md 를 처음 잡을 때 가장 헷갈리는 건 파일 하나를 어디까지 책임지게 해야 하는지다.

프로젝트 공용 규칙, 디렉토리별 세부 규칙, 개인 메모리 성격의 정보가 한 번에 섞이기 시작하면 문서는 금방 길어지고, 정작 작업 기준은 더 흐려진다.

그래서 이번 글에서는 CLAUDE.md 치트시트에 나온 흐름을 따라가되, 항목만 옮기지 않고 실제 프로젝트에 적용하는 기준으로 다시 풀어보려 한다.

결국 중요한 것은 파일 하나를 잘 쓰는 방법보다, 규칙과 메모리를 어떤 구조로 운영해야 에이전트가 덜 흔들리는가다.

CLAUDE.md란

먼저 잡아야 할 것은 CLAUDE.md 의 성격이다. 이 파일을 README 비슷한 소개 문서로 생각하면 금방 어긋난다.
CLAUDE.md 는 프로젝트 설명문이라기보다, 에이전트가 작업할 때 붙들고 가야 하는 기준 문서에 더 가깝다.

보통 이 문서에는 아래 내용이 들어간다.

프로젝트가 무엇인지
어떤 기술 제약이 있는지
어떤 문서를 먼저 읽어야 하는지
어떤 작업 원칙을 지켜야 하는지
무엇을 하면 안 되는지

즉, "이 프로젝트에서는 어떤 기준으로 판단하고 행동해야 하는가"를 적는 문서라고 보면 된다.

README 가 저장소를 소개하는 문서에 가깝다면, CLAUDE.md 는 실제 작업 중 따라야 할 규칙을 정리하는 문서에 더 가깝다.
소개보다 작업 기준에 더 가까운 문서라고 생각하면 이해가 쉽다.

파일 위치

같은 내용이라도 어디에 두느냐에 따라 의미가 달라진다. 그래서 CLAUDE.md 는 문장보다 배치가 먼저라는 말이 나오는 편이다.

보통은 아래 세 단계로 생각하면 편하다.

전역 위치

사용자 환경 전반에 적용할 규칙을 두는 자리다. 개인 취향, 자주 쓰는 도구, 로컬 경로, 응답 스타일 같은 내용이 여기에 더 잘 맞는다.

프로젝트 루트

저장소 전체에 공통으로 적용할 원칙을 두는 자리다. 프로젝트 소개, 공통 코딩 스타일, 빌드/테스트 방식, 금지사항, 우선 읽어야 할 문서 목록이 여기에 들어간다.

하위 디렉토리

특정 폴더에서만 의미가 있는 세부 규칙을 두는 자리다. 예를 들어 contents/ 에는 글쓰기 규칙, components/ 에는 UI 규칙, scripts/ 에는 실행 주의사항을 둘 수 있다.

개인 취향은 전역에 두고, 팀이 같이 따라야 하는 기준은 프로젝트 안에 두고, 디렉토리별 예외는 하위에서 좁히는 방식이 가장 덜 꼬인다.

전역은 개인 취향, 프로젝트 루트는 공용 규칙, 하위 디렉토리는 세부 예외라고 먼저 나눠두면 구조가 훨씬 선명해진다.

예를 들면 경로는 아래처럼 잡을 수 있다.

~/.claude/CLAUDE.md
# 사용자 전역 규칙
# 어떤 프로젝트에 들어가도 공통으로 적용할 개인 기준

~/.claude/rules/*.md
# 전역 규칙을 주제별로 나눈 디렉토리
# 응답 스타일, 도구 선호, 로컬 작업 습관 같은 내용

./CLAUDE.md
# 프로젝트 루트 규칙
# 저장소 전체에 공통으로 적용할 기준

./docs/agents/common.md
# 프로젝트 공통 규칙 문서
# 모든 작업에서 먼저 읽게 할 공용 원칙

./docs/agents/frontend.md
# 프론트엔드 작업 전용 규칙 문서
# UI, 스타일, 컴포넌트 작업에 더 좁게 적용

./contents/CLAUDE.md
# contents 디렉토리 전용 규칙
# 포스트 작성, frontmatter, slug, 이미지 경로처럼 콘텐츠 작업에만 적용

./components/CLAUDE.md
# components 디렉토리 전용 규칙
# 공용 UI, 접근성, 컴포넌트 구조처럼 해당 폴더 작업에만 적용

이렇게 두면 전역 규칙, 프로젝트 공통 규칙, 디렉토리별 규칙이 자연스럽게 나뉜다.

여기서 docs/agents 는 예시일 뿐이고, 꼭 그 경로여야 하는 것은 아니다.
중요한 것은 공통 규칙이 어디 있는지 일관적일 것,
루트 CLAUDE.md 에서 먼저 읽을 문서를 명확히 가리킬 수 있을 것,
공통 규칙과 디렉토리별 규칙이 뒤섞이지 않을 것이다.

작성 원칙

규칙 문서는 잘 썼다는 느낌보다 잘 읽힌다는 느낌이 더 중요하다. 길고 친절한 설명문보다, 짧고 단정한 문장이 실제 작업에서는 훨씬 잘 버틴다.

예를 들어 아래 차이가 중요하다.

"코드를 깔끔하게 유지" 보다 "unused import 제거"
"문서 잘 관리" 보다 "디렉토리 구조 변경 시 문서 업데이트"
"가능하면 확인" 보다 "작업 전 frontmatter 먼저 확인"

이 차이가 중요한 이유는 단순하다. 추상적인 표현은 사람끼리도 다르게 읽히고, 에이전트는 더 쉽게 흔들린다. 그래서 아래 원칙 정도는 처음부터 잡고 가는 편이 좋다.

짧게 쓴다
애매한 표현을 줄인다
우선순위와 금지사항을 분명히 쓴다
파일 경로나 대상 범위를 같이 적는다

깔끔하게, 잘, 적절히 같은 표현은 사람끼리도 다르게 읽히는데, 에이전트에게는 더 모호하다.
그래서 추상어보다 작업 지시형 문장이 훨씬 안정적으로 동작한다.

Rules 분리

처음에는 루트 문서 하나로도 시작할 수 있다.
문제는 규칙이 늘어나기 시작한 뒤다. 공통 규칙, 프론트엔드 규칙, 글쓰기 규칙, 주의사항이 한 파일에 겹치기 시작하면, 문서는 길어지는데 기준은 오히려 덜 보인다.

예를 들어 이런 식이다.

공통 규칙은 공통 스타일 문서
프론트엔드 규칙은 프론트엔드 전용 문서
글쓰기 규칙은 블로그 포스트 작성 문서
특정 디렉토리 규칙은 해당 폴더의 문서

그래서 루트 CLAUDE.md 는 안내판처럼 두고, 세부 기준은 별도 문서로 빼는 편이 낫다.
이렇게 하면 루트 문서는 진입점 역할만 맡고, 각 주제 문서는 자기 역할에 집중할 수 있다.

규칙 문서가 많아지는 것 자체가 문제는 아니다.

문제는 서로 성격이 다른 규칙이 한 파일 안에 뒤섞이는 순간부터 시작된다.

실제로는 아래처럼 두는 방식이 가장 이해하기 쉽다.

프로젝트 루트
├── CLAUDE.md
│   # 저장소 전체 규칙의 진입점
└── docs/agents/
    ├── common.md
    │   # 공통 작업 규칙
    ├── frontend.md
    │   # 프론트엔드 전용 규칙
    ├── blog-post-writing.md
    │   # 글쓰기/콘텐츠 전용 규칙
    └── directory-structure.md
        # 디렉토리 역할 설명

루트 CLAUDE.md 에서는 세부 규칙을 전부 다시 쓰기보다, 어떤 문서를 어떤 순서로 먼저 읽을지 안내하는 편이 훨씬 낫다.

예를 들어 docs/agents 대신 아래처럼 둬도 전혀 문제는 없다.

./guides/common.md
./guides/frontend.md
./guides/content.md

또는

./.ai/common.md
./.ai/frontend.md
./.ai/blog.md

즉, 디렉토리 이름이 중요한 것이 아니라 역할과 읽는 순서가 더 중요하다.

전역과 프로젝트

여기서 갈리는 지점은 개인 취향과 공용 정책이다. 이 둘을 한 군데에 섞기 시작하면 규칙 문서는 금방 흐려진다.

전역에 더 잘 맞는 내용은 보통 아래와 같다.

개인 응답 스타일
개인 자동화 습관
자주 쓰는 도구
로컬 환경 설정

반대로 프로젝트 안에 있어야 하는 것은 이런 것들이다.

저장소 구조 설명
팀 공통 작업 방식
커밋/테스트/빌드 정책
금지사항
변경 시 함께 확인할 항목

협업 저장소에서는 이 원칙이 특히 중요하다. 팀 규칙은 저장소 안에서 완결되게 두고, 개인 습관은 전역 쪽에 남겨두는 편이 나중에 훨씬 덜 헷갈린다.

무엇이 팀 기준이고 무엇이 개인 선호인지 흐려지기 때문이다. 협업 저장소라면 누구나 같이 따라야 하는 기준이 먼저 보여야 한다.
보통은 전역 규칙 → 프로젝트 루트 규칙 → 하위 디렉토리 규칙처럼 범위를 좁혀 가는 흐름이 가장 이해하기 쉽다. 실제로 문서를 쓸 때도 이 순서를 의식해서,
위에서 공통 원칙을 잡고 아래로 갈수록 예외와 세부 규칙을 추가하는 방식이 잘 맞는다.

메모리와 규칙

처음 쓰면 규칙 문서와 메모리가 비슷해 보인다. 둘 다 "다음 작업에 도움이 되는 정보"처럼 보이기 때문이다. 그런데 실제로는 역할이 꽤 다르다.

구분	역할
CLAUDE.md, rules	항상 지켜야 하는 기준
memory	이어서 참고해야 하는 맥락과 히스토리

예를 들어 코드 스타일, 테스트 원칙, 금지사항은 규칙에 가깝다. 반면 최근 작업 배경, 이전 세션에서 합의한 예외 처리, 자주 반복하는 작업 메모는 메모리에 더 가깝다.

짧게 줄이면 이렇다. 규칙은 계속 유지되는 기준이고, 메모리는 이어서 가져갈 문맥이다.

Q. 메모리에는 무엇을 남기는 편이 좋을까?

A. 항상 지켜야 하는 원칙보다, 다음 세션에서도 다시 참고해야 하는 배경 정보를 남기는 편이 맞다. 최근 합의한 예외 처리,
반복 작업에서 자주 놓치는 포인트,
다음 작업 때 다시 봐야 하는 맥락이 여기에 더 잘 맞는다.

실무에서는 세션이 끝날 때 직접 파일을 열어 메모를 남기기보다,

에이전트에게 "오늘 합의한 예외사항을 MEMORY.md 에 한 줄로 요약해서 남겨줘"라고 바로 지시하는 습관이 더 편하다.

CLI 작업 흐름에서는 이 방식이 훨씬 자연스럽고, 메모를 남기는 비용도 확실히 줄어든다.

문서 작성법

문서가 길다고 규칙이 잘 전달되는 것은 아니다. 오히려 규칙 문서는 설명문처럼 쓸수록 힘이 빠지는 경우가 많다. 그래서 이 단계에서는
"어떻게 설명할까"보다 "어떻게 지시할까"에 더 가까워진다.

여기서 중요한 포인트는 세 가지다.

추상적인 표현을 줄인다

"잘", "깔끔하게", "적절히" 같은 단어는 해석이 너무 넓다. 에이전트가 따라야 할 문서라면 더 구체적으로 써야 한다.

대상 범위를 명확히 적는다

어느 파일, 어느 디렉토리, 어떤 작업에 적용되는지 같이 적어야 한다. 그래야 문서가 실제 작업 규칙으로 기능한다.

금지사항은 짧고 단정하게 쓴다

길게 설명하는 것보다 "무엇을 하지 말아야 하는가"를 짧게 못 박는 편이 더 잘 읽힌다.

결국 좋은 규칙 문서는 읽고 이해하는 문서라기보다, 읽고 바로 행동할 수 있는 문서에 가깝다.

문서가 친절한 것과 문서가 흐린 것은 다르다.

설명이 길어질수록 오히려 무엇을 해야 하는지가 덜 보일 수 있다.

메모리 사용법

메모리도 규칙 문서처럼 길게 적기 시작하면 금방 힘을 잃는다. 다음 세션에서 다시 바로 꺼내 쓸 수 있어야 의미가 있기 때문이다.

그래서 보통 아래 성격의 정보가 잘 맞는다.

최근에 합의한 작업 방식
다음에도 반복될 배경 정보
자주 까먹는 예외사항
특정 저장소에서만 통하는 실행 팁

반대로 모든 규칙을 메모리에 넣기 시작하면 구조는 금방 무너진다. 메모리는 규칙집이 아니라, 반복 작업을 이어주는 짧은 기록에 가깝게 두는 편이 낫다.

그렇지 않다. 메모리는 다음에 다시 꺼내 써도 바로 이해되는 길이가 더 중요하다. 길고 자세한 기록보다,
다음 작업에 바로 연결되는 짧은 문장이 훨씬 실용적이다.

메모리 경로 예시는 보통 아래처럼 떠올리면 된다.

~/.claude/projects/<project>/memory/MEMORY.md
# 프로젝트 단위 대표 메모 파일
# 다음 세션에서도 이어서 봐야 할 핵심 배경 정보

~/.claude/projects/<project>/memory/build-notes.md
# 빌드, 실행, 배포 관련 반복 메모

~/.claude/projects/<project>/memory/content-rules.md
# 콘텐츠 작업 중 자주 반복되는 메모
# 단, 항상 지켜야 하는 규칙이라면 memory 보다 rules 쪽이 더 잘 맞는다

여기에는 규칙집보다, 다음 세션에서 다시 참고해야 할 작업 메모를 남기는 편이 맞다.

자주 하는 실수

실제로 자주 어긋나는 지점은 늘 비슷하다. 기능을 몰라서가 아니라, 규칙과 메모리 구조를 헷갈려서 틀어지는 경우가 더 많다.

대표적으로는 이런 문제들이다.

규칙이 너무 추상적이라서 해석이 제각각인 경우
공통 규칙과 개인 취향이 섞인 경우
메모리와 규칙의 역할이 뒤섞인 경우
한 파일에 모든 내용을 넣어서 읽히지 않는 경우

결국 문서 구조를 잘 나누는 것이 작업 품질의 절반이라는 말과도 연결된다.

가장 흔한 실패는 규칙이 없는 경우보다, 규칙은 많은데 우선순위가 보이지 않는 경우에 더 가깝다.

GitHub 레포 연동

GitHub 레포와 함께 작업할수록 이 구조는 더 중요해진다. 에이전트는 코드만 읽는 것이 아니라,
저장소 안에 있는 규칙 문서까지 같이 읽으면서 작업 기준을 만든다.

즉, 레포가 코드의 진실 공급원이라면, CLAUDE.md 는 작업 방식의 진실 공급원에 가깝다.

그래서 레포 중심으로 협업할수록 규칙 문서는 프로젝트 안쪽에, 더 명시적으로 두는 편이 낫다.

코드는 레포가 기억하고, 작업 기준은 CLAUDE.md 가 기억한다고 생각하면 이해가 쉽다.

실전 템플릿

처음부터 완성형 문서를 만들 필요는 없다. 오히려 처음에는 작은 템플릿 하나로 시작하는 편이 훨씬 현실적이다.

아래 정도면 충분히 출발할 수 있다.

# 프로젝트 이름

## 먼저 읽을 문서
- ./docs/agents/common.md
- ./docs/agents/frontend.md
- ./docs/agents/blog-post-writing.md

## 프로젝트 설명
- Next.js 기반 정적 사이트
- MDX 콘텐츠 중심 구조

## 작업 원칙
- 콘텐츠 수정 전 frontmatter 먼저 확인
- slug, URL, 발행일은 임의 변경 금지
- 정적 export 와 충돌하는 기능 도입 금지

## 디렉토리 해석
- contents/posts/ : 포스트 원본
- components/ : 공용 UI
- lib/ : 콘텐츠 로더와 유틸

## 피해야 할 것
- 서버 런타임 의존 기능 추가
- 실제 없는 이미지 경로 삽입

중요한 것은 템플릿의 완성도가 아니라, 프로젝트 제약과 우선순위가 바로 읽히는가다.

그럴 필요는 없다. 오히려 처음에는 작은 템플릿으로 시작하고,
실제로 반복해서 부딪히는 규칙만 조금씩 추가하는 편이 유지보수에 더 유리하다.

그리고 루트 CLAUDE.md 에는 이런 식의 안내가 들어가면 읽는 순서를 잡기 쉽다.

## 먼저 읽을 문서
- ./docs/agents/common.md
- ./docs/agents/frontend.md
- ./docs/agents/blog-post-writing.md

## 디렉토리별 규칙
- contents/ 작업 시 -> ./contents/CLAUDE.md
- components/ 작업 시 -> ./components/CLAUDE.md

이렇게 적어두면 에이전트가 공통 규칙부터 읽고, 실제로 들어가는 디렉토리에 맞는 세부 규칙으로 내려가는 흐름을 만들기 쉽다.

여기서도 ./docs/agents 는 하나의 예시일 뿐이다. 팀에서 ./guides, ./docs/rules, ./.ai 같은 경로를 쓰고 있다면 그 구조를 그대로 써도 된다.

핵심 요약

끝까지 보고 나면 결국 핵심은 몇 가지로 줄어든다. 처음에는 아래 다섯 가지만 먼저 잡아도 충분하다.

CLAUDE.md 는 소개 문서가 아니라 작업 기준 문서다.
파일 위치에 따라 적용 범위가 달라진다.
규칙이 많아지면 rules 문서로 분리하는 편이 낫다.
memory 는 규칙이 아니라 작업 맥락을 이어주는 용도다.
처음에는 작은 템플릿으로 시작해도 충분하다.

결국 이 치트시트는 파일 하나를 예쁘게 쓰는 법보다, 에이전트가 프로젝트를 덜 흔들리게 이해하도록 규칙과 맥락을 어떤 구조로 둘 것인지 정리한 가이드에 가깝다.

정리

✔ CLAUDE.md 는 프로젝트에서 에이전트가 따라야 할 기준을 적는 문서다.

✔ 파일 위치가 곧 적용 범위이기 때문에 전역, 프로젝트, 디렉토리 단위 규칙을 구분해서 두는 편이 좋다.

✔ 규칙은 CLAUDE.md 와 rules 문서로, 반복 맥락은 memory 로 나누는 것이 가장 안정적이다.

✔ 추상적인 표현보다 짧고 구체적인 지시형 문장이 훨씬 잘 작동한다.

✔ 처음에는 작은 템플릿으로 시작하고, 필요할 때만 규칙을 분리해 확장하면 된다.

✔ 결국 이 구조도 낯선 문제가 아니라, DDD 나 MSA, 객체지향에서 보던 것처럼 책임과 범위를 어디서 끊을지 정하는 문제에 가깝다.