폴더에 둔다고 읽히지 않습니다
.claude/는 Claude Code의 설정이 모이는 곳입니다. 그런데 여기 있는 것이 전부 자동으로 읽히지는 않습니다. 정해진 자리에 있는 것만 읽히고, 나머지는 가리켜 줘야 읽힙니다.
인터넷에 도는 .claude 폴더 구조도는 이 둘을 섞어 그려 놓는 경우가 많습니다. 그래서 memory/에 열심히 적어 두고 왜 반영이 안 되지 하게 됩니다.
Claude가 알아서 읽는 것
아래 경로는 따로 말하지 않아도 Claude Code가 찾아 읽습니다.
| 경로 | 담는 것 | 언제 읽히나 |
|---|---|---|
| CLAUDE.md | 팀 공통 규칙 · 사실 | 세션 시작 시 전체 |
| CLAUDE.local.md | 개인 메모 · 취향 | CLAUDE.md 뒤에 이어서 |
| .claude/rules/*.md | 주제별 규약 | 항상. paths가 있으면 해당 파일을 다룰 때만 |
| .claude/skills/<이름>/SKILL.md | 절차 | 이름·설명은 항상, 본문은 호출될 때 |
| .claude/agents/*.md | 역할별 서브에이전트 | 위임 대상으로 등록 |
| .claude/commands/*.md | 슬래시 명령 | /이름으로 호출 |
| .claude/settings.json | 권한 · 환경변수 · 훅 | 세션 시작 시 |
| .claude/settings.local.json | 개인 설정 | 세션 시작 시 |
정리하면 이런 모양입니다.
your-project/
├── CLAUDE.md 팀 공통 — Git 관리
├── CLAUDE.local.md 개인 — .gitignore
└── .claude/
├── settings.json 권한 · 환경변수 · 훅 — Git 관리
├── settings.local.json 개인 — .gitignore
├── rules/ 주제별 규약 (paths로 범위 지정)
├── skills/<이름>/SKILL.md 절차 (호출될 때 본문 로드)
├── agents/<이름>.md 역할별 서브에이전트
└── commands/<이름>.md /이름 슬래시 명령우리가 만든 폴더
memory/ · templates/ 같은 폴더는 Claude Code의 규격이 아닙니다. 만들어 두는 것 자체는 좋지만, 그 자리에 있다는 이유만으로는 읽히지 않습니다.
| 흔히 만드는 것 | 담는 것 | 읽히게 하려면 |
|---|---|---|
| .claude/memory/ | 의사결정 기록 · 알려진 이슈 | CLAUDE.md에서 지목하거나 rules/로 옮기기 |
| .claude/templates/ | 이슈 · PR · 설계서 양식 | "PR 만들 때 이 파일을 따르라"고 절차에 적기 |
| docs/ | 설계 문서 · 사내 규정 | 필요할 때 경로를 알려주기 |
지목하는 방법 — CLAUDE.md 한 줄
가장 간단한 방법은 CLAUDE.md에 어디에 무엇이 있는지만 적어 두는 것입니다.
## 참고 자료 위치 - 과거 의사결정과 그 이유: `.claude/memory/decisions.md` - 알려진 문제와 우회책: `.claude/memory/known-issues.md` - PR 본문 양식: `.claude/templates/pr-template.md` 위 파일이 필요한 작업이면 먼저 읽고 시작한다.
떠도는 구조도에서 자주 틀리는 것
① /project:review — 옛 문법입니다
지금은 파일 이름이 그대로 명령이 됩니다. 접두어가 붙지 않습니다.
| 파일 | 호출 |
|---|---|
| .claude/commands/review.md | /review |
| .claude/skills/review/SKILL.md | /review |
② .claude/memory/는 자동 메모리가 아닙니다
Claude Code가 스스로 쓰고 읽는 자동 메모리는 프로젝트 폴더가 아니라 내 PC의 다른 곳에 있습니다.
~/.claude/projects/<프로젝트>/memory/MEMORY.md ← 자동 메모리 (머신 로컬) .claude/memory/decisions.md ← 우리가 만든 일반 파일
③ 스킬은 "이벤트로 자동 실행"되지 않습니다
스킬은 상황에 맞으면 Claude가 판단해서 부르거나 내가 /이름으로 부릅니다. 정해진 시점에 반드시 실행되는 것은 훅입니다.
| 부르는 주체 | 확실성 | |
|---|---|---|
| 스킬 | Claude의 판단 · 사람 | 맥락 — 확률적 |
| 훅 | 정해진 이벤트 | 코드 — 100% 확정 |
무엇을 커밋하나
기준은 하나입니다 — 팀이 공유해야 하면 커밋, 나만의 것이면 제외.
| ✓ Git으로 공유 | ✗ .gitignore |
|---|---|
| CLAUDE.md | CLAUDE.local.md |
| .claude/settings.json | .claude/settings.local.json |
| .claude/rules/ · skills/ · agents/ · commands/ | .claude/worktrees/ |
# .gitignore CLAUDE.local.md .claude/settings.local.json .claude/worktrees/
우리 프로젝트에 적용하기
처음부터 폴더를 다 만들지 마세요. 필요해질 때 하나씩 늘리는 편이 관리됩니다.
CLAUDE.md 한 장
빌드·테스트 명령, 팀 컨벤션, 금지사항(+대안). 200줄 이내 (B-3)
길어지면 rules/로 분리
주제별로 쪼개고, 특정 폴더에만 필요한 규칙은 paths로 좁힙니다
반복 절차가 생기면 skills/
매번 같은 순서로 시키는 일을 절차서로 (B-6)
탐색·리뷰가 잦으면 agents/
별도 문맥에서 돌 역할을 파일로 (B-4)
반드시 지킬 것은 훅
settings.json에 등록해 코드로 막습니다 (B-7)
지금 무엇이 읽히고 있는지 확인
/context
Memory files 항목에 내가 만든 파일이 보이면 제대로 로드된 것입니다. 안 보이면 자리가 틀렸거나 지목이 빠진 것입니다.
정리를 Claude에게 맡기기
우리 저장소의 .claude 폴더와 CLAUDE.md를 점검해줘. 1. 자동으로 로드되는 자리에 있는 것과, 그렇지 않은 파일을 구분해서 목록으로 2. 자동 로드가 아닌데 CLAUDE.md에서 지목도 안 된 파일이 있으면 알려줘 3. CLAUDE.md가 200줄을 넘으면 rules/로 나눌 후보를 제안해줘 판단 근거도 함께 적어줘.
- 자동으로 읽히는 자리와 우리 관례를 구분할 수 있다
- /context로 실제 로드된 파일을 확인했다
- 관례 폴더를 CLAUDE.md에서 지목하거나 스킬로 옮겼다
- *.local.*을 .gitignore에 넣었다
- 스킬과 훅의 확실성 차이를 설명할 수 있다