Claude Code 권한 설정: .env, Git, 위험한 명령을 보호하는 법

Claude Code를 설정할 때 개발자는 흔히 잘못된 선택지 앞에 섭니다. 사소한 읽기 명령마다 계속 승인을 받거나, 전체 우회 옵션인 --dangerously-skip-permissions를 켜서 .env 유출, 의도치 않은 git push --force, 프로젝트 환경 손상 위험을 감수하는 선택입니다.

어느 쪽도 효과적이지 않습니다. 안전한 운영은 최소 권한 원칙에서 출발합니다. 읽기 접근, 쓰기 권한, 셸 실행, 버전 관리를 분명히 분리해야 합니다.

---

1. 권한 맵: 읽기에서 외부 영향까지

파일과 명령을 다음 네 가지 접근 단계로 나눕니다.

단계	작업	기본 정책	예시
1. 코드 검사	프로젝트 파일 읽기	허용(승인 불필요)	cat, grep, src/ 소스 보기
2. 비밀과 설정	.env, 키, 토큰 접근	엄격히 금지	.env*, id_rsa, *.pem, credentials.json
3. 파일 편집	코드 작성 및 수정	워크스페이스 범위에서 허용	write_to_file, replace_file_content
4. 위험한 셸 및 Git	패키지 관리자, 파괴적 작업	수동 승인 필수	rm -rf, git push --force, npm publish, DROP TABLE

---

2. .env 파일과 프로젝트 비밀을 격리하기

Transport Layer Security(TLS)는 네트워크를 지나는 API 트래픽을 암호화합니다. 하지만 기밀 자격 증명이 모델의 컨텍스트 창, 오류 로그, handoff 요약에 들어가는 것까지 막지는 못합니다.

Claude Code가 비공개 자격 증명을 읽지 않게 하려면 다음을 적용하세요.

1. 비밀을 포함하는 모든 환경 파일을 .gitignore에 추가합니다.
2. 더미 값만 담긴 깔끔한 .env.example 템플릿을 제공합니다. 에이전트는 실행 값 없이 변수 이름을 이해할 수 있습니다.
3. CLAUDE.md 또는 AGENTS.md에 엄격한 경계 규칙을 적습니다.

## 비밀 보호 규칙

- `.env`, `.env.local`, 개인 키 파일의 내용을 검사, 출력 또는 전달하지 않는다.
- 필요한 설정 키를 확인할 때는 `.env.example`을 검사한다.

[!IMPORTANT] API 키 관리: Claude Code API 키는 로컬 환경에서 설정하며 저장소 파일에 커밋해서는 안 됩니다. 안전한 연결 절차는 BetterToken Claude Code 문서를 따르세요.

.gitignore는 실수로 commit하는 일을 막지만 에이전트가 file을 읽는 것까지 차단하지 않습니다. CLAUDE.md나 AGENTS.md의 지침은 의도를 표현할 뿐 기술적 경계가 아닙니다. 현재 permission rule과 OS-level sandbox를 함께 적용하세요.

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": [
        "./**/.env",
        "./**/.env.*",
        "./secrets"
      ]
    }
  }
}

Read deny는 built-in file tools와 인식된 file command에 적용됩니다. 임의의 Python 또는 Node subprocess는 다른 방식으로 읽을 수 있으므로 OS 경계에는 sandbox가 필요합니다. failIfUnavailable과 allowUnsandboxedCommands는 격리할 수 없을 때 비격리 fallback 대신 실행을 중단합니다. Native Windows에서는 sandbox를 지원하지 않으므로 WSL2나 container를 사용하세요. Managed environment에서는 project settings가 policy를 약화하지 못하도록 관리자가 고정해야 합니다.

---

3. Git 및 명령 제어를 위한 우선 체크리스트

Claude Code가 작업을 수행할 때는 먼저 다음 평가 순서를 적용합니다.

에이전트가 명령을 제안함
  │
  ├─> 파괴적인 패턴(rm -rf, drop, force push)이 포함되는가?
  │     └─> 예: 거부하거나 개발자 감독 아래 수동 실행
  │
  └─> .git 내부, .env 파일 또는 외부 네트워크를 건드리는가?
        │
        ├─> 예: 명시적 근거를 요구하고 명령 범위를 제한
        │
        └─> 아니오: 대상 브랜치에서 실행 승인

단계별 가드레일

1. 1단계: Git 변경을 통제합니다. 수동 git diff --check와 테스트 실행 없이 main으로 자동 직접 push를 허용하지 마세요.
2. 2단계: 패키지 설치를 격리합니다. npm install <package> 같은 명령이나 원격 curl 스크립트는 신뢰할 수 없는 의존성과 공급망 위험을 막기 위해 수동으로 검토해야 합니다.
3. 3단계: 디렉터리 범위를 제한합니다. 에이전트 워크스페이스를 특정 기능 폴더 또는 전용 Git worktree로 제한하세요.

---

4. Production access는 별도 경계입니다

Local permission은 production IAM, network policy, system approval을 대신하지 않습니다. 기본은 access 없음입니다. 진단에 꼭 필요하다면 resource-scoped short-lived read-only role을 발급합니다. Write에는 command, target, time window, validation, observer, rollback을 명시한 별도 approval이 필요합니다. 결과가 불명확하면 retry 전에 current state를 읽으세요. Audit log에는 identity, resource, action, result만 기록하고 secret value나 sensitive payload는 제외하며 temporary credential은 이후 revoke합니다. Credential을 HANDOFF.md에 복사하지 마세요.

5. 테스트 워크스페이스에서 권한 검증하기

Claude Code에 중요한 저장소 접근 권한을 주기 전에 샌드박스에서 보안 경계를 검증합니다.

1. 일회용 테스트 브랜치를 만듭니다: git checkout -b test/permission-check.
2. 가짜 테스트 비밀이 들어 있는 더미 .env 파일을 추가합니다.
3. 에이전트에게 인증 모듈을 리팩터링하도록 요청합니다.
4. 다음을 확인합니다.
   • 탐색 중 에이전트가 더미 .env 파일을 읽지 않았는지
   • 비밀 토큰이 오류 로그, 주석, git diff에 유출되지 않았는지
   • 승인되지 않은 파일에 접근하지 않고 단위 테스트가 실행되는지
5. 경계가 검증되면 테스트 브랜치를 정리합니다.

이처럼 권한 경계를 명확히 하면 자격 증명을 보호하면서도 빠른 자율 실행을 유지할 수 있습니다.