AI-06 · 설정 폴더와 전역·지역 설정
같은 설명을 대화마다 반복하는 대신, 지킬 규칙과 허용할 작업을 파일로 적어 두는 곳이 .claude 폴더입니다. 어떤 파일에 적는지가 곧 누구에게 어디까지 적용되는지를 정하므로 내용을 쓰기 전에 위치를 먼저 정합니다.
이 자료는 Claude Code를 기준으로 설명합니다. 지시의 종류와 우선순위, AGENTS.md를 사용하는 다른 도구와의 차이는 AI-02 · 컨텍스트 이해와 구성에서 다룹니다.
적용 범위를 먼저 구분합니다
| 구분 | 위치 | 적용 범위 | 공유 방식 |
|---|---|---|---|
| 조직 관리 설정 | 회사가 배포하는 managed-settings.json | 배포된 모든 PC의 모든 작업 | 개인이 바꿀 수 없음 |
| 프로젝트 개인 설정 | .claude/settings.local.json | 이 프로젝트, 내 PC에서만 | 저장소에 올리지 않음 |
| 프로젝트 공유 설정 | .claude/settings.json, CLAUDE.md, .mcp.json | 이 프로젝트, 모든 팀원 | 저장소에 함께 저장 |
| 전역 개인 설정 | ~/.claude/settings.json, ~/.claude/CLAUDE.md | 내 PC의 모든 프로젝트 | 저장소에 올리지 않음 |
같은 항목을 여러 곳에 적으면 표의 위쪽 설정이 우선 적용됩니다. 가장 넓게 적용되는 전역 설정의 우선순위가 가장 낮습니다. 팀이 정한 모델은 내 전역 설정보다 먼저 적용되고, 내가 settings.local.json에 적은 값은 팀 설정보다 먼저 적용되지만 다른 팀원에게는 영향을 주지 않습니다.
핵심 기술 요소
.claude/settings.local.json은 도구가 직접 만들 때만 Git 제외 목록에 자동으로 추가됩니다. 파일을 손으로 만들었다면.gitignore에 직접 추가해야 개인 설정이 저장소에 올라가지 않습니다.
폴더 안에 무엇이 있는지
| 파일·폴더 | 하는 일 | 위치 |
|---|---|---|
CLAUDE.md | 작업 시작마다 읽는 프로젝트 규칙 | 프로젝트 루트 또는 .claude/ |
rules/*.md | 주제별 규칙, 특정 파일에만 적용 가능 | .claude/rules/, ~/.claude/rules/ |
settings.json | 권한, 훅, 환경변수와 모델 기본값 | .claude/, ~/.claude/ |
settings.local.json | 이 프로젝트에서 나만 사용하는 설정 | .claude/ |
skills/이름/SKILL.md | 이름으로 불러 쓰는 반복 작업 절차 | .claude/skills/, ~/.claude/skills/ |
agents/*.md | 별도 맥락에서 일하는 보조 Agent 정의 | .claude/agents/, ~/.claude/agents/ |
commands/*.md | /이름으로 실행하는 단일 프롬프트 | .claude/commands/ |
실습에서 만드는 Skill도 .claude/skills/ 아래에 저장됩니다. 폴더를 새로 배우는 것이 아니라 이미 사용하던 위치를 정리하는 것입니다.
MCP 서버 등록과 개인 기록은 .claude 폴더 밖에 있습니다.
| 파일·폴더 | 하는 일 | 공유 방식 |
|---|---|---|
.mcp.json | 팀이 함께 쓰는 MCP 서버 등록 | 프로젝트 루트, 저장소에 함께 저장 |
~/.claude.json | 개인 MCP 서버 등록과 앱 상태 | 내 PC에만 저장 |
~/.claude/projects/프로젝트/memory/ | 도구가 스스로 적어 두는 메모 | 내 PC에만 저장 |
핵심 기술 요소
MCP 서버의
local범위는~/.claude.json에 저장되고, 설정 파일의 개인 범위는 프로젝트 안.claude/settings.local.json에 저장됩니다. 이름은 비슷하지만 위치와 적용 범위가 다릅니다.
내부통제 관점에서 확인할 것
- 허용 범위는 공유 설정에 적습니다.
.claude/settings.json은 저장소에 함께 저장되므로 누가 언제 무엇을 허용했는지 변경 이력으로 남습니다. 개인 설정에만 적은 허용은 내 PC에만 남아 나중에 검토할 수 없습니다. - 반드시 막아야 하는 동작은 규칙 문서가 아니라 권한으로 정합니다.
CLAUDE.md는 도구가 참고하는 안내이며 실행을 막는 수단이 아닙니다. 확실히 막으려면permissions의 거부 규칙이나 훅을 사용합니다. - 인증정보와 실제 자료 경로를 공유 설정에 넣지 않습니다. 공유 파일은 저장소를 통해 그대로 전달됩니다. 판단 기준은 SAFE-01 · 파일·데이터·기밀정보 다루기에서 확인합니다.
- 대화 기록이 평문으로 남습니다. 도구를 거친 파일 내용, 명령 결과와 붙여 넣은 원문이
~/.claude아래 기록으로 저장됩니다. 실습에 실제 회사자료를 사용하지 않는 이유이기도 합니다.
조회 Tool만 허용하고 변경 Tool을 빼면 조회와 실행의 경계를 파일로 남길 수 있습니다.
{
"permissions": {
"allow": ["mcp__mock-erp__get_control_population", "mcp__mock-erp__get_case_evidence"],
"deny": ["Read(./.env)", "Bash(rm *)"]
}
}MCP Tool은 mcp__서버이름__Tool이름 형식으로 적고 괄호를 사용하지 않습니다. 이렇게 정한 경계를 누가 승인하고 언제 중단하는지는 SAFE-02 · AI·도구·업무 담당자의 역할과 책임에서 이어집니다.
실제로 적용되었는지 확인하기
파일을 고쳐도 동작이 그대로라면 내용을 다시 고치기 전에 파일이 실제로 읽혔는지 확인합니다. 인터랙티브 CLI에서 /context를 실행하면 이번 작업에 읽힌 규칙 파일 목록을 볼 수 있고, /memory는 규칙 파일과 메모의 위치를 열어 확인·수정할 수 있습니다.
자주 나는 실패와 복구
| 증상 | 원인 | 복구 |
|---|---|---|
| 설정을 고쳤는데 그대로입니다 | 더 우선하는 설정이 같은 항목을 덮었습니다 | 조직, 프로젝트 개인, 프로젝트 공유, 전역 순서로 같은 항목을 찾습니다 |
| 시작할 때 설정 오류가 표시됩니다 | 설정 파일이 주석과 마지막 쉼표를 허용하지 않습니다 | // 주석과 마지막 쉼표를 지우고 다시 시작합니다 |
| 다른 프로젝트에서도 같은 규칙이 적용됩니다 | 프로젝트 전용 규칙을 전역 파일에 적었습니다 | 해당 내용을 프로젝트 .claude/로 옮깁니다 |
| 규칙을 따르지 않습니다 | 규칙이 서로 충돌하거나 파일이 깁니다 | 충돌하는 문장을 정리하고 한 파일을 200줄 이내로 유지합니다 |
| 개인 설정이 저장소에 올라갔습니다 | 파일을 손으로 만들어 제외 목록에 없습니다 | .gitignore에 .claude/settings.local.json을 추가합니다 |
공식 근거
- Claude Code 설정 — 설정 파일의 위치와 적용 우선순위
- .claude 디렉터리 — 폴더에 들어가는 파일과 공유 여부
- 권한 설정 — 허용·거부 규칙의 형식
- 프로젝트 기억 — 규칙 파일이 읽히는 순서와 크기 기준