CLAUDE.md 완전 정복 - 보안 설계 완전 가이드

팀에서 AI 코딩 에이전트를 안전하게 운용하는 CLAUDE.md보안패턴

CLAUDE.md는 편리하지만, AI에게 강력한 툴 접근 권한을 부여하는 만큼 보안 설계가 중요합니다. 이 장에서는 안전하게 Claude Code를 운용하기 위한 보안 패턴과, 팀에서 효율적으로 사용하기 위한 운용 전략을 소개합니다.

보안의 기본 원칙

원칙 1. 최소 권한

Claude Code에 부여하는 권한은 필요 최소한으로 합니다. "혹시 필요할 수도 있으니까"라는 이유로 광범위한 권한을 주면, 예상치 못한 파괴적 조작이 발생할 수 있습니다.

## 금지 사항

IMPORTANT: 다음 조작은 어떠한 경우에도 절대 실행하지 않는다

- 프로덕션 환경에 직접 배포
- 프로덕션 데이터베이스에 쿼리 실행 (개발 DB만 허용)
- `.env` 파일의 내용을 로그·출력·채팅창에 포함하지 않는다
- API 키·패스워드·토큰을 코드에 하드코딩하지 않는다
- `rm -rf`를 실행하지 않는다
- `git push --force`를 실행하지 않는다
- `git push origin main`을 직접 실행하지 않는다 (PR 필수)

원칙 2. 비밀 정보 보호

CLAUDE.md에 API 키나 패스워드를 직접 작성해서는 안 됩니다. CLAUDE.md는 Git으로 관리되어 팀 전원이 볼 수 있고, 경우에 따라 GitHub에 공개될 수도 있습니다.

# ❌ 절대 해서는 안 되는 예
## 환경 설정
KAKAO_CLIENT_SECRET=abc123xyz...
TOSS_SECRET_KEY=sk_live_...

# ✅ 올바른 방법
## 환경 설정
- API 키는 `.env.local` 파일로 관리한다
- `.env.local`은 `.gitignore`에 추가하여 Git에 커밋하지 않는다
- 필요한 환경변수 목록과 발급 방법은 `.env.example`을 참조
- 시크릿 값이 필요하면 팀 내 시크릿 관리 시스템(1Password, AWS Secrets Manager 등)을 사용한다

원칙 3. 파괴적 조작의 제한

되돌리기 어려운 조작은 명시적으로 금지하거나, 반드시 확인 스텝을 거치도록 합니다.

## 데이터베이스 조작 규칙

| 조작 | 개발 DB | 프로덕션 DB |
|------|---------|------------|
| SELECT | ✅ 자유 실행 | ❌ MCP 접속 금지 |
| INSERT/UPDATE | ✅ 가능 | ❌ 금지 |
| DELETE | ⚠️ 논리 삭제만 (deleted_at 업데이트) | ❌ 금지 |
| DROP/TRUNCATE | ❌ 금지 (마이그레이션 파일로 관리) | ❌ 금지 |

Hooks에 의한 보안 강제

CLAUDE.md의 규칙은 컨텍스트가 길어지거나 복잡해지면 AI가 놓칠 가능성이 있습니다. 중요한 보안 규칙은 반드시 Hooks로 강제하세요. Hooks는 이벤트 발화 시 예외 없이 실행되기 때문입니다.