Claude Code의 확인 다이얼로그를 설계하는 — permissions allowlist 실습

"승인하시겠습니까?"가 너무 많다

Claude Code를 사용하기 시작하면 가장 먼저 신경 쓰이는 것이 바로 확인(confirmation) 다이얼로그입니다.

파일을 읽을 때마다 묻고, Bash 명령어를 실행할 때마다 묻고, 도구 호출 시마다 Yes/No를 요구받습니다.

이는 안전을 위한 설계이지만, 사용자 경험으로는 무겁습니다. "이 질문은 매번 당연한 것인데"라는 판단을 반복하게 됩니다.

Claude Code의 permissions는 settings.json에서 설계할 수 있습니다. 어떤 작업을 자동 승인하고, 어떤 작업을 반드시 확인하도록 할지 선언적으로 정의하는 것입니다. 이 설계를 결정하면, Claude Code가 "함께 일할 동료"처럼 느껴집니다.

permissions 구조

작업이 요구될 때마다, deny → allow → defaultMode 순서로 평가됩니다.

~/.claude/settings.json

(글로벌 설정)에 작성합니다.

{
"permissions": {
"allow": [...],
...
}

allow
: 무조건 실행을 허가하는 패턴 -
deny
: 절대 실행시키지 않는 패턴 -
defaultMode
: allow에도 deny에도 해당하지 않을 경우의 동작

defaultMode
의 선택지:

실제 allowlist 설계

아래는 실제로 운영하고 있는 allowlist입니다.

{
"permissions": {
"allow": [
...

allowlist 설계 방침

Bash(*)
으로 모든 Bash를 개방한 이유

Bash 명령어의 화이트리스트를 개별적으로 작성하려면, git status, git log, npm install, python main.py…처럼 끝이 없습니다. 개인 개발 환경에서는 "Bash는 전부 OK"로 간주하고, denylist에서 위험한 작업을 명시적으로 차단하는 것이 더 실용적입니다.

Skill을 개별적으로 허가한 이유

Skill(git-management:*)처럼 와일드카드를 사용하면, 해당 스킬이 호출하는 모든 서브 커맨드가 자동 승인이 됩니다. 자주 사용하는 스킬(git 관리・회고)은 매번 확인하지 않아도 되기 때문입니다.

경로 패턴으로 Edit을 제한한 이유

"Edit(~/.claude/skills/new-skill/**)"

스킬 개발 중에는 특정 디렉터리의 파일을 빈번하게 편집합니다. 경로 패턴으로 범위를 좁힘으로써 "이 디렉터리의 편집은 신뢰한다"라는 의도를 표현할 수 있습니다.

denylist로 지키는 "절대 금지"

allowlist로 광범위하게 개방한 만큼, denylist로 확실히 막습니다.

"deny": [
"Read(.env*)", // 환경 변수 파일은 읽게 하지 않음
"Read(*.key)", // 비밀 키는 읽게 하지 않음
...

deny는 allow보다 우선합니다. Bash(*)로 모든 Bash를 허가했더라도, Bash(rm -rf *)는 deny이므로 실행되지 않습니다.

defaultMode 활용하기

"acceptEdits"을 기본으로 사용하고 있습니다.

• Edit・Write: 매번 승인할 필요도 없습니다 (파일 변경은 git으로 추적 가능).
• Bash・WebFetch: allowlist에 포함되지 않은 것은 확인합니다.

완전 자동의 "auto"는 혼자 사용하는 실험 환경용입니다. 본 서비스 환경의 파일을 건드릴 위험이 있다면 사용하지 않는 것이 좋습니다.

설정 키우기

처음부터 완벽한 allowlist를 만들 필요는 없습니다.

단계 1: defaultMode를 "acceptEdits"로 설정하기

먼저 이것만으로도 파일 작업의 확인 다이얼로그가 크게 줄어듭니다.

단계 2: 자주 사용하는 명령어를 allow에 추가하기

"또 이거네"라고 생각한 명령어를 allow에 넣어 나갑니다. 일주일 사용하면 패턴이 보이기 시작합니다.

단계 3: 기밀 파일을 deny에 넣기

.env, *.key

、프로덕션 설정 파일의 패턴을 deny에 추가한다.

설계의 효과

allowlist 설계 전후의 체감 변화:

자주 사용하는 작업의 확인 다이얼로그가 거의 없어진다. 반면 위험한 작업은 설계 전보다 확실하게 차단된다.

요약

• settings.json의 permissions를 통해 확인 다이얼로그를 선언적 (declarative)으로 설계할 수 있다. allowlist로 "신뢰하는 작업"을, denylist로 "절대 안 되는 작업"을 정의한다.
• deny는 allow보다 우선순위가 높기 때문에, 범위를 넓게 개방하면서도 안전하게 운용할 수 있다.
• defaultMode: "acceptEdits"로 시작하여, 사용하면서 점진적으로 키워나가는 것이 현실적이다.

확인 다이얼로그는 보안 (security) 문맥에서는 올바른 설계다. 하지만 매번 자명한 판단을 반복하는 것은 컨텍스트 스위칭 (context switch) 비용이 된다. allowlist는 그 비용을 줄이기 위한 설계이며, 보안을 완화하는 것이 아니다.

permissions 설계는 Claude Code의 "신뢰 경계선 (trust boundary)"을 정의하는 작업이다. allowlist와 denylist를 명시함으로써, 자동화의 혜택을 누리면서도 위험한 작업은 확실하게 차단할 수 있다.

이 설계 사상의 전체 모습은 유료 도서 「Claude Code 하네스 엔지니어링 실전 Playbook」에서 체계화되어 있다.

좋아요나 댓글로 반응해 주시면 큰 힘이 됩니다!

Discussion