오늘만 무료

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

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

2시간전 brunch_membership's

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는 이벤트 발화 시 예외 없이 실행되기 때문입니다.

기밀 파일 접근 방지

{
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Edit|Write",
"command": "bash -c 'FILE=\"$TOOL_INPUT_FILE_PATH\"; BLOCKED_PATTERNS=(\"\\.env\" \"\\.env\\.local\" \"\\.env\\.production\" \"\\.pem\" \"\\.key\" \"credentials\\.json\" \"keystore\\.\"); for p in \"${BLOCKED_PATTERNS[@]}\"; do if echo \"$FILE\" | grep -qE \"$p\"; then echo \"BLOCKED: 기밀 파일에 대한 접근은 금지되어 있습니다: $FILE\" >&2; exit 1; fi; done'"
}
]
}
}

위험한 커맨드 방지

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "bash -c 'CMD=\"$TOOL_INPUT\"; for PATTERN in \"rm -rf\" \"DROP TABLE\" \"DROP DATABASE\" \"TRUNCATE\" \"git push --force\" \"git push origin main\" \"--no-verify\" \"sudo rm\"; do if echo \"$CMD\" | grep -qi \"$PATTERN\"; then echo \"BLOCKED: 위험한 커맨드가 감지되었습니다: $PATTERN\" >&2; exit 1; fi; done'"
}
]
}
}

개인정보 로그 출력 방지

국내 개인정보보호법 준수를 위해, 개인정보가 포함된 출력을 감지하는 Hook입니다.

{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"command": "bash -c 'OUTPUT=\"$TOOL_OUTPUT\"; if echo \"$OUTPUT\" | grep -qE \"[0-9]{3}-[0-9]{4}-[0-9]{4}|[0-9]{6}-[1-4][0-9]{6}\"; then echo \"WARNING: 출력에 전화번호 또는 주민등록번호 형식의 데이터가 포함되어 있습니다. 개인정보 로그 출력 규칙을 확인하세요.\" >&2; fi'"
}
]
}
}

팀 운용 패턴

패턴 1: 공유 CLAUDE.md + 개인 설정 분리

팀이 통일해야 할 규칙은 프로젝트 CLAUDE.md에, 개인 취향은 ~/.claude/CLAUDE.md에 나눠서 관리합니다.

프로젝트 CLAUDE.md (Git 관리 — 팀 공유)
├── 기술 스택과 버전
├── 코딩 규약
├── 워크플로우 커맨드
├── 금지 사항 (보안 규칙 포함)
└── PR 규약

개인 ~/.claude/CLAUDE.md (각자 관리 — Git 제외)
├── 응답 언어 설정 (한국어 우선)
├── 출력 스타일 취향 (간결/상세)
├── 코드 설명 방식 선호
└── 개인 단축 Skills 참조

이 분리 구조의 장점은, 새 팀원이 클론 후 바로 동일한 Claude Code 환경을 사용할 수 있다는 점입니다. 개인 설정이 팀 컨벤션에 영향을 주지 않습니다.

패턴 2: 리뷰 기준 CLAUDE.md

코드 리뷰 기준을 CLAUDE.md에 정의해 두면, Claude Code가 일관된 관점으로 코드를 리뷰해 줍니다.

## 코드 리뷰 기준

PR을 리뷰할 때 다음 항목을 확인한다:

### � 필수 체크 (문제가 있으면 반드시 수정 요청)
- [ ] **타입 안전성**: `any`, `as`, `!`(non-null assertion) 사용이 없는지
- [ ] **에러 핸들링**: 외부 API 호출·DB 조작에 try-catch가 있는지
- [ ] **테스트**: 추가·변경한 기능에 단위 테스트가 있는지
- [ ] **보안**: 사용자 입력의 유효성 검사(Zod 등)가 있는지
- [ ] **민감정보**: API 키·개인정보가 하드코딩·로그 출력되지 않는지

### � 권장 체크 (제안으로 코멘트)
- [ ] **퍼포먼스**: N+1 쿼리가 없는지
- [ ] **가독성**: 함수가 50행 이내인지, 책임이 분리되어 있는지
- [ ] **명명**: 변수명·함수명이 의도를 명확히 표현하는지
- [ ] **국내 특화**: 결제 금액이 서버 사이드에서만 계산되는지

패턴 3: 신규 멤버 온보딩

새로운 팀원이 Claude Code를 첫날부터 올바르게 사용할 수 있도록, 셋업 가이드와 주의 사항을 CLAUDE.md에 포함합니다.

## 개발 환경 셋업 (신규 멤버)

다음 절차로 개발 환경을 구축한다:

1. 레포지토리를 클론한다
2. `pnpm install`로 의존 관계를 설치한다
3. `.env.example`을 복사하여 `.env.local`을 작성하고,
팀 시크릿 관리 시스템(1Password)에서 실제 값을 설정한다
4. `pnpm prisma migrate dev`로 개발 DB를 셋업한다
5. `pnpm dev`로 개발 서버를 시작한다
6. `http://localhost:3000`에 접속하여 동작을 확인한다

### Claude Code 사용 시 주의 사항 (신규 멤버)
- 프로덕션 DB에 접속하는 MCP 설정은 절대 하지 않는다
- 실제 카드 번호·결제 정보로 테스트하지 않는다 (토스페이먼츠 테스트 모드 사용)
- 모르는 것이 생기면 `#dev-help` 채널에 질문한다

권한 레벨 설계

팀 규모가 커지면, 멤버의 역할에 따라 Claude Code의 권한을 다르게 설계할 수 있습니다.

## 권한 레벨

### � read-only (인턴·외부 협력사)
- 코드 열람·검색만 가능
- 파일 변경은 직접 편집하지 않고 "제안"으로 출력
- 테스트 실행 가능 (읽기 전용 개발 DB)
- 금지: 파일 쓰기, DB INSERT/UPDATE, 커밋

### � developer (일반 개발자)
- 코드 열람·편집 가능
- 개발 DB에 대한 SELECT/INSERT/UPDATE 가능
- 테스트·빌드 실행 가능
- 금지: main 브랜치 직접 커밋, 프로덕션 DB 접근, 배포 스크립트 실행

### � admin (테크 리드·인프라 담당)
- 전체 조작 가능
- 배포 스크립트 실행 가능
- CLAUDE.md·settings.json 변경 가능
- 단, 프로덕션 DB의 파괴적 조작은 관리자도 금지 (별도 안전 절차 필요)

CLAUDE.md 유지보수

정기 검토 (월 1회)

CLAUDE.md는 코드베이스와 함께 살아있는 문서입니다. 방치하면 현실과 괴리된 규칙이 쌓여 오히려 AI의 판단을 방해하게 됩니다.

## CLAUDE.md 월간 검토 체크리스트

- [ ] 기술 스택 버전이 실제와 일치하는가 (Next.js, TypeScript 등)
- [ ] 사용하지 않게 된 커맨드·라이브러리 기술이 없는가
- [ ] 모순되는 규칙이 없는가 (특히 최근에 추가한 규칙)
- [ ] 새롭게 추가해야 할 규칙이 없는가 (코드 리뷰에서 반복 지적된 사항)
- [ ] 행수가 적절한가 (규모별 권장치: Small 50행, Medium 150행, Large 400행)
- [ ] 개인정보·보안 관련 규칙이 최신 법령 기준에 맞는가

CLAUDE.md 변경은 PR로

CLAUDE.md의 변경은 팀 전원의 AI 출력에 즉시 영향을 줍니다. 코드 변경과 동일한 리뷰 프로세스를 적용합니다.

## CLAUDE.md 변경 규칙

- CLAUDE.md 변경은 반드시 PR을 통한다 (직접 main에 push 금지)
- 2인 이상의 리뷰를 필수로 한다
- PR 본문에 "왜 이 규칙을 추가·변경·삭제하는가"를 기술한다
- 변경 후 1주일은 AI 출력에 의도하지 않은 영향이 없는지 모니터링한다