클로드 코드(Claude Code)를 설치하고 나면, 바로 기능을 많이 쓰기보다 어떤 설정을 먼저 잡아야 편한지를 아는 쪽이 훨씬 중요합니다. 처음에는 대화는 되는데 권한이 자꾸 막히거나, 프로젝트 바깥 폴더를 못 읽거나, 팀과 공유할 설정과 내 개인 설정이 섞여서 헷갈리는 경우가 많습니다.
이 글은 그런 초반 혼란을 줄이기 위한 클로드 코드 세팅 방법 정리입니다. 터미널에서 바로 바꿔볼 수 있는 명령부터, 설정 파일을 어디에 두는지, 어떤 값은 팀과 공유하고 어떤 값은 로컬에만 두는지까지 차근차근 정리했습니다.
Table of Contents
1. 가장 먼저 /config부터 열어보기
처음에는 JSON 파일을 바로 여는 것보다, 클로드 코드 안에서 /config를 먼저 실행해보는 편이 편합니다. 현재 환경에서 바꿀 수 있는 설정과 어디를 손보면 되는지 감을 잡기 좋기 때문입니다.
claude
/config설정을 아직 외우지 못한 상태라면, 이 메뉴를 통해 전체 구조를 먼저 훑는 것이 가장 덜 부담스럽습니다. 특히 처음에는 무엇을 세팅해야 할지보다 어디에서 세팅하는지를 먼저 이해하는 편이 낫습니다.
2. 전역 설정과 프로젝트 설정을 구분하기
클로드 코드는 설정을 한 곳에만 두지 않습니다. 그래서 설정이 왜 적용되지 않는지 헷갈릴 때가 많습니다. 초반에는 아래 세 가지만 구분하면 됩니다.
~/.claude/settings.json: 내 컴퓨터에서 기본으로 쓸 전역 설정.claude/settings.json: 프로젝트 안에서 팀과 공유할 설정.claude/settings.local.json: 내 로컬에서만 유지할 개인 설정
예를 들어, 모든 프로젝트에서 공통으로 쓰고 싶은 기본 동작은 전역 설정에 두고, 특정 저장소에서만 허용할 폴더 접근이나 권한 규칙은 프로젝트 설정에 두는 식입니다. 반대로 개인 실험용 값은 settings.local.json 쪽이 더 안전합니다.
3. permissions 규칙을 먼저 정리하기
처음 클로드 코드를 쓸 때 가장 자주 답답한 부분은 권한입니다. 어떤 작업은 바로 실행되고, 어떤 작업은 계속 확인을 물어보거나 막히는 일이 생깁니다. 이때는 permissions 규칙을 먼저 보는 편이 좋습니다.
대화형 세션 안에서는 /permissions로 접근할 수 있고, 설정 파일에서는 권한 관련 항목을 직접 관리할 수 있습니다. 초반에는 무조건 넓게 풀어두기보다, 자주 쓰는 작업만 차근차근 허용하는 쪽이 안전합니다.
예를 들면 이런 식으로 생각하면 됩니다.
- 파일 읽기와 기본 분석은 비교적 넓게 허용
- 실행 명령이나 파일 변경은 필요한 범위만 허용
- 위험한 작업은 처음엔 확인을 거치게 두기
이렇게 잡아두면 너무 답답하지도 않고, 너무 무방비 상태도 피할 수 있습니다.
4. 프로젝트 바깥 폴더를 읽어야 한다면 /add-dir 사용
여러 폴더를 같이 보는 작업을 하다 보면, 현재 프로젝트 밖의 디렉터리를 읽지 못해 막히는 경우가 있습니다. 이럴 때는 /add-dir로 추가 디렉터리를 연결할 수 있습니다.
/add-dir ../shared-lib예를 들어 메인 프로젝트와 공용 라이브러리를 같이 봐야 하거나, 문서 폴더와 코드 폴더를 함께 읽게 하고 싶을 때 유용합니다. 이 기능을 모르고 있으면 “왜 이 폴더는 못 읽지?”라는 느낌을 자주 받게 됩니다.
5. 팀과 공유할 설정은 작게, 개인 설정은 로컬에 두기
팀 프로젝트에서는 설정을 전부 공유 파일에 몰아넣기보다, 정말 팀 전체에 필요한 것만 프로젝트 설정에 넣는 편이 좋습니다. 예를 들면 프로젝트 공통 권한 규칙이나 작업 디렉터리 범위 정도입니다.
반면 알림 방식, 개인 취향에 가까운 값, 실험 중인 규칙은 로컬 설정으로 분리하는 편이 충돌이 적습니다. 이 기준이 없으면 나중에 저장소에 불필요한 설정 변경이 계속 쌓이게 됩니다.
6. CLAUDE.md와 설정 파일은 역할이 다릅니다
처음에는 CLAUDE.md와 설정 파일을 같은 것으로 느끼기 쉽지만, 역할이 다릅니다. 설정 파일은 권한과 동작 범위를 다루고, CLAUDE.md는 이 프로젝트에서 어떤 식으로 일해야 하는지에 대한 작업 규칙에 가깝습니다.
예를 들어 아래 같은 내용은 CLAUDE.md 쪽이 더 잘 맞습니다.
- 테스트는 어떤 순서로 돌릴지
- 코드 스타일은 무엇을 따를지
- 커밋 전에 꼭 확인할 항목은 무엇인지
반대로 권한, 폴더 접근, 로컬 오버라이드 같은 문제는 설정 파일에서 다루는 편이 맞습니다.
7. 처음 적용해볼 만한 세팅 순서
처음에는 이것저것 한꺼번에 건드리기보다, 아래 순서로 세팅하면 무난합니다.
/config로 현재 구조 확인- 전역 설정 파일과 프로젝트 설정 파일 위치 확인
/permissions로 자주 쓰는 작업 범위 점검- 필요하면
/add-dir로 추가 폴더 연결 - 프로젝트 규칙은
CLAUDE.md에 따로 정리
이 순서로만 잡아도 나중에 설정이 꼬였을 때 어디부터 봐야 할지 훨씬 명확해집니다.
자주 헷갈리는 부분
설정을 바꿨는데 적용이 안 되는 것 같아요
전역 설정과 프로젝트 설정, 로컬 설정이 겹치면 어느 파일이 우선하고 있는지 다시 확인해야 합니다. 처음에는 파일을 너무 많이 동시에 건드리지 않는 편이 낫습니다.
팀 설정과 내 설정을 같이 저장소에 올려도 되나요?
권장하지 않습니다. 팀 전체에 필요한 값만 프로젝트 설정에 두고, 개인 실험이나 취향에 가까운 값은 로컬 설정으로 두는 편이 깔끔합니다.
처음에는 어디까지 세팅하는 게 적당할까요?
정말 필요한 것만 먼저 잡는 편이 좋습니다. 권한 규칙, 디렉터리 범위, 작업 규칙 정도만 정리해도 초반 사용감은 꽤 좋아집니다.
정리
클로드 코드 세팅은 기능을 많이 켜는 과정이 아니라, 어디까지 읽고, 무엇을 허용하고, 팀과 개인 설정을 어떻게 나눌지를 정리하는 과정에 가깝습니다.
처음에는 /config, 설정 파일 위치, /permissions, /add-dir 이 네 가지만 익혀도 사용감이 크게 달라집니다. 설치만 끝낸 상태에서 한 번 더 정리해두면 이후 작업이 훨씬 안정적입니다.
함께 보면 좋은 글:
참고한 공식 문서
- Claude Code settings
- Claude Code permissions
- Claude Code common workflows