Claude Code로 작업하다 보면, npm install이나 git status를 실행할 때마다 "이 도구를 허가하시겠습니까?"라는 프롬프트가 나타나 흐름이 끊길 때가 있다. 매번 엔터를 누르는 것이 은근히 스트레스이며, 긴 세션에서는 체감상 10% 정도의 시간을 빼앗기는 기분이 들었다.
이 기사는 그 프롬프트를 90% 줄이기 위한 settings.json 작성법을 정리한 메모이다. 같은 부분에서 어려움을 겪은 사람들을 위해, 내가 시도했던 allowlist 패턴과 실수했던 포인트들을 남겨둔다.
-
Claude Code를 일상적으로 사용하는 엔지니어
-
도구 허가 프롬프트에 지친 사람
-
.claude/settings.json의 동작을 제대로 정리하고 싶은 사람
-
macOS 14.x(Darwin 24.6.0)
-
Claude Code(/permissions 명령어를 사용할 수 있는 버전) - Node.js 22.x / Python 3.13
-
셸: zsh
-
~/.claude/settings.json의 permissions.allow에 Bash·MCP의 안전한 정형 패턴을 열거
-
프로젝트 고유의 것은 .claude/settings.json에 나누어 작성
-
Bash는 Bash(npm install:*)와 같이 **콜론(:) + 와일드카드(*)**가 필수(이를 모르면 매칭되지 않음)
-
deny는 allow보다 우선순위가 높음(이 부분에서 실수하기 쉬움)
-
위험한 계열(rm -rf, git push --force)은 명시적으로 deny에 넣어 사고 방지
이렇게 하면 npm / git status / gh pr / Read / Grep 등의 프롬프트는 거의 사라진다.
먼저 현재 나오고 있는 프롬프트의 내역을 보고 싶다. 최근 세션의 로그를 집계하여 빈번하게 발생하는 도구를 나열해 주는 /fewer-permission-prompts라는 스킬이 동봉되어 있다.
/fewer-permission-prompts
출력 이미지(내 환경의 예):
[summary] 최근 200 세션 동안 허가 프롬프트가 발생한 도구 상위
- Bash(npm install:*) 42 회
- Bash(git status:*) 35 회
...
이를 바탕으로 settings.json에 추가할 후보를 결정한다. 자신이 일상적으로 여러 번 허가하고 있는 것을 우선하여 allowlist에 넣어가는 것이 정답이다. 처음부터 전부 작성하려고 하면 입도(granularity)가 어긋나게 된다.
~/.claude/settings.json(모든 프로젝트 공통)을 편집한다. 읽기 계열·조사 계열은 기본적으로 allow에 넣어도 문제없다.
{
"permissions": {
"allow": [
...
]
}
}
Read · Grep · Glob과 같은 읽기 전용 도구는 통째로 allow에 넣어도 문제없다. 이것만으로도 프롬프트 수는 대폭 줄어든다.
리포지토리 직하의 .claude/settings.json에 프로젝트 고유의 명령어를 작성한다. 예를 들어 Next.js 프로젝트라면:
{
"permissions": {
"allow": [
...
]
}
}
pnpm과 npm 같은 패키지 매니저(Package Manager)의 차이는 프로젝트 측으로 분리하는 것이 운영상 깔끔하다. 글로벌하게 pnpm을 작성해 버리면 npm 프로젝트에 불필요한 허가가 섞여 들어간다.
Claude Code를 한 번 종료하고 재시작하거나, /config reload로 설정을 재로드한다. 그 후 평소처럼 작업하여 npm install이나 git status에서 프롬프트가 나오지 않는다면 성공이다.
확인용으로 일부러 deny에 넣은 명령어를 실행해 본다:
> git push --force origin main
여기서 "허가하시겠습니까?" 프롬프트가 뜨는지 확인한다. 이것이 뜨지 않는다면 deny가 작동하지 않는 것이다(후술할 주의점 참조).
처음에 이 부분을 깨닫지 못해서 1시간을 허비했다.
NG 예시:
"allow": ["Bash(npm install)"]
이렇게 작성하면 **완전 일치 (Exact Match)**로 취급되어, npm install --save react와 같이 인자(argument)가 포함되어 있으면 매칭되지 않는다. 프롬프트가 계속 나타나며 "allow에 적었는데 왜 안 되지?"라는 상황이 발생한다.
OK 예시:
"allow": ["Bash(npm install:*)"]
:*가 "이후의 인자는 무엇이든 상관없음"을 의미하는 와일드카드(wildcard)이다. Bash 도구 특유의 표기법으로, 콜론(:)이 경계 기호(boundary symbol)로 사용된다는 점에 주의해야 한다. Bash(npm install*)와 같이 아스테리스크(*)만 붙여서는 작동하지 않는다.
서브 커맨드(subcommand)가 가변적인 경우에는 Bash(npm run *:*)와 같이 커맨드 쪽에도 *를 넣는다. 이렇게 하면 npm run dev, npm run build, npm run test 모두에 적용된다. allow에 Bash(git push:*)라고 쓰고, deny에 Bash(git push --force*)라고 쓰면, git push --force는 deny가 우선하므로 정상적으로 프롬프트가 나타난다.
여기서 "allow에 적었으니 그냥 통과되어야 한다"라고 착각하면 보안 사고로 이어질 수 있다. 금지하고 싶은 작업은 명시적으로 deny에 작성한다. allow와 deny에서 동일한 패턴이 충돌하면 deny가 승리한다는 점을 기억해 두자.
우선순위는 ~/.claude/settings.local.json (로컬 개인) → .claude/settings.json (프로젝트) → ~/.claude/settings.json (사용자) 순이며, 더 구체적인 계층이 나중에 적용되어 덮어쓴다(last-one-wins).
단, deny는 어느 레이어(layer)에서도 유효하다 (사용자 계층에서 deny한 것을 프로젝트 계층의 allow로 덮어쓸 수 없다). 이를 통해 보안을 담보한다.
"프로젝트에서 일시적으로 허용하고 싶다"면, 글로벌 설정을 완화하는 것이 아니라 .claude/settings.local.json에 개인용 allow를 추가하는 것이 정답이다.
MCP 서버의 도구를 허용할 때는 mcp__<server>__<tool> 형식을 사용한다.
"allow": ["mcp__notion__notion-fetch"]
포인트는 다음과 같다:
- 서버 이름과 "mcp" 사이의 구분자는 **언더스코어 두 개(
__)**이다.
- 도구 이름 쪽은 실제 등록된 이름을 그대로 사용한다 (하이픈(
-) 구분인 경우 그대로 유지).
이를 모르면, Notion 공식 MCP와 같이 notion-fetch라는 이름의 도구를 허용할 때, mcp__notion__notion_fetch라고 잘못 입력하여 영원히 매칭되지 않는 사고가 발생할 수 있다.
설정 후 /permissions를 입력하면 실제로 매칭되고 있는 규칙 목록을 볼 수 있으므로, 작성 직후 반드시 확인한다.
.claude/settings.local.json은 개인의 추가 allowlist용이다. .gitignore에 넣어두지 않으면 팀 멤버의 설정을 덮어쓰거나, 자신의 개인 허용 설정이 유출될 수 있다.
확인 방법:
grep settings.local.json .gitignore
검색 결과가 없다면 추가한다:
echo ".claude/settings.local.json" >> .gitignore
Claude Code는 첫 init 시 .gitignore에 자동으로 추가해 주는 경우가 많지만, 오래된 리포지토리(repository)에는 포함되어 있지 않을 수 있으므로 한 번 확인해 두는 것이 좋다.
왜 프롬프트가 뜨도록 설계되었는가? Claude Code는 **에이전트 (Agent)**이므로, 인간이 감시하고 있지 않아도 명령을 실행하도록 설계되어 있다. 이를 무제한으로 허용하면 rm -rf /와 같은 사고가 발생할 수 있다. 따라서 "읽기 계열은 기본 허용, 쓰기·실행 계열은 확인"이라는 기본 노선을 취하고 있다.
allowlist는 "자신이 안전하다고 판단한 것만 자동으로 허용한다"는 권한 관리 메커니즘으로, OS의 sudoers와 유사한 발상이다. 자동으로 허용한다는 것은, 스스로 그 안전성에 책임을 진다는 의미이기도 하다.
실운용에서는 "읽기 계열은 통째로 allow, 쓰기 계열은 개별 allow, 파괴 계열은 명시적 deny"라는 3단계 전략을 취하면 편의성과 안전성의 균형을 맞출 수 있다.
/fewer-permission-prompts에서 자주 발생하는 도구들을 집계하여 위에서부터 해결한다.- 글로벌 (
~/.claude/settings.json) 설정과 프로젝트 (.claude/settings.json) 설정을 구분하여 사용한다.
- Bash 패턴은
Bash(명령어:*) 형태로 와일드카드 (Wildcard)를 붙인다.
deny는 allow보다 우선순위가 높으므로, 위험한 작업은 명시적으로 deny 한다..claude/settings.local.json은 .gitignore에 추가한다.
이것만으로도 프롬프트 피로 (Prompt fatigue)의 90%를 없앨 수 있다. 작업 흐름 (Flow)이 끊기지 않고 계속 이어질 수 있다는 점은 작업 시간이 길어질수록 더욱 큰 효과를 발휘한다.
