AI 코딩

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

Claude Code 권한을 안전하게 제한하는 실무 가이드입니다. 비밀을 격리하고 Git 및 셸 명령을 통제하며, 프로덕션 저장소에 접근하기 전에 보안 경계를 테스트합니다.

BetterToken

편집팀

2026년 8월 20일3 분 분량

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가 비공개 자격 증명을 읽지 않게 하려면 다음을 적용하세요.

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

비밀 보호 규칙

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



> [!IMPORTANT]
> **API 키 관리**: Claude Code API 키는 로컬 환경에서 설정하며 저장소 파일에 커밋해서는 안 됩니다. 안전한 연결 절차는 [BetterToken Claude Code 문서](https://docs.bettertoken.ai/ai-tools/claude-code)를 따르세요.

---

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

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


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

단계별 가드레일

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

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

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

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

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

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.