클로드 코드(Claude Code)를 쓰다 보면 “왜 이 폴더는 못 읽지?”라는 상황을 자주 만납니다. 이때 권한 문제로만 생각하기 쉬운데, 실제로는 작업 범위 문제인 경우가 많습니다.
이 글은 그래서 클로드 코드 add-dir 사용법을 중심으로, 언제 필요한지, 권한 문제와 어떻게 다른지, 실제로 어떤 식으로 써야 덜 헷갈리는지까지 정리했습니다.
Table of Contents
add-dir은 언제 필요한가
보통 현재 작업 폴더 밖의 디렉터리를 같이 봐야 할 때 필요합니다.
- 메인 프로젝트와 shared-lib를 같이 볼 때
- 문서 폴더와 코드 폴더를 같이 읽혀야 할 때
- 서브 프로젝트를 옆에 두고 함께 분석할 때
이럴 때 권한을 전부 넓게 푸는 것보다, 읽을 디렉터리만 정확히 추가하는 편이 훨씬 안전합니다.
가장 기본적인 사용 예시
/add-dir ../shared-lib이렇게 현재 프로젝트 바깥의 공용 라이브러리를 추가할 수 있습니다. 핵심은 “무엇을 허용할지”보다 “어디를 작업 범위에 포함할지”를 분리해서 생각하는 것입니다.
권한 문제와는 어떻게 다를까
권한은 /permissions 쪽에서 무엇을 할 수 있는지를 정하는 흐름이고, /add-dir는 어디를 볼 수 있는지를 정하는 흐름에 가깝습니다.
즉 이런 식으로 나누면 쉽습니다.
/permissions: 읽기, 편집, 실행 같은 행동 범위/add-dir: 작업 대상이 되는 디렉터리 범위
이 둘을 섞어서 보면 “왜 설정을 바꿨는데도 못 읽지?” 같은 혼란이 생기기 쉽습니다.
실무적으로는 이렇게 쓰는 편이 좋습니다
- 먼저 현재 작업 루트를 명확히 잡기
- 부가적으로 꼭 필요한 폴더만
/add-dir로 추가 - 권한은 별도로
/permissions에서 관리
이렇게 나누면 나중에 문제가 생겨도 범위와 권한을 따로 점검할 수 있습니다.
자주 헷갈리는 부분
add-dir을 했는데도 안 읽히는 것 같아요
현재 세션, 권한 규칙, 실제 경로 지정이 맞는지 다시 확인해야 합니다. 경로가 예상과 다르면 추가해도 원하는 폴더가 아닐 수 있습니다.
그럼 add-dir만 하면 권한도 해결되나요?
아닙니다. add-dir은 범위 추가이고, 허용 동작은 별도로 permissions 규칙을 봐야 합니다.
함께 보면 좋은 글
정리
클로드 코드 add-dir 사용법의 핵심은 복잡하지 않습니다. 권한을 무작정 넓히기보다, 필요한 디렉터리만 작업 범위에 추가하는 편이 훨씬 안전하고 추적하기 쉽습니다.
프로젝트 바깥 폴더를 봐야 할 때는 먼저 /add-dir를 떠올리는 편이 가장 현실적입니다.