Claude Code Safety Guards 설정법

rm -rf 차단·API 키 유출·main 직접 push 방지 실무

by AI개발자

Mar 19. 2026

100시간 동안 무슨 일이 있었나

2026년 1~2월, 나는 Claude Code를 사람의 개입이 없는 상태로 100시간을 가동했다.

게임 개발, 기사 작성, 툴 개발, 마케팅등 다양한 태스크를 AI에 맡기고, 나는 거의 하루에 한 번 체크만 했다.

결과는 "예상보다 50배 많은 실패"였다.

실제로 일어난 일들

삭제 사고 (2회): rm -rf로 게임 프로젝트 파일이 사라졌다. 1번째는 백업으로 복원했고 2번째는 2시간 분량의 작업이 날아갔다.

비용 폭주 (1회): API를 호출하는 서브에이전트가 루프에 빠져, 1시간에 $8을 소비했다. 다음 날 아침에야 알아챘다.

무한 루프 (여러 차례): 같은 에러를 반복하는 Claude Code. '수정→확인→같은 에러'를 20번 반복했다.

프로덕션 push 실수 (1회): 리뷰 없이 main에 push했다. 다음 날, 다른 세션에서야 알아챘다.

컨텍스트 소실 (빈번): 컨텍스트 윈도우가 가득 차서, 이전 작업을 잊어버린 Claude Code가 같은 태스크를 처음부터 다시 시작했다.

모두 '설정의 문제'였다

나중에 복기해보니, 모든 실패는 공통된 원인을 가지고 있었다.

"기본적인 Claude Code 설정"은 자율 가동을 위해 만들어진 것이 아니다.

rm -rf를 차단하는 hook이 없었다.

에러를 감지하고 멈추는 구조가 없었다.

컨텍스트가 사라져도 작업을 이어받을 수 있는 상태 관리가 없었다.

이것들을 하나씩 추가해나간 것이 이 책의 내용이다.

claudecode-scan로 멀하지?

% npx claudecode-scan

이 명령어는 여러분들이 작업중인 프로젝트에서 터미널을 열고 실행해보자.

계산되어 출력된 점수의 의미와 점수를 올리는 방법이 이 책의 주요 내용이다.

이 도구를 만든 이유는 필자가 겪은 2개월간의 노가다와 같은 상황을 겪지 않도록 하기 위해 여러분이 사용중인 Claude Code를 기반으로 만든 프로젝트 내 ~/.claude/settings.json과 CLAUDE.md파일을 자동으로 스캔해서 독자의 현재 상태를 확인시켜준다.

점수를 확인하는 방법

6개의 디멘션

점수는 6개 카테고리에서 계산된다.

Safety Guards (제일 중요)

위험한 명령을 차단하는 hook이 있는가?

API 키가 CLAUDE.md에 직접 쓰여 있지 않은가?

main/master로의 직접 push가 방지되어 있는가?

에러가 존재하는 상태로 외부 API를 호출하지 않는가

이 부분이 낮은 점수인 경우: 파일 소실, API 비용 폭주, 프로덕션 사고

Code Quality

파일 편집 후에 구문 체크가 실행되는가?

에러 코드가 자동 감지되는가?

완료의 정의(DoD)가 있는가?

AI가 자신의 아웃풋을 검증하는가?

이 부분이 낮은 점수인 경우: 망가진 코드가 프로덕션에 들어가며, 에러를 알아채지 못함

Monitoring

컨텍스트 잔량이 모니터링되는가?

활동 로그가 기록되는가?

일일 요약가 생성되는가?

이 부분이 낮은 점수인 경우: 무슨 일이 일어나고 있는지 모르며, 독자가 알아챘을 때는 이미 늦었다.

Recovery

변경 전에 git 백업이 만들어지는가?

워치독이 아이들/프리즈를 감지하는가?

루프 감지 구조가 있는가?

이 부분이 낮은 점수인 경우: 실패로부터의 복구가 불가능하다.

Autonomy

태스크 큐에서 AI가 자율 실행할 수 있는가?

불필요한 질문이 억제되는가?

세션 재시작 후에도 작업을 계속할 수 있는가?

이 부분이 낮은 점수인 경우: 항상 인간이 필요하여 자율 가동이 불가능하다.

Coordination

의사결정 로그가 남는가?

여러 AI 인스턴스가 연계할 수 있는가?

교훈이 축적되는가?

이 부분이 낮은 점수인 경우: 같은 실패를 반복한다.

일반적인 초기 점수

처음 진단하면 많은 사람들이 50~70점이 나온다.

이것은 정상이다. Claude Code의 기본 설정은 '대화 세션' 용이며, '자율 가동' 용이 아니다.

필자도 초기 점수도 58점이었다.

Score: 58/100 — Getting There

Top fixes:

→ Add a PreToolUse hook that blocks destructive commands.

↳ https://github.com/gaebalai/claude-code-hooks/blob/main/hooks/branch-guard.sh

→ Add an error-tracker that prevents publishing when errors exist.

↳ https://github.com/gaebalai/claude-code-hooks/blob/main/hooks/error-gate.sh

대상 독자

Claude Code를 장시간 및 사람개입없이 돌리고 싶은 사람

스캔 점수가 60점 이하로 '무엇부터 고쳐야 하지?'라고 생각한 사람

AI에이전트의 안전한 운용에 관심있는 사람

이 책에서 얻을 수 있는 것들

20개의 체크항목 설명 - 왜 그 체크문항들이 필요한지, 어떤 상황에서 FAIL이 나오는지

10개의 hook스크립트 - 복사해서 바로 쓸 수 있는 훅

5개의 템플릿: CLAUDE.md, task-queue, mission.md 등

100시간의 경험담: 무엇이 실패하고 어떻게 고쳤는지에 대해

rm -rf 차단·API 키 유출·main 직접 push 방지 실전 가이드

Safety Guards가 낮으면, 다른 모든 설정이 의미 없다.

claudecode-scan을 실행해서 확인된 6개 평가 영역 중 Safety Guards는 유일하게 "낮으면 즉각적인 피해가 발생하는" 영역이다.

Code Quality나 Monitoring이 낮으면 서서히 문제가 누적된다. 하지만 Safety Guards가 비어 있으면, 한 번의 실행으로 파일이 사라지거나 제품이 망가진다.

이번 장에서는 4가지 체크를 먼저 끝내자.

체크1: 위험한 명령을 사전에 차단한다.

어떤 일이 벌어졌었나?

Claude Code가 "오래된 캐시 파일을 삭제해서 클린한 상태로 만들겠습니다"라고 설명한 뒤, 다음 명령을 실행했다.

rm -rf ./src/

왜 이런 일이 생기나?

Claude Code는 명령 실행 전에 "이 명령이 안전한가"를 스스로 판단하지 않는다. 지시의 의도를 이해하고 그에 맞는 명령을 생성하지만, 부작용을 사전에 검증하는 구조가 기본 설정에는 없다.

따라서 인간 측에서 위험한 명령을 실행하기 전에 가로채는 구조가 반드시 필요하다.

해결책: branch-guard.sh를 PreToolUse hook으로 등록

1단계. hook 스크립트를 배치한다.

mkdir -p ~/.claude/hooks

curl -o ~/.claude/hooks/branch-guard.sh \

https://raw.githubusercontent.com/gaebalai/claude-code-hooks/main/hooks/branch-guard.sh

chmod +x ~/.claude/hooks/branch-guard.sh

2단계. ~/.claude/settings.json에 hook을 등록한다.

{

"hooks": {

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [

{

"type": "command",

"command": "bash ~/.claude/hooks/branch-guard.sh"

}

]

}

]

}

3단계. hook이 차단하는 명령을 확인한다.

hook은 위 명령이 감지되면 exit 2를 반환해 Claude Code가 해당 툴 실행을 즉시 취소하도록 만든다.

※ 한국 개발 환경 참고: 일부 CI/CD 파이프라인(예: Jenkins, GitHub Actions 셀프호스티드 러너)에서는 hook 스크립트의 실행 권한(chmod +x) 설정이 누락되는 경우가 있다. 배포 후 반드시 bash -n ~/.claude/hooks/branch-guard.sh로 문법 오류가 없는지 확인하자.

체크2: API키를 CLAUDE.md파일에 절대 쓰지 않는다.

어떤 일이 벌어졌나?

CLAUDE.md 파일 안에 아래와 같이 API 키를 직접 기재했다.

API_KEY=sk-xxxx

GITHUB_TOKEN=ghp_xxxx

작업 효율을 위해 임시로 써둔 것이었다. 이후 화면을 공유하는 미팅 중 스크린샷에 해당 내용이 담겼고, 유출 직전까지 갔다.

왜 위험한가?

CLAUDE.md는 Claude Code가 항상 참조하는 공개 컨텍스트 파일이다. 즉:

실수로 git에 커밋되면 원격 저장소에 노출

스크린샷, 화면 공유, 로그에 그대로 노출

Claude Code가 외부 서비스 호출 시 키 값을 직접 출력할 수 있음

해결책: 전용 자격증명 파일로 분리

1단계. ~/.credentials 파일을 만든다.

# ~/.credentials

# 이 파일은 절대 git에 커밋하지 말 것

OPENAI_API_KEY=sk-xxxx

GITHUB_TOKEN=ghp_xxxx

ANTHROPIC_API_KEY=sk-ant-xxxx

SLACK_BOT_TOKEN=xoxb-xxxx

2단계. 파일 권한을 본인만 읽을 수 있도록 제한한다.

chmod 600 ~/.credentials

3단계. CLAUDE.md에는 참조 방법만 명시한다.

## 인증 정보

API 키 및 토큰은 `~/.credentials`에 저장되어 있습니다.

사용 시 `source ~/.credentials`로 환경 변수를 로드하세요.

이 파일에 API 키를 직접 기재하지 마세요.

4단계. .gitignore와 전역 git 무시 파일에 추가한다.

# 프로젝트 .gitignore에 추가

echo ".credentials" >> .gitignore

echo "*.env.local" >> .gitignore

# 전역 gitignore에도 추가 (모든 레포지토리에 적용)

echo ".credentials" >> ~/.gitignore_global

git config --global core.excludesfile ~/.gitignore_global

※ 한국 환경 특이사항: 카카오, 네이버, 토스 등 국내 서비스 API 키도 동일하게 관리해야 한다. 특히 카카오 REST API 키나 네이버 클라이언트 시크릿은 노출 시 악용 위험이 크므로 주의가 필요하다. 또한 AWS 한국 리전(ap-northeast-2)을 사용하는 경우 IAM 액세스 키도 반드시 이 방식으로 관리하자.

CLAUDE-autonomous.md 전체 템플릿 보기

체크3: main/master 브랜치 직접 push를 방지한다

어떤 일이 벌어졌나

Claude Code가 "변경 사항을 원격에 반영하겠습니다"라고 말한 뒤 아무 경고 없이 main 브랜치에 직접 push했다. 코드 리뷰 없이, PR 없이, 승인 없었다.

이 사실을 알게 된 건 다음 날 다른 팀원이 pull을 받고서였다.

해결책: hook + CLAUDE.md 이중 방어

branch-guard.sh는 이미 이 케이스를 커버한다.

체크 1에서 설정한 hook이 git push origin main을 자동 차단하므로 추가 설치는 필요 없다.

단, hook만으로는 CC가 우회 방법을 찾으려 시도할 수 있다. CLAUDE.md에 명시적인 규칙을 함께 기재해 CC의 판단 기준 자체를 바꿔야 한다.

## Git 운영 규칙

### 브랜치 전략

- **모든 작업은 새 브랜치에서 시작한다**: `git checkout -b feature/작업명`

- 브랜치 명명 규칙: `feature/`, `fix/`, `docs/`, `chore/` 접두사를 사용한다

- `main` 및 `master` 브랜치로의 직접 push는 어떤 상황에서도 금지

### PR 필수 절차

- 작업 완료 후 반드시 PR을 생성한다

- PR 설명에는 변경 이유, 변경 내용, 테스트 방법을 포함한다

- 승인 없이 merge하지 않는다

### 긴급 상황

- 핫픽스가 필요한 경우에도 `hotfix/설명` 브랜치를 생성 후 PR을 통해 처리한다

체크 4: 에러가 있는 상태에서 외부 API를 호출하지 않는다

어떤 일이 벌어졌나

TypeScript 컴파일 에러가 해결되지 않은 상태였다. Claude Code는 에러를 인지하고 수정을 시도했지만, 수정이 완료되었다고 잘못 판단한 뒤 npm publish를 실행했다.

결과: 구문 에러가 포함된 패키지가 npm에 공개되었다. 사용자들이 이 패키지를 설치하기 시작한 후에야 문제를 발견했다.

왜 이런 일이 생기나

CC는 에러를 인지하더라도, "이 에러가 해결되었는가"를 독립적으로 추적하는 메커니즘이 기본 설정에 없다. 에러를 수정했다고 스스로 판단하면, 다음 단계로 넘어간다.

해결책: error-gate.sh로 에러 상태 감지 후 외부 호출 차단

1단계. hook 스크립트를 배치한다.

curl -o ~/.claude/hooks/error-gate.sh \

https://raw.githubusercontent.com/yurukusa/claude-code-hooks/main/hooks/error-gate.sh

chmod +x ~/.claude/hooks/error-gate.sh

Step 2. PreToolUse hook에 추가 등록한다. (branch-guard.sh와 함께 배열에 추가)

{

"hooks": {

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [

{

"type": "command",

"command": "bash ~/.claude/hooks/branch-guard.sh"

{

"type": "command",

"command": "bash ~/.claude/hooks/error-gate.sh"

}

]

}

]

}

Step 3. hook이 차단하는 명령을 확인한다.

~/.claude/error-log.jsonl에 미해결(Unresolved) 에러가 하나라도 존재하는 경우, 아래 명령들이 차단된다.

※ 에러 로그 파일 관리: ~/.claude/error-log.jsonl은 CC가 자동으로 갱신한다. 에러가 해결되면 해당 항목이 Resolved로 표시된다. 로그가 쌓이면 jq 'select(.status == "unresolved")' ~/.claude/error-log.jsonl로 미해결 에러만 필터링해서 볼 수 있다.