Claude Code는 강력한 CLI 에이전트이지만, 초기 설정 그대로 사용하면 API 키 유출이나 파괴적인 명령의 오실행에 직면하기 쉬운 구성으로 되어 있습니다. 본 기사에서는 개인 ~ 소규모 팀에서 Claude Code를 운영함에 있어, '초기 설정으로 고정해야 할 항목'과 '운영 중에 지속적으로 지켜야 할 규칙'을 나누어 정리합니다.

용어 보충: CLI 에이전트란 터미널 상에서 동작하며, 파일 읽기/쓰기 및 셸 명령 실행까지 동반하는 AI 어시스턴트의 총칭입니다. Claude Code 외에 Codex CLI나 Gemini CLI 등이 있습니다.

0. 위협 모델: 먼저 "무엇을 지킬 것인가"를 통일하기

보안 설정 이야기는 대책을 나열하기만 하면 우선순위를 정할 수 없습니다. Claude Code 운영에서 실질적인 피해가 발생하는 경로는 대략 5가지로 정리할 수 있으며, 이후의 설정은 모두 이 중 하나를 차단하기 위해 존재합니다.

용어 보충: 프롬프트 인젝션 (Prompt Injection)이란 에이전트가 읽어들인 외부 텍스트(README, Issue 본문, 웹 페이지 등) 안에 "지금까지의 지시를 무시하라", "다음 명령을 실행하라"와 같은 명령을 심어 넣어, 본래의 사용자 지시를 덮어쓰는 공격 기법입니다.

5가지 위협의 지도가 완성되었으므로, 다음으로 각각을 차단하기 위한 "초기 설정"을 살펴보겠습니다.

1. 초기 설정

여기서 소개하는 10개 항목은 새로운 PC나 신규 멤버의 온보딩 시, 처음 30분 동안 고정해야 할 대상입니다.

1-1. 설치 경로의 고정

출처가 불분명한 바이너리나 변조된 npm 패키지를 잡게 되면, 그 시점에서 "신뢰할 수 없는 코드 실행"이 성립됩니다. 다음 3가지를 지키면 이 부분은 거의 봉쇄할 수 있습니다.

• 공식 인스톨러 또는 Anthropic 공식 npm 패키지를 통해 도입한다
• npm install -g 시에는 --ignore-scripts 병용을 검토한다
• 자동 업데이트를 ON으로 설정하여 오래된 버전을 남기지 않는다

용어 보충: --ignore-scripts는 npm이 패키지 설치 시 동봉된 postinstall (설치 완료 직후 자동으로 실행되는 스크립트) 등을 실행하지 않게 하는 플래그입니다. 편의성은 낮아지지만, 악의적인 스크립트를 실행할 리스크를 줄일 수 있습니다.

1-2. API 키 / 토큰의 보관

인증 정보 유출이 발생하는 가장 큰 원인은 설정 파일이나 dotfiles에 직접 작성하는 것입니다. 키의 보관 장소를 확실히 정하는 것만으로도 유출 경로의 대부분을 막을 수 있습니다.

• API 키를 ~/.claude/settings.json에 직접 작성하지 않는다. OS의 키체인(Keychain), 1Password CLI (op run) 등의 보안 도구를 통해 읽어오도록 한다
• 동적 또는 수명이 짧은 토큰을 사용하는 경우, 공식의 apiKeyHelper 설정을 통해 셸 스크립트에서 API 키를 반환하는 방식으로 한다 (apiKeyHelper는 5분 또는 HTTP 401 발생 시 재호출되는 사양)
• .zshrc / .bashrc에 직접 작성하는 것도 피한다 (화면 공유 · 스크린샷 시 사고의 원인이 됨)
• GitHub PAT는 최소 스코프(Scope)로 발행한다 ( repo 전체 허용이 아니라, 필요한 리포지토리만 허용)
• 키는 분기에 한 번 로테이션한다. 로테이션 절차는 사내 노트에 작성해 둔다

용어 보충: PAT (Personal Access Token)란 GitHub의 비밀번호 대신 API 액세스를 허용하는 개인용 토큰입니다. 스코프 (권한 범위)를 좁힐 수 있으므로 용도별로 나누어 사용하는 것이 정석입니다.

1-3. 글로벌 settings.json은 최소화한다

~/.claude/settings.json은 모든 프로젝트에 적용되므로, 여기에 광범위한 허용을 넣으면 영향 범위가 커집니다. 기본 규칙은 "허용은 최소, 거부는 최대"입니다.

• 기본: 글로벌에는 "모든 프로젝트 공통 거부"와 "읽기 계열의 범용 허용"만을 작성한다
• 예외: 일시적으로 검증용으로 허용을 완화하고 싶은 경우에는 .claude/settings.local.json (커밋 대상 제외)에 가둔다

용어 보충: .claude/settings.local.json

는 프로젝트 직하의 개인용 설정 파일입니다. .gitignore로 제외해 두는 것을 전제로, 공유하지 않을 실험적 설정의 저장소로 사용할 수 있습니다.

1-4. permissions.deny를 먼저 작성하기 (평가 순서는 deny → ask → allow)

Claude Code의 permissions 규칙은 공식 사양에 따라 deny → ask → allow 순으로 평가되며, 가장 먼저 일치하는 규칙이 적용된다고 정의되어 있습니다. "절대로 수행하게 하고 싶지 않은 작업"을 deny에 모아두는 것이 안전합니다.

{
"permissions": {
"deny": [
...

각 엔트리의 의도는 두 계통으로 나뉩니다.

• 쉘 계통 (Shell-based): rm -rf, sudo, curl * | sh, git push --force 등 복구가 어려운 작업을 일괄 차단
• 파일 계통 (File-based): ~/.ssh, ~/.aws, .env, secrets/ 등 인증 정보 및 기밀 파일의 읽기를 금지

파일 계통 규칙은 gitignore 구문을 따르며, ./...는 현재 디렉토리 상대 경로, ~/...는 홈 디렉토리 상대 경로, //...는 절대 경로를 지정합니다. Read(.env)와 Read(**/.env)는 동일한 의미로, 임의의 깊이에 있는 .env를 차단합니다.

WebFetch의 deny에 대하여: 공식 사양에서는 도구 이름만(WebFetch) 작성하면 모든 요청에 매칭됩니다. 도메인을 좁혀서 허용하려면 WebFetch(domain:example.com) 형태로 화이트리스트(Whitelist)를 작성합니다. WebFetch(domain:*)라는 방식은 공식 구문에 명시되어 있지 않으므로, bare WebFetch를 deny로 설정한 뒤 필요한 도메인만 allow로 개별 해제하는 것이 안전합니다.

Bash 패턴의 한계: 공식 문서에서는 "Bash(curl http://github.com *)와 같이 명령 인자(Command argument)로 도메인을 제한하는 것은 취약하다"고 주의를 주고 있습니다. 프로토콜 차이, 리다이렉트(Redirect), 변수 경유, 불필요한 공백 등으로 쉽게 우회할 수 있기 때문입니다. URL 필터링은 curl/wget을 deny로 설정하면서 WebFetch로 도메인을 제한하거나, PreToolUse hook을 통해 검증하는 방식 중 하나와 병행하여 사용하십시오.

1-5. allow list의 입도(Granularity)를 좁히기

Bash(*)와 같은 와일드카드 허용은 "모든 명령 허용"과 동일합니다. 허용은 서브 명령(Subcommand) 단위로 작성하는 것이 기본입니다.

• 기본: Bash(git status), Bash(git diff:*), Bash(ls:*)와 같이 입도를 좁힘
• 예외: Bash(npm install:*)와 같은 의존성 추가 계열을 포함할 경우, 신뢰하는 프로젝트 내부(<project>/.claude/settings.json)로 한정함
• MCP 도구: mcp__github__list_issues와 같이 개별적으로 허용

공식 사양에 따르면 ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd 등의 읽기 계열 명령은 내장되어 승인 없이 실행됩니다(모드와 관계없이). 이들은 allow 리스트에 작성할 필요가 없습니다.

1-6. additionalDirectories를 최소화하기

Claude Code는 기본적으로 실행 디렉토리의 파일에만 접근할 수 있습니다. 이를 확장하는 방법은 실행 시의 --add-dir <path> 플래그, 세션 중의 /add-dir 명령, 또는 settings.json의 additionalDirectories 세 가지입니다(공식은 settings file의 additionalDirectories로 안내하고 있습니다).

• 글로벌 설정의 additionalDirectories에는 범용적인 디렉토리를 작성하지 말 것
• 프로젝트마다 필요한 최소한의 디렉토리만 추가할 것
• ~, /, ~/Documents

와 같은 광범위한 경로는 금지 - 일시적으로 추가할 뿐이라면, 설정 파일에 남기지 말고

--add-dir <path>

나

/add-dir

을 사용하여 세션 한정으로 설정할 것

또한, additionalDirectories는 파일 읽기/쓰기 범위를 넓히는 것이지, .claude/ 하위의 설정 일체를 읽어오게 하는 메커니즘이 아니라는 점을 공식 문서에서도 명시하고 있습니다.

1-7. hooks 리뷰

hooks는 Claude의 턴 경계(turn boundary)에서 임의의 쉘 명령(shell command)을 실행할 수 있는 강력한 메커니즘입니다. 타인의 설정을 가져올 때 이곳을 간과하면 쉽게 '신뢰할 수 없는 코드 실행'이 발생할 수 있습니다.

• 타인의 settings.json이나 .claude/를 가져올 때는 반드시 hooks 섹션을 육안으로 확인할 것
• hooks 내에 curl ... | sh 형식의 명령어가 포함되어 있다면 즉시 거부할 것
• 본인이 작성하는 hooks 스크립트는 Git으로 관리하고, 변경 시에는 리뷰를 거칠 것

PreToolUse hook은 권한 평가(permission evaluation) 전후에 삽입되는 강력한 확장 포인트로, 공식 사양에서는 "exit code 2로 정지하면 allow 규칙이 있더라도 호출이 차단된다"라고 정의되어 있습니다. 조직 정책으로서 특정 작업을 절대 차단하고 싶다면, deny 규칙 + PreToolUse hook의 이중 방어 체계를 구축하십시오.

용어 보충: hooks란 Claude Code가 "도구를 실행하기 직전", "세션 시작 시", "종료 시" 등 특정 이벤트에서 자동으로 실행하는 사용자 정의 스크립트를 말합니다. 사양에 대한 자세한 내용은 Claude Code 공식 문서의 Hooks 섹션을 확인하십시오.

1-8. MCP 서버 심사 및 분리

MCP 서버는 Claude Code에 외부 서비스와의 연결구를 제공하는 메커니즘입니다. 로컬 프로세스든 외부 API든 인증 정보나 응답 내용에 접근하므로, 신뢰 경계(trust boundary)를 넘나드는 중요한 포인트가 됩니다.

• 공식 또는 대형 업체 이외의 MCP는 연결 전에 소스 및 배포처를 확인할 것
• "노출되면 안 되는 대상"과 "외부로 전송하는 MCP"를 동일한 프로젝트에서 병행하지 말 것 (예: 기밀 리포지토리를 열어둔 프로젝트에서 SNS 포스팅 관련 MCP를 활성화하지 말 것)
• MCP용 토큰은 MCP 전용으로 발급하고, 범용 PAT(Personal Access Token)를 재사용하지 말 것
• MCP 도구의 개별 허용은 mcp__<server>__<tool> 형식으로 작성할 것 (예: mcp__github__list_issues)

용어 보충: MCP (Model Context Protocol)는 Claude Code 등의 에이전트가 GitHub, Slack, 데이터베이스 등 외부 서비스와 상호작용하기 위한 표준 프로토콜입니다. MCP 서버가 '도구(tool)'를 에이전트에게 제공하는 형태가 됩니다.

1-9. .gitignore 정비

인증 정보 유출의 최종 방벽은 .gitignore입니다. 커밋 전에 감지할 수 있다면 원격(remote)으로 유출되기 전에 막을 수 있습니다.

.env
.env.*
*.pem
...

여기에 더해, GitHub 측에서 secret scanning과 push protection을 활성화해 두면 로컬에서 빠져나가더라도 원격 측에서 차단됩니다. .gitignore에만 의존하지 말고 이중 방어 체계를 갖추는 것이 안전합니다.

1-10. 격리 환경과 샌드박스(Sandbox)를 하나 준비해 둘 것

"권한(permissions)을 완화하여 자동 실행하고 싶다"는 상황은 운영하다 보면 반드시 발생합니다. 그때 호스트 전체를 노출시키지 않기 위해 격리 환경 패턴을 하나 확보해 둡니다.

• 기본: dev container / Docker / lima 상에서 구동하는 운영 패턴을 하나 정비할 것
• 파괴적인 작업이나 미지의 MCP 테스트는 git worktree를 사용하여 격리된 복사본 위에서 실행할 것
• 공식 Sandboxing을 활성화하면 Bash 명령어에 대해 OS 레벨의 파일 시스템/네트워크 제한이 추가되어, permission rule만으로는 방어하기 어려운 경로도 차단할 수 있음
• 대안으로 클라우드 상의 일회용 VM (Codespaces, Cloud Workstations)도 선택지에 포함할 것

10가지 항목의 초기 설정이 완료되었으므로, 다음으로는 운영 중에 지켜야 할 규칙을 살펴보겠습니다.

2. 운영 중에 지킬 것

초기 설정이 잘 구성되어 있더라도, 일상적인 운영 과정에서 빈틈이 생길 수 있습니다. 여기서는 특히 발생 빈도가 높은 8가지 항목을 정리합니다.

2. 운영 중에 지킬 것

2-1. 권한 모드(Permission Mode)의 구분 사용

Claude Code에는 6가지 권한 모드가 있으며, 용도에 따라 전환하여 사용하는 것이 안전합니다. CLI에서는 Shift+Tab을 통해 default → acceptEdits → plan을 순환할 수 있으며, auto / dontAsk / bypassPermissions는 실행 시 플래그를 지정하거나 특정 요건을 충족했을 때만 사용할 수 있습니다.

기본은 default, 조사만 하고 싶을 때는 plan, 안전한 리팩토링이 많을 때는 acceptEdits를 사용합니다. 요건을 충족하는 환경에서 장기 태스크를 자율적으로 수행하게 하고 싶을 때만 auto를, CI 등의 비대화형 실행은 dontAsk를, bypassPermissions는 격리 환경 내로 한정합니다.

용어 보충: auto 모드의 classifier는 Claude 본체와는 별개의 분류 모델로, 각 액션(셸 실행 · 네트워크 요청 등)을 실행 직전에 체크하여 curl | bash와 같은 외부 코드 실행, 운영 환경 배포(Production Deploy), force push 등을 기본적으로 차단합니다. 상세 사양은 공식 문서의 Permission Modes 섹션을 참조하십시오.

2-2. 프롬프트 인젝션(Prompt Injection) 대책

외부에서 가져오는 텍스트(README, Issue, PR 본문, 웹 페이지)는 모두 "적대적 입력(Adversarial Input)일 수 있다"는 전제하에 다룹니다.

• 신뢰할 수 없는 소스를 읽게 한 직후에 Bash를 자동으로 실행하지 말 것
• WebFetch의 결과에 "이전 지시를 무시하라", "다음 명령어를 실행하라" 등의 내용이 섞여 있지 않은지 에이전트의 응답을 관찰할 것
• 에이전트의 출력에 승인되지 않은 명령어 실행이나 파일 쓰기 제안이 포함되어 있지 않은지 매번 육안으로 확인할 것

2-3. 커밋(Commit) · 푸시(Push)의 수동 리뷰

자동 커밋은 할루시네이션(Hallucination)이나 잘못된 삭제를 "이력(History) 속에 교묘히 섞어 넣는" 효과를 가집니다. 최소한 PR 생성 단계까지는 사람이 개입하는 흐름을 구축해야 합니다.

• git push를 CLI 에이전트에게 전적으로 맡기지 말고, PR 생성 단계에서 사람이 리뷰한 후 push 할 것
• --no-verify와 --force 사용을 금지할 것 (CLAUDE.md에도 명문화해 두면 사고를 줄일 수 있음)
• 스테이징(Staging) 시 git commit -A / git add .를 피하고, 파일을 지정하여 stage 할 것

2-4. 시크릿(Secret) 유출 모니터링

유출을 방지하는 것뿐만 아니라, 유출되었음을 인지했을 때의 초동 대처도 중요합니다.

• 정기적으로 gh secret-scanning alerts list를 실행할 것

하여 유출 알림을 확인한다 - 유출 의심이 있다면, (1) 즉시 해당 키를 무효화 → (2) 이력에서 제거 (git filter-repo) → (3) 신규 발행 순으로 대응한다 - 리포지토리(Repository) 공개 전에는 trufflehog filesystem .으로 1회 스캔한다

2-5. 외부 전송 도구의 의식적 이용

외부 리뷰 SaaS (예: Claude Code에 내장된 /ultrareview와 같이, 코드를 외부 서버로 보내 평가받는 리뷰 커맨드), 공개 Paste, 외부 LLM에 대한 요약 요청 등 외부 전송을 동반하는 커맨드는 입력 내용이 서버 측에 남습니다.

• 사내 비밀 또는 고객 데이터가 포함된 코드에 대해서는 외부 전송 계열 커맨드를 사용하지 않는다
• 사용하는 경우에는 사전에 해당 파일을 마스킹(Masking)하거나, 기밀을 제외한 별도의 워크트리(Worktree)에서 실행한다

2-6. 정기 유지보수 사이클

설정은 "한 번 설정하고 끝"이라면 퇴화합니다. 최소한 아래의 사이클을 반복합니다.

2-7. 인시던트 대응 절차를 한 장으로 정리해 두기

유출이나 실수로 인한 삭제가 발생했을 때, 절차를 찾고 있는 사이에 피해가 확대됩니다. 사내 노트 또는 리포지토리 내에 "1페이지 인시던트 초동 대응 메모"를 비치해 둡니다.

최소한 아래 3가지 시나리오에 대한 초동 대응을 작성합니다.

• API 키 유출: 즉시 무효화 → 이력에서 제거 → 신규 발행 → 영향 범위 파악
• 커맨드 오실행: 직전의 git 상태 확인 → reflog로부터 복구
• 의심스러운 MCP / hooks 탐지: 해당 파일을 격리 → 설정에서 삭제 → 재현 조건 기록

2-8. 로그 · 트랜스크립트(Transcript) 취급

CLI 에이전트의 대화 로그에는 인증 정보나 사내 코드가 포함될 수 있습니다. 공유나 전재 시에는 다음 사항을 철저히 합니다.

• 로그를 GitHub Issue 등에 붙여넣기 전에 키, 토큰, 사내 URL을 반드시 마스킹한다
• 제3자 LLM에 요약 요청을 위해 로그를 전달하기 전에 기밀이 혼입되지 않았는지 확인한다
• 로컬에 저장되는 대화 로그 디렉토리는 백업이나 인덱싱 대상에서 제외하는 것을 검토한다 (구체적인 경로이나 제외 커맨드는 이용 버전에 따라 다르므로 각자의 환경에서 확인)

설정 파일 자체도 Git으로 관리한다: 개인용 ~/.claude/settings.json은 리포지토리 외부에 두는 반면, 프로젝트의 .claude/settings.json이나 CLAUDE.md, .claude/hooks/ 하위의 스크립트는 리포지토리에 커밋하여 PR 리뷰를 통해 추적한다. "누가 언제 deny 규칙을 완화했는지", "어떤 hooks를 추가했는지"가 이력에 남게 되어, 조직적인 사고 방지와 설명 책임(Accountability) 모두에 효과적이다.

8개 항목의 운영 규칙이 갖춰졌으므로, 이것들을 "최소한 이것만은"으로 응축한 체크리스트를 제시합니다.

3. "최소한 이것만은" 30분 체크리스트

신규 PC · 신규 멤버 대응 시, 본 기사의 복사본으로 사용할 수 있는 15개 항목의 체크리스트입니다.

• API 키를 settings.json / dotfiles에 직접 작성하지 않았다 (환경 변수 또는 키체인(Keychain) 경유, 또는 apiKeyHelper 경유)
• GitHub PAT가 필요한 리포지토리 · 필요한 스코프(Scope)로만 발행되었다
• 글로벌 settings.json에서 --dangerously-skip-permissions에 상당하는 운용을 상용하지 않는다
• permissions.deny에 rm -rf /*, sudo *, curl * | sh, git push --force*가 포함되어 있다
• permissions.deny에 Read(~/.ssh/**), Read(~/.aws/**), Read(./.env) / Read(./.env.*)가 포함되어 있다
• permissions.deny

permissions.allow에 와일드카드(예: Bash(*) 등)가 포함되어 있지 않음 -
additionalDirectories가 최소한으로 설정되어 있음 (~, / 등 광범위한 지정 없이, 일시적인 추가는 --add-dir을 사용하여 세션 한정으로 수행) - 글로벌 / 프로젝트의 hooks를 모두 육안으로 확인했음 - 연결 중인 MCP 서버의 배포처를 모두 파악하고 있음 -
.gitignore에 .env*, *.pem, credentials*, .claude/local/이 포함되어 있음 - GitHub의 secret scanning / push protection이 ON 상태임 - 격리 환경(Docker / worktree / 공식 Sandboxing)의 운영 패턴이 하나 이상 있음 - 자동 push / --no-verify / git add .를 CLI에 맡기지 않는 운영 규칙이 있음 - API 키의 로테이션 주기와 절차, 인시던트 발생 시 초동 조치 절차가 결정되어 있음

4. 설정 스니펫 모음

마지막으로, 복사 및 붙여넣기로 사용할 수 있는 설정 예시 2가지를 제시합니다.

4-1. 권장 글로벌 settings.json (최소 기본값)

~/.claude/settings.json에 배치하는 것을 상정합니다. allow는 읽기 계열의 범용 명령어로만 제한했습니다.

{
"permissions": {
"deny": [
...

네트워크 취득이 필요할 때는 permissions.allow 측에 WebFetch(domain:docs.example.com)와 같이 도메인 단위로 허용을 추가합니다.

4-2. 격리 컨테이너 실행의 최소 예시 (Docker)

파괴적인 작업이나 미지의 MCP 테스트 시 사용하는 최소 구성의 Docker 실행 예시입니다. 호스트의 ~/.ssh나 ~/.aws는 마운트하지 않습니다.

docker run --rm -it \
-v "$PWD":/work -w /work \
-e ANTHROPIC_API_KEY \
...

키가 필요한 경우에는 read-only 마운트 및 전용 키로 한정하며, 범용 키는 절대로 마운트하지 마십시오.

요약

본 기사에서는 Claude Code를 실무 운영하기 위한 보안 설정을 5가지 위협 모델과 연계하여 정리했습니다.

• 초기 설정: API 키 보관 (환경 변수 / 키체인 / apiKeyHelper) → permissions.deny → allow 입도(granularity) → hooks / MCP 심사 → .gitignore → 격리 환경·Sandboxing의 10개 항목을 30분 내에 확립
• 운영 중: 권한 모드(Permission modes)의 구분 사용 → 프롬프트 인젝션(Prompt Injection) 대책 → push 시 수동 리뷰 → 정기 유지보수 → 인시던트 초동 조치의 8개 항목을 실행
• 판단 기준: "허용은 최소, 거부는 최대", "자동 push는 사람이 리뷰", "기밀은 외부로 전송하지 않는다"라는 3대 원칙을 CLAUDE.md에 명문화

참고로, 본 기사는 2026년 5월 시점의 공식 문서를 근거로 정리되었습니다. settings.json의 스키마, permission rule의 구문, hooks 이벤트에 관한 1차 정보는 Settings / Configure permissions / Permission modes / Hooks를 확인해 주시기 바랍니다.

Discussion