Claude Code 프로젝트 설정, 규칙과 도구 허용을 어떻게 고정하나

Claude Code 설정을 프로젝트에 고정하려면 .claude/settings.json(공유)과 .claude/settings.local.json(개인)에 permissions allow/ask/deny를 두고, /permissions·/status로 적용 범위를 확인합니다.

이 글은 공식 문서를 기준으로 작성했으며, CLI 버전에 따라 키가 바뀔 수 있습니다. 구독 요금은 다루지 않습니다.

프로젝트 단위 설정은 어디에 두나?

한 줄 답: 팀 공유는 .claude/settings.json, 개인 예외는 .claude/settings.local.json, 전역 취향은 ~/.claude/settings.json에 둡니다.

User: ~/.claude/settings.json — 이 머신에서 모든 프로젝트에 적용되는 개인 기본값입니다.
Shared project: .claude/settings.json — 폴더·레포 단위로 공유하며, git에 커밋해 팀과 동기화합니다.
Project local: .claude/settings.local.json — 한 프로젝트 안에서의 개인 오버라이드입니다. Claude Code가 만들면 git에서 제외 처리되며, 직접 만든다면 .gitignore에 넣는 것을 권장합니다.
Managed: 조직의 managed-settings.json 등입니다. 개발자 설정으로는 덮어쓰기 어렵습니다.

설치만으로는 settings 파일이 자동으로 생기지 않습니다. /config를 쓰거나 권한 확인 시 “다시 묻지 않기”를 선택하면 그때 생성될 수 있습니다.

우선순위는 Managed → CLI --settings → local → shared project → user 순으로 높습니다. 다만 permissions.allow처럼 리스트 형태인 키는 상위·하위 값이 병합됩니다.

현재 적용 상태는 /status 화면의 Setting sources에서 확인합니다. JSON 형식이 깨졌다면 같은 화면에 Settings Error로 표시됩니다. 에디터 자동완성이 필요하면 $schema에 https://json.schemastore.org/claude-code-settings.json을 넣습니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

도구·네트워크 허용은 어떻게 좁히나?

한 줄 답: permissions는 deny → ask → allow 순으로 평가하고, 네트워크는 WebFetch(domain:…) allow와 Bash deny를 짝지어 좁힙니다.

/permissions 명령으로 현재 규칙과 출처 파일을 확인·편집할 수 있습니다. 규칙 형식은 Tool 또는 Tool(specifier)이며, Bash(npm run *), Read(./.env), WebFetch(domain:example.com), mcp__server__tool처럼 씁니다.

평가 순서는 deny, 그다음 ask, 그다음 allow입니다. deny에 걸린 항목은 더 좁은 allow 규칙을 추가해도 예외로 만들 수 없습니다.

CLAUDE.md나 프롬프트에 적은 지시는 행동을 유도할 뿐이고, 실제로 실행을 막거나 허용하는 것은 Claude Code의 permissions 계층입니다.

프로젝트 .claude/settings.json에 있는 permissions.allow와 additionalDirectories는 워크스페이스 trust를 수락한 뒤에만 적용됩니다. 반면 deny·ask는 trust 여부와 관계없이 즉시 적용됩니다.

네트워크 접근을 좁히려면 대략 다음 방향을 씁니다.

deny에 Bash(curl *) 같은 규칙을 넣고, 허용할 호스트만 WebFetch(domain:허용호스트)로 allow합니다.
Bash 규칙만으로는 다른 실행 경로나 sh -c 우회가 가능하므로, 더 엄격하게 막으려면 sandbox 네트워크 allowlist를 함께 검토해야 합니다(이 글에서는 깊이 다루지 않습니다).

defaultMode나 bypassPermissions는 격리된 환경이 아니면 주의해서 써야 합니다. 조직 단위에서는 disableBypassPermissionsMode로 이 모드 자체를 막을 수 있습니다. 요금제나 플랜별 기본 권한 모드가 다르다고 단정하지는 않습니다.

{
  "permissions": {
    "allow": ["Bash(npm run *)", "WebFetch(domain:docs.anthropic.com)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  }
}

Cursor 규칙 파일과 어떻게 맞추나?

한 줄 답: Cursor 규칙(.cursor/rules, AGENTS.md 등)은 의도·스타일을 적는 층이고, Claude Code settings.json의 permissions는 도구 허용을 강제하는 층으로 역할을 나눕니다.

Cursor의 프로젝트 규칙 파일은 코딩 컨벤션이나 워크플로 지시를 담습니다. .mdc 규칙을 구체적으로 작성하는 방법은 이 글 범위 밖이므로, 공식 Rules 문서를 참고하는 것이 좋습니다.
Claude Code에서 상시 지시문은 CLAUDE.md 계열 파일이 맡고, 그 지시가 실제로 실행 가능한지는 .claude/settings.json의 permissions가 결정합니다.

두 도구를 맞추는 원칙은 다음과 같이 정리할 수 있습니다.

“무엇을 하라 또는 하지 말라”는 문구는 규칙 마크다운(Cursor 규칙, CLAUDE.md)에 적습니다.
“어떤 Bash·Read·WebFetch·MCP를 허용하거나 차단할지”는 settings의 permissions에 적습니다.
같은 금지 사항(예: .env 읽기 금지)을 양쪽에 적어도, 실제 강제력은 permissions의 deny에서 나옵니다.

AGENTS.md를 @AGENTS.md로 임포트하거나 심볼릭 링크로 CLAUDE.md와 동기화하는 절차는 이 글에서 다시 다루지 않습니다. 자세한 내용은 이전 글을 참고하시기 바랍니다.

FAQ

settings.local.json을 커밋해도 됩니까?

개인용 파일이므로 보통 커밋하지 않습니다. git에 추적되면 그 안의 allow 규칙도 trust 대상이 될 수 있습니다.

allow에 넣었는데도 계속 물어봅니다. 왜 그런가요?

상위 단계의 deny·ask가 먼저 걸렸거나, 워크스페이스 trust를 아직 수락하지 않았거나, 복합 Bash 명령이 규칙과 다르게 매칭됐을 수 있습니다. /permissions로 어떤 규칙이 어디서 왔는지 먼저 확인합니다.

CLAUDE.md에 “curl 금지”라고만 적으면 충분한가요?

그 문구는 유도만 될 뿐 강제되지 않습니다. 실제로 막으려면 permissions.deny에 해당 규칙을 넣어야 합니다.

Claude 구독 요금은 어떻게 되나요?

이 글의 범위 밖입니다. 확인하지 않은 가격을 숫자로 적지 않겠습니다.