Claude Code가 프로젝트 파일을 볼 수 없는 이유와 해결 방법: 2026년

익숙한 상황입니다. Claude Code에 파일을 수정해 달라고 했는데 해당 파일이 없다는 답이 돌아옵니다. 혹은 의도한 것과 완전히 다른 항목을 아무 말 없이 수정합니다. 폴더를 열어 보면 파일은 있어야 할 바로 그곳에 있습니다. 하지만 Claude는 알아채지 못하는 것 같습니다.

거의 대부분 이유는 하나이며, 고장 난 것은 없습니다. Claude는 컴퓨터 전체의 파일을 볼 수 없습니다. Claude를 실행한 폴더에만 액세스할 수 있습니다. 형제 폴더나 프로젝트 루트 아래에서 시작하면 필요한 파일이 작업 트리 밖에 있을 수 있습니다. 홈 같은 상위 폴더에서 시작하면 범위가 넓어질 뿐 하위 프로젝트에 접근할 수 없게 되지는 않습니다. 왜 이런 방식으로 작동하는지, Claude에 필요한 파일에 액세스할 수 있도록 하는 방법을 단계별로 설명하겠습니다. 2026년 9월 초에 확인한 공식 Claude Code 문서의 명령어와 설정을 직접 인용합니다.

도구 구성에 관한 추가 자료는 Ailoot 문서에서 확인할 수 있습니다.

Claude Code가 일부 프로젝트 파일을 볼 수 없는 이유는 무엇인가요?#

기본적으로 Claude Code는 폴더 하나에서 작동합니다. claude 명령어를 입력하고 세션을 시작한 폴더입니다. 문서에도 이 내용이 명시되어 있습니다.

이 폴더가 작업 디렉터리입니다. 폴더 안에서는 Claude가 추가 질문 없이 어떤 파일이든 읽습니다. 프롬프트 수정, 코드 검색, 특정 파일 읽기 등 모든 작업이 바로 가능합니다. 하지만 이 폴더 밖에 있는 모든 항목은 기본적으로 접근할 수 없습니다. 인접한 폴더, 한 단계 위의 폴더, 다른 드라이브 등 Claude는 허용하기 전까지 살펴보지 않습니다.

작업 폴더 불일치는 중요합니다. 프로젝트가 /Users/you/my-shop인데 형제인 /Users/you/other-project에서 시작했다면 my-shop의 index.html은 작업 트리 밖에 있습니다. /Users/you에서 시작한 경우는 다릅니다. my-shop은 하위이므로 홈에서 시작했다는 이유로 접근 불가가 되지는 않지만 범위가 넓습니다. 폴더 접근 가능과 모든 파일을 이미 읽었다는 것도 다릅니다.

이제 이 문제를 확인하고 해결하는 방법을 살펴보겠습니다. 먼저 Claude를 어느 폴더에서 실행했는지 확인한 다음, 일회성 안내부터 영구 설정까지 다양한 방법으로 필요한 파일에 액세스할 수 있도록 하겠습니다.

Claude Code를 어느 폴더에서 실행했는지 확인하려면 어떻게 하나요?#

무언가를 수정하기 전에 정말 폴더가 문제인지 확인하세요. 확인은 간단합니다. 채팅에서 Claude에게 현재 디렉터리를 표시해 달라고 요청하세요. Claude는 안전한 pwd 명령어를 실행합니다. 이 명령어는 경로만 표시하고 아무것도 건드리지 않습니다.

pwd

응답의 실제 작업 디렉터리와 전체 프로젝트 경로를 비교하세요. /Users/you/other-project는 /Users/you/my-shop의 형제이며 /Users/you는 상위입니다. 형제 폴더에서 시작하면 my-shop은 트리 밖이지만 상위에서 시작하면 포함되면서 특정 프로젝트를 루트로 선택하지 않은 상태입니다.

이 불일치를 해결하는 가장 깔끔한 방법은 프로젝트 폴더에서 Claude를 직접 실행하는 것입니다. 현재 세션을 닫고 터미널에서 올바른 폴더로 이동한 다음 그곳에서 Claude를 실행하세요.

# 예시 경로를 실제 프로젝트 루트로 바꾸세요.
cd /Users/you/my-shop
claude

이제 my-shop이 작업 폴더가 되고 프로젝트 파일을 모두 볼 수 있습니다. VS Code 같은 편집기에서도 같은 규칙이 적용됩니다. 프로젝트가 들어 있는 폴더를 여세요. 한 단계 위의 폴더나 드라이브 전체가 아니라 프로젝트 폴더를 열어야 합니다. 열어 둔 폴더가 Claude가 작업 디렉터리로 간주하는 위치를 결정합니다.

이미 이 세션에서 Claude에게 맥락을 제공했고 이를 잃고 싶지 않은 경우처럼 재실행이 불편하다면, 세션 중에 폴더를 추가하거나 전환할 수 있습니다. 다음 두 섹션에서 방법을 설명합니다.

Claude Code에 인접한 폴더의 파일을 보여주려면 어떻게 하나요?#

프로젝트가 하나의 폴더에만 있지 않은 경우도 있습니다. 코드는 한곳에, 이미지나 텍스트는 인접한 폴더에, 공유 구성 요소는 근처의 다른 위치에 있을 수 있습니다. 폴더마다 Claude를 다시 시작하는 것은 불편합니다. 기본 폴더를 작업 디렉터리로 유지하면서 필요한 폴더에 액세스할 수 있도록 하는 편이 좋습니다.

가장 간단한 방법은 활성 세션에서 다음 명령어를 직접 사용하는 것입니다.

/add-dir ../assets

/add-dir과 폴더 경로를 입력하면 Claude가 기본 폴더의 파일과 동일한 방식으로 해당 폴더의 파일에 즉시 액세스할 수 있습니다. 다시 권한을 묻지 않습니다. 추가된 폴더에도 작업 디렉터리와 같은 규칙이 적용됩니다.

여러 폴더에서 작업할 예정이라면 Claude가 시작할 때부터 액세스를 열어 두세요. 같은 경로를 사용하되 플래그를 추가하면 됩니다.

claude --add-dir ../assets

프로젝트에서 같은 인접 폴더를 항상 사용한다면 매번 수동으로 추가할 필요가 없습니다. settings.json 설정 파일에는 additionalDirectories 키가 있습니다. 여기에 경로를 나열하면 Claude가 시작할 때마다 자동으로 열립니다.

{
  "permissions": {
    "additionalDirectories": ["../assets", "../shared"]
  }
}

Windows에서는 한 가지 유의할 점이 있습니다. \\server\shared 같은 경로로 네트워크 폴더를 추가할 수 없습니다. Claude가 이러한 경로를 허용하지 않습니다. 네트워크 폴더를 드라이브 문자로 별도 드라이브에 마운트한 다음 그 문자를 --add-dir에 전달하세요. 일반 로컬 폴더에는 이런 문제가 없습니다.

인접한 폴더를 추가하는 것만으로 부족하고 다른 폴더로 완전히 이동해야 한다면 어떻게 할까요? 아래에 설명할 별도의 명령어가 있습니다.

세션 중 Claude Code를 다른 폴더로 전환하려면 어떻게 하나요?#

인접한 폴더를 추가하는 것만으로 부족하고 지금까지 쌓은 맥락을 잃지 않은 채 기본 폴더를 바꾸어 다른 프로젝트로 이동해야 할 때가 있습니다. /cd 명령어를 사용하세요.

/cd ../another-project

이후 Claude는 새 폴더를 작업 디렉터리로 간주합니다. 대화 기록은 모두 유지되지만, Claude가 파일을 찾는 기준 위치는 새 위치로 바뀝니다. 새 폴더에 CLAUDE.md 지침 파일이 있으면 Claude가 이 파일도 가져옵니다. 즉, 새 프로젝트의 규칙에 맞춰 작업합니다.

신뢰와 관련해 알아둘 점이 있습니다. 이 폴더에서 작업한 적이 없다면 이동할 때 Claude가 해당 폴더를 신뢰하는지 물어봅니다. 이는 안전장치입니다. 낯선 폴더의 지침 파일에는 무엇이든 들어 있을 수 있으므로 Claude는 먼저 그 폴더가 사용자의 프로젝트인지 확인합니다. 확인한 다음 계속 진행하세요.

두 명령어의 차이는 간단합니다. /add-dir은 기본 폴더를 작업 디렉터리로 유지하면서 인접한 폴더를 추가로 엽니다. 프로젝트의 여러 부분이 여기저기 흩어져 있을 때 유용합니다. /cd는 전체 작업 디렉터리를 새 위치로 옮깁니다. 다른 프로젝트로 전환할 때 유용합니다. /cd 명령어는 버전 2.1.169에서 도입되었으므로 사용할 수 없다면 Claude Code를 업데이트하세요. Claude Code를 업데이트하는 방법에 관한 별도의 가이드도 있습니다.

Claude Code가 파일을 볼 수 있는 것은 토대일 뿐입니다. 안정적인 결과는 파일 액세스만으로 나오지 않습니다. 파일의 내용과 프로젝트 주변의 맥락을 구성하는 방식에서 나옵니다.

Claude Code가 하위 폴더의 파일을 볼 수 없는 이유는 무엇인가요?#

여기서는 서로 다른 두 상황을 혼동하지 않는 것이 중요합니다. 프로젝트 바깥의 인접한 폴더는 추가하기 전까지 완전히 접근할 수 없습니다. 프로젝트 안의 하위 폴더는 다릅니다. Claude가 액세스할 수는 있지만 처음부터 그 내용을 기억하고 있지는 않습니다.

작동 방식은 이렇습니다. Claude가 시작하면 프로젝트의 최상위 수준에 있는 항목을 불러옵니다. 하위 폴더의 파일은 그곳으로 이동해 무언가를 읽을 때 필요에 따라 불러옵니다. 문서에서는 지침 파일에 관한 이 동작을 설명하고 있으며, 일반적인 컨텍스트에도 같은 논리가 적용됩니다.

쉽게 말해, 깊이 중첩된 하위 폴더의 파일이 사라진 것이 아니며 완전히 액세스할 수 있습니다. Claude가 그곳을 살펴보지 않아 아직 기억하지 못한 것뿐입니다. 파일이 실제로 있고 액세스할 수 있는데도 Claude가 파일을 “볼 수 없는” 것처럼 느껴지는 이유가 여기에 있습니다.

한 줄로 해결할 수 있습니다. 예를 들어 src/components/header.jsx처럼 파일 경로를 Claude에게 직접 알려주거나, 먼저 파일을 읽어 달라고 요청하세요. Claude가 파일을 살펴보는 즉시 해당 파일이 컨텍스트에 들어오므로 평소처럼 작업할 수 있습니다. 설정을 변경할 필요는 없습니다.

@ 메뉴에서 파일이 사라지는 이유와 .gitignore의 관계는 무엇인가요?#

Claude가 파일을 “잃어버렸다”고 생각하게 되는 또 다른 흔한 이유는 파일 선택기입니다. @를 입력하면 전체 경로를 입력하지 않고도 파일을 편리하게 선택할 수 있도록 목록이 나타납니다. 하지만 모든 파일이 목록에 표시되지는 않습니다.

기본적으로 @ 메뉴는 .gitignore에 나열된 파일을 숨깁니다. 이 파일은 공유 저장소에 추가하지 말아야 할 항목을 지정합니다. 서비스 폴더, 비밀번호와 환경 설정이 들어 있는 파일, 완료된 빌드 출력물 등이 여기에 해당합니다. 보통 이런 파일을 직접 다룰 필요가 없으므로 목록만 복잡하게 만들게 된다는 점에서 이는 합리적입니다. 하지만 가끔 이런 파일이 필요해도 메뉴에 나타나지 않을 수 있습니다.

respectGitignore 설정이 이를 제어합니다. 기본적으로 켜져 있으므로 .gitignore에 포함된 파일은 메뉴에 나타나지 않습니다. 파일을 보려면 설정을 false로 바꾸세요.

{
  "respectGitignore": false
}

파일을 수정하지 않고 Claude Code 안에서 /config 명령어를 사용해도 같은 설정을 변경할 수 있습니다. 해당 토글의 이름은 “파일 선택기에서 .gitignore 존중”입니다. 선택을 해제하면 숨겨진 파일이 메뉴에 다시 표시됩니다.

한 가지 중요한 유의점이 있습니다. respectGitignore는 @ 메뉴에만 적용되며 파일 액세스와는 관계가 없습니다. 파일이 목록에서 숨겨져 있어도 경로를 직접 입력하면 Claude가 읽을 수 있습니다. 메뉴는 편의 기능일 뿐 액세스 경계를 설정하지 않습니다.

Claude Code가 특정 파일을 읽지 못하면 어떻게 해야 하나요?#

폴더가 분명히 올바르고 액세스도 허용되어 있는데 Claude가 특정 파일 하나를 계속 읽지 않는다면, 파일에 제한이 걸렸을 가능성이 큽니다. 제한은 settings.json 설정 파일에 있으며 두 가지 유형이 있습니다.

첫 번째는 특정 파일에 대한 제한입니다. 설정에서 이를 deny 규칙이라고 하며, 가장 흔히 키와 비밀번호가 저장된 .env 파일에 적용됩니다.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

이런 규칙은 지정한 파일을 Claude가 읽지 못하도록 차단하며, 이는 의도된 동작입니다. 키와 비밀번호가 모델과의 대화에 들어가서는 안 되므로 .env는 기본적으로 잠겨 있습니다. Claude가 .env나 비밀 정보가 들어 있는 유사한 파일을 읽지 않는다면 의도된 동작입니다. 강력한 이유 없이 이 제한을 제거해서는 안 됩니다.

두 번째 유형은 작업 폴더 밖의 모든 항목에 대한 일반 제한입니다. blockReadsOutsideWorkingDirectories 설정이 이를 제어합니다. 이 설정을 활성화하면 직접 열려고 해도 Claude는 작업 디렉터리 밖의 파일을 모두 읽지 않습니다. 이 설정이 true이고 외부 파일이 필요하다면 /add-dir을 사용해 해당 폴더를 추가하거나 제한을 해제하세요.

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": false
  }
}

이 설정은 버전 2.1.257에서 도입되었습니다. 다른 방법을 모두 시도했는데도 파일에 계속 접근할 수 없다면 deny와 blockReadsOutsideWorkingDirectories를 모두 확인해 보세요.

Claude Code가 파일을 볼 수 없을 때 어디서부터 시작해야 하나요?#

다음은 위에서부터 차례대로 따라 할 수 있는 간단한 계획입니다.

1. 작업 폴더를 확인합니다. Claude에게 pwd로 현재 디렉터리를 표시해 달라고 한 다음 프로젝트 위치와 비교합니다.
2. 폴더가 다르면 올바른 위치에서 Claude를 다시 실행하거나(cd project를 입력한 다음 claude 실행), /cd 명령어로 해당 위치로 이동합니다.
3. 인접한 폴더의 파일이 필요한가요? Claude를 시작할 때 /add-dir 또는 --add-dir 플래그를 사용해 추가합니다.
4. 하위 폴더의 파일이 컨텍스트에 없나요? Claude에게 해당 파일의 경로를 직접 알려주거나 파일을 읽어 달라고 요청합니다.
5. @ 메뉴에서 파일이 보이지 않나요? .gitignore 때문입니다. respectGitignore를 false로 설정하거나 /config에서 확인란을 해제합니다.
6. 특정 파일 하나가 잠겨 있나요? settings.json의 deny 및 blockReadsOutsideWorkingDirectories 규칙을 확인합니다.

열 번 중 아홉 번은 첫 단계에서 모든 문제가 해결됩니다. Claude를 잘못된 폴더에서 실행한 것입니다. 파일 액세스는 토대지만 프로젝트를 대신 만들어 주지는 않습니다. Claude가 전체 프로젝트를 기억하고 맥락을 놓치지 않도록 컨텍스트를 구성하는 방법은 Claude Code의 Second Brain 가이드에서 자세히 설명했습니다.

도구 사용에 관한 추가 자료는 Ailoot 문서에서 확인하세요.