터미널 폴더 경로와 .claude

Claude Code 설정 글을 읽다 보면 이런 문장을 만납니다. “~/.claude/CLAUDE.md에 규칙을 적으세요.” 그런데 그 폴더가 내 맥북 화면 어디에 있는지는 아무도 알려주지 않습니다. 파인더를 아무리 뒤져도 안 나옵니다.

결론부터 말씀드립니다. 기호 세 개만 알면 경로는 전부 읽힙니다.

기호	뜻
`~`	내 홈 폴더 (물결표. 맥은 `/Users/이름`, 윈도우는 `C:\Users\이름`)
`.`	지금 터미널이 서 있는 폴더
이름이 `.`으로 시작	숨김 폴더. 파인더·탐색기에 기본으로 안 보입니다

그래서 ~/.claude/는 “내 홈 폴더 안에 있는, 이름이 점으로 시작해서 평소엔 눈에 안 보이는 claude 폴더”입니다. 그게 전부입니다. 파인더에서 못 찾으신 건 못 찾은 게 아니라 가려져 있어서 안 보인 겁니다.

2026년 9월 기준입니다. 경로와 동작은 Claude Code 공식 문서를 기준으로 삼았고, 화면에 찍힌 출력은 전부 필자의 맥(Claude Code v2.1.278)에서 직접 실행한 결과입니다. 설치가 아직이라면 설치편을 먼저 보세요.

폴더를 알아야 하는 진짜 이유

외워두면 좋은 상식이라서 드리는 말씀이 아닙니다. 이걸 모르면 Claude Code가 내 파일을 아예 못 봅니다. 공식 권한 문서에 이렇게 적혀 있습니다.

“By default, Claude has access to files in the directory where you launched it. That directory is the session’s primary working directory.” (기본적으로 Claude는 여러분이 실행한 그 폴더 안의 파일에 접근합니다. 그 폴더가 세션의 기본 작업 디렉터리입니다.)

즉 Claude Code는 “내 컴퓨터 전체”를 보는 프로그램이 아닙니다. 터미널을 연 그 폴더 하나를 봅니다. 바탕화면 폴더에서 켜놓고 다운로드 폴더의 파일을 고쳐달라고 하면 못 합니다. 비개발자분들이 “Claude가 파일을 못 찾는다”고 하시는 경우는 대부분 실력 문제가 아니라 위치 문제입니다.

홈 폴더는 화면 어디에 있나

~가 가리키는 그 폴더를 눈으로 먼저 보는 게 빠릅니다.

맥: 파인더를 열고 ⌘ + Shift + H를 누릅니다. 바로 열리는 그 폴더가 홈 폴더입니다. 창 제목에 집 아이콘과 사용자 이름이 뜹니다. 메뉴의 이동 → 홈도 같습니다. (사이드바에 집 아이콘이 없는 경우가 많은데, 정상입니다. 파인더 설정 → 사이드바에서 켤 수 있습니다.)

윈도우: 탐색기 주소창에 %USERPROFILE%을 입력하고 엔터를 칩니다. C:\Users\내이름으로 이동합니다.

여기가 ~입니다. 다운로드, 바탕화면, 문서 폴더가 전부 이 안에 들어 있습니다.

안 보이는 폴더를 보이게 하는 법

이 단락이 이 글의 핵심입니다.

방금 연 홈 폴더에서 ⌘ + Shift + . (커맨드 + 시프트 + 마침표)를 눌러보세요. 반투명하게 흐린 폴더들이 우수수 나타납니다. 그중에 .claude가 있습니다. 같은 키를 한 번 더 누르면 다시 사라집니다.

숫자로 보면 차이가 확 납니다. 필자의 맥에서 홈 폴더를 세어보면 이렇습니다.

ls -1 ~ | wc -l      # 31   ← 평소 파인더에 보이는 것
ls -A ~ | grep '^\.' | wc -l   # 80   ← 점으로 시작해서 숨겨진 것

평소 보이는 31개 뒤에 80개가 더 있습니다. 설정 파일들이라 실수로 지우면 곤란하니 운영체제가 가려둔 것뿐입니다. .claude도 그중 하나입니다.

윈도우는 사정이 조금 다릅니다. 이름의 점이 아니라 파일 속성으로 숨김을 판단하기 때문에 .claude 폴더가 그냥 보이는 경우가 많습니다. 안 보인다면 탐색기 상단의 보기 → 표시 → 숨긴 항목을 켜세요.

폴더를 여는 것만 목적이라면 더 빠른 길도 있습니다. 맥 파인더에서 ⌘ + Shift + G를 누르고 ~/.claude를 그대로 붙여넣으면 숨김 표시를 켜지 않아도 바로 그 폴더가 열립니다. 윈도우는 탐색기 주소창에 %USERPROFILE%\.claude를 넣으면 됩니다.

터미널 명령어는 세 개면 충분합니다

터미널은 명령어를 글자로 입력하는 검은 창입니다. 맥은 ‘터미널’, 윈도우는 ’PowerShell’입니다. 여기서 폴더를 다루는 데 필요한 명령어는 사실상 세 개입니다.

명령어	하는 일
`pwd`	나 지금 어느 폴더에 있지?
`ls`	이 폴더 안에 뭐가 있지?
`cd 경로`	저 폴더로 이동

세 개 모두 맥 터미널과 윈도우 PowerShell에서 똑같이 동작합니다. PowerShell이 pwd·ls·cd를 별칭으로 받아주기 때문에 운영체제별로 따로 외우실 필요가 없습니다. (옛날 방식인 CMD 창에서는 ls 대신 dir을 씁니다. 프롬프트가 PS C:\로 시작하면 PowerShell, PS 없이 C:\면 CMD입니다.)

숨김 항목까지 보려면 ls 뒤에 한 글자를 붙입니다. 맥은 ls -a, PowerShell은 ls -Force입니다. 이 블로그 프로젝트 폴더에서 실제로 실행한 결과입니다.

$ ls                                            # 일부 생략
astro.config.mjs  CLAUDE.md  package.json  public  README.md  src

$ ls -a                                          # 일부 생략
.  ..  .astro  .claude  .DS_Store  .env  .git  .gitignore
astro.config.mjs  CLAUDE.md  package.json  public  README.md  src

맨 앞의 .과 ..은 파일이 아닙니다. 각각 지금 폴더와 한 단계 위 폴더를 가리키는 표시라 어느 폴더에서 쳐도 따라 나옵니다. 그 뒤로 ls만 쳤을 때는 없던 여섯 개가 나타납니다. .claude가 바로 이 프로젝트의 Claude Code 설정 폴더입니다.

cd는 경로를 직접 타이핑하실 필요가 없습니다. 터미널에 cd 까지만 치고 (뒤에 띄어쓰기 한 칸) 원하는 폴더를 파인더에서 터미널 창으로 끌어다 놓으면 경로가 알아서 입력됩니다. 엔터만 치면 이동합니다. 비개발자분들께는 이 방법이 가장 확실합니다.

경로 읽기 연습

공식 문서와 블로그에 자주 나오는 경로 세 개를 실제 위치로 바꿔보겠습니다. 사용자 이름이 kim이고 바탕화면의 my-app 폴더에서 작업 중인 상황입니다.

문서에 쓰인 경로	실제 위치	무엇
`~/.claude/CLAUDE.md`	`/Users/kim/.claude/CLAUDE.md`	사용자 지침. 내 모든 프로젝트에 적용
`./CLAUDE.md`	`/Users/kim/Desktop/my-app/CLAUDE.md`	프로젝트 지침. 이 프로젝트에만 적용
`.claude/skills/my-skill/SKILL.md`	`/Users/kim/Desktop/my-app/.claude/skills/my-skill/SKILL.md`	이 프로젝트 전용 스킬

규칙은 하나입니다. ~로 시작하면 홈 폴더 기준, 아니면 지금 있는 폴더 기준. 두 번째와 세 번째 줄이 바탕화면으로 바뀐 이유는 그때 터미널이 거기 있었기 때문입니다. 다른 폴더에서 켰다면 실제 위치도 따라 바뀝니다.

홈의 `.claude`와 프로젝트의 `.claude`는 다릅니다

이름이 같아서 가장 많이 헷갈리는 지점입니다. 공식 문서는 .claude 디렉터리가 두 군데에 존재한다고 명시합니다.

~/.claude/ — 홈 폴더 안. 내가 쓰는 모든 프로젝트에 공통으로 적용됩니다. 여기 있는 CLAUDE.md는 어느 폴더에서 Claude Code를 켜든 읽힙니다.
프로젝트폴더/.claude/ — 작업 폴더 안. 그 프로젝트에서만 적용됩니다. 팀과 함께 쓰는 규칙이 여기 들어갑니다.

둘은 경쟁 관계가 아닙니다. 공식 문서 표현대로 둘 다 “in context together”, 즉 함께 컨텍스트에 들어갑니다. 참고로 필자의 ~/.claude/ 안에는 항목이 37개 있는데, 처음에는 CLAUDE.md와 settings.json 두 개만 보셔도 충분합니다.

10분 실습: 프로젝트 폴더 하나 만들기

읽기만 하면 남지 않습니다. 딱 10분이면 끝나는 순서입니다.

파인더에서 바탕화면에 새 폴더를 만들고 이름을 my-app으로 바꿉니다. (1분)
터미널을 엽니다. 맥은 ⌘ + 스페이스 → 터미널, 윈도우는 Win + X → Windows PowerShell. (1분)
pwd를 칩니다. 지금 위치가 찍힙니다. 아마 홈 폴더일 겁니다. (1분)
cd 까지 치고 my-app 폴더를 터미널 창으로 끌어다 놓은 뒤 엔터. (2분)
pwd를 다시 칩니다. 경로 끝이 my-app으로 바뀌었으면 성공입니다. (1분)
claude를 실행합니다. 프롬프트 위에 버전·모델과 함께 작업 디렉터리가 표시됩니다. 그 줄이 방금 만든 my-app을 가리키는지 확인하세요. (2분)
Claude에게 이렇게 말해봅니다. “지금 이 폴더에 메모용 텍스트 파일 하나 만들어줘.” 파인더의 my-app 안에 파일이 생기면, 경로 개념은 끝난 겁니다. (2분)

6번의 작업 디렉터리 표시는 사실상 pwd를 대신합니다. 매번 확인하는 습관만 들여도 아래에 나오는 사고의 절반이 사라집니다.

여기서 막힙니다

“파일을 못 찾겠다”는 답이 옵니다. 열에 아홉은 엉뚱한 폴더에서 Claude Code를 켠 경우입니다. 프롬프트 위 작업 디렉터리 표시를 보세요. 다르면 /cd 경로로 세션을 통째로 옮기거나 /add-dir 경로로 폴더를 하나 더 붙일 수 있습니다. 터미널을 껐다 켜지 않아도 됩니다.

홈 폴더에서 켜면 매번 같은 걸 물어봅니다. 홈 폴더(~)에서 그냥 claude를 켜는 분이 많은데, 공식 문서는 이 경우 신뢰(trust) 승인이 그 세션 동안만 유지되고 디스크에 저장되지 않는다고 명시합니다. 실행할 때마다 같은 확인 창이 다시 뜹니다. 작업할 폴더를 따로 만들고 거기서 켜는 게 맞습니다.

command not found: claude가 뜹니다. 이건 폴더 문제가 아니라 설치 경로(PATH) 문제입니다. 어느 폴더에서 쳐도 똑같이 납니다. 설치편의 해결 순서를 따르세요.

cd를 쳤는데 no such file or directory가 납니다. 경로에 한글이나 띄어쓰기가 들어간 경우가 많습니다. 직접 타이핑하지 말고 4번처럼 끌어다 놓으세요. 따옴표까지 알아서 붙습니다.

이걸 다 외우실 필요는 없습니다

정직하게 말씀드리면, 위 내용을 통째로 암기하는 건 시간 낭비입니다. 실제로 필요한 순간은 정해져 있습니다. 문서에서 처음 보는 경로를 만났을 때, 그리고 Claude가 파일을 못 찾을 때. 그 두 번뿐입니다.

그래서 이 글은 읽고 넘기는 글이 아니라 막힐 때 다시 여는 글로 만들어 두시는 편이 낫습니다. 북마크해 두시고, ~가 뭐였는지 헷갈릴 때 경로 읽기 연습 표만 다시 보셔도 충분합니다.

세션 안에서 쓰는 /cd, /add-dir 같은 명령어가 궁금하시다면 슬래시 명령어 정리에 전체 목록이 있습니다.