muaco Tech Note

Claude Codegithub.com

Claude Code 작업 디렉터리 밖 파일 쓰기 막기settings.json 한 줄 설정

settings.json에 한 줄을 넣어 Claude Code가 작업 디렉터리 밖에 파일을 쓰지 못하게 막고, 실제로 거부되는지 확인하는 법을 알려 드립니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

settings.json에 한 줄을 넣으면 Claude Code가 작업 디렉터리 밖에 파일을 만들거나 고치지 못합니다. 설정 이름은 permissions.blockWritesOutsideWorkingDirectories이고, 2026년 10월 30일에 나온 v2.1.314에서 생겼습니다.

작업 디렉터리는 Claude Code를 켠 폴더입니다. 이 설정을 켜면 Write, Edit, NotebookEdit 세 도구가 그 바깥 경로를 거부합니다. 권한 모드(Claude가 허락을 얼마나 자주 받을지 정하는 방식)를 무엇으로 두든 똑같이 막힙니다.

미리 갖춰야 할 준비

  • Claude Code 2.1.314 이상. 그보다 낮은 버전에는 이 설정이 없습니다. 버전 확인은 따라 하기 첫 단계에서 합니다.
  • Claude Code를 쓸 수 있는 계정. Pro, Max, Team, Enterprise, Console 계정 중 하나가 있어야 합니다. 무료 claude.ai 요금제에는 Claude Code가 들어 있지 않습니다.
  • 터미널과 텍스트 편집기. 터미널은 글자로 컴퓨터에 명령을 내리는 창입니다. 설정 파일은 메모장이나 VS Code 같은 편집기로 고칩니다.

미리 밝혀 둘 점이 있습니다. 10월 30일 현재 공식 설정 문서에는 이 키의 설명이 아직 올라와 있지 않습니다. 그래서 동작은 릴리스 노트의 설명을 기준으로 삼고, 설정 파일 다루는 법은 설정 문서를 따랐습니다.

전체 흐름은 네 걸음입니다.

따라 하기: 한 줄 넣고 거부 확인하기

준비: 버전 확인

따라 하기
  1. 터미널을 열고 claude --version을 입력하세요. 2.1.314 (Claude Code)처럼 2.1.314 이상의 숫자가 나오면 설정 단계로 넘어갑니다.
  2. 숫자가 더 낮으면 claude update를 실행하세요. Successfully updated from으로 시작하는 줄이 뜨면 1단계를 다시 해서 숫자를 확인합니다.

설정: settings.json에 한 줄 넣기

따라 하기
  1. 내 컴퓨터의 모든 프로젝트에 걸려면 사용자 설정 파일 ~/.claude/settings.json을 고르세요. Windows에서는 %USERPROFILE%\.claude\settings.json이 같은 파일입니다.
  2. 한 프로젝트에만 걸고 싶다면 1단계 대신 그 프로젝트 폴더 안의 .claude/settings.json을 고르세요. 이 파일을 저장소에 올리면 함께 일하는 사람에게도 같은 규칙이 걸립니다.
  3. 이미 파일이 있다면 새로 만들지 말고 열어서 고치세요. 새 파일로 덮어쓰면 원래 있던 설정이 사라지니, 파일이 없을 때만 새로 만듭니다.
  4. 빈 파일이라면 아래 내용을 그대로 붙여 넣으세요. 중괄호나 따옴표가 하나라도 빠지면 Claude Code가 설정 오류로 봅니다. 
    {
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}
  5. 이미 "permissions" 묶음이 있다면 그 안에 한 줄만 더하세요. 바로 앞 줄 끝에는 쉼표를 붙이고, 새로 넣은 마지막 줄 끝에는 붙이지 않습니다. 
    {
  "permissions": {
    "allow": [
      "Bash(npm run lint)"
    ],
    "blockWritesOutsideWorkingDirectories": true
  }
}
  6. 저장한 뒤 Claude Code를 새로 켜고 /status를 입력하세요. Setting sources 줄에 User settings처럼 고른 파일의 종류가 보이면 제대로 읽힌 상태입니다.

Claude Code는 설정 파일이 바뀌면 대부분 바로 다시 읽습니다. 그래도 확인은 새로 켠 세션에서 해야 앞선 상태와 섞이지 않습니다.

값을 true로 적은 까닭도 밝혀 둡니다. 릴리스 노트에는 값의 형태가 적혀 있지 않습니다. 먼저 나온 읽기 차단 설정이 true로 켜는 방식이라 같게 적었고, 실제로 막히는지는 다음 단계에서 봅니다.

확인: 바깥에 저장해 보기

따라 하기
  1. 시험용 폴더를 만들고 그 안에서 Claude Code를 켜세요. 터미널에 아래 세 줄을 한 줄씩 입력합니다. 
    mkdir blocktest
cd blocktest
claude
  2. Claude에게 "상위 폴더에 outside.txt 파일을 만들고 안녕이라고 적어 주세요"라고 요청하세요. 상위 폴더는 지금 폴더를 감싼 한 칸 위 폴더라서 작업 디렉터리의 바깥입니다.
  3. Claude의 답을 읽어 보세요. 그 경로에는 쓸 수 없어 파일을 만들지 못했다는 내용이면 설정이 걸린 상태입니다.
  4. 터미널 창을 하나 더 열고, 1단계와 같은 위치에서 ls를 입력하세요(Windows CMD는 dir). 목록에 blocktest는 있는데 outside.txt가 없으면 성공입니다.
  5. 처음 창으로 돌아가 "이 폴더 안에 inside.txt 파일을 만들어 주세요"라고 요청하세요. 허락을 묻는 창이 뜨면 승인하고, 파일이 생기면 바깥만 골라 막힌다는 확인까지 끝납니다.

거부 메시지의 정확한 문구는 릴리스 노트에도 설정 문서에도 실려 있지 않습니다. 그래서 이 글은 문구가 아니라 파일이 생겼는지로 판단합니다. 프로젝트 설정 파일에 넣었다면 시험용 폴더 대신 그 프로젝트 폴더에서 같은 순서로 해 보세요.

막히기 쉬운 곳

업데이트했는데 버전이 2.1.314보다 낮습니다

claude update를 했는데도 숫자가 그대로일 수 있습니다. 설치 방법과 채널에 따라 새 버전이 늦게 오기 때문입니다. Homebrew의 claude-code와 stable 채널은 보통 일주일쯤 지난 버전을 받습니다.

Homebrew로 깔았다면 brew upgrade claude-code, WinGet이라면 winget upgrade Anthropic.ClaudeCode로 직접 올리세요. 그래도 낮으면 아직 그 채널에 도착하지 않은 상태입니다. 며칠 뒤 다시 확인해 보세요.

켜자마자 Settings Error 창이 뜹니다

설정 파일의 문법이 틀렸다는 신호입니다. settings.json은 규칙이 엄격해서 주석(//)이나 마지막 항목 뒤 쉼표 하나만 있어도 오류로 봅니다. 창에서는 Claude의 도움으로 고치기, 종료, 고장 난 설정을 빼고 계속하기 중에서 고릅니다.

계속하기를 고르면 이 차단 설정도 빠진 채 돌아갑니다. 어느 줄이 문제인지 모르겠다면 터미널에서 claude doctor를 실행하세요. 세션을 열지 않고 설정 파일 검증 오류를 보여 줍니다.

프로젝트 설정에 넣었는데 /status에 보이지 않습니다

프로젝트의 하위 폴더에서 Claude Code를 켰는지 먼저 보세요. Claude Code는 공유 프로젝트 설정 .claude/settings.json을 세션을 시작한 폴더에서 읽습니다. .claude 폴더가 들어 있는 폴더로 옮겨 가서 다시 켜면 됩니다.

거부된 뒤 Claude가 터미널 명령으로 다시 쓰려 합니다

Write가 막히면 Claude가 셸 명령(터미널에 치는 명령)으로 같은 파일을 만들겠다고 나설 수 있습니다. 릴리스 노트가 꼽은 도구는 Write, Edit, NotebookEdit 셋뿐입니다. 이 설정이 셸 명령까지 막는지는 문서에 나와 있지 않습니다.

직원이 건마다 결재를 받듯, Manual 모드에서는 셸 명령도 실행 전에 허락을 묻습니다. 그 창에서 거절하면 됩니다. 셸 명령까지 막아 두려면 아래에 소개하는 샌드박스를 함께 쓰세요.

꼭 써야 하는 바깥 폴더가 있습니다

업무에 필요한 다른 폴더에도 쓰기가 거부됩니다. 그 폴더가 작업 디렉터리에 들어 있지 않아서입니다. 작업 디렉터리는 켠 폴더에 더해 따로 추가한 폴더까지를 말합니다.

세션 중에는 /add-dir, 켤 때는 --add-dir <경로>로 폴더를 더하세요. 다만 이 쓰기 차단이 추가한 폴더를 어떻게 다루는지는 아직 문서에 없습니다. 더한 뒤 확인 단계처럼 한 번 시험해 보세요.

여기서 더 나아가려면

읽기까지 막고 싶다면 v2.1.257에 나온 짝 설정 blockReadsOutsideWorkingDirectories를 같은 "permissions" 묶음에 true로 넣으세요. 바깥 경로를 읽는 Read, Grep, Glob, LSP 호출이 거부됩니다.

셸 명령은 샌드박스가 맡습니다. 운영체제 수준에서 파일과 네트워크 접근을 묶어 두는 장치입니다. Windows에서는 WSL 2에서만 쓸 수 있으니 환경부터 확인해 보세요.

이상으로 글 마치겠습니다.

출처

#Claude Code#권한#permissions#settings.json#작업 디렉터리#파일 쓰기 제한#보안 설정

같은 분류의 글