안전장치와 자동화 베스트 프랙티스

안전장치와 자동화 베스트 프랙티스

자동화는 강력하지만 실수도 빠르게 일어납니다. 사람이 하루에 10개 파일을 실수로 수정한다면, 자동화는 10분에 1,000개 파일을 잘못 수정할 수 있습니다. 이 강에서는 Claude Code 자동화를 실제 프로덕션 환경에서 안전하게 운영하기 위한 안전장치들을 체계적으로 다룹니다. 이 내용을 팀과 공유하거나 CLAUDE.md에 포함시키면 자동화 사고를 예방하는 기준이 됩니다.

1. git이 최후의 안전망이다

Claude Code 자동화를 실행하기 전 항상 깨끗한 git 상태를 확인하세요. 언제든 이전 상태로 돌아갈 수 있어야 자동화를 믿고 맡길 수 있습니다.

#!/bin/bash
# 자동화 실행 전 필수 체크
echo "=== 사전 안전 체크 ==="

# 1. 미커밋 변경사항 없는지 확인
if ! git diff --quiet || ! git diff --staged --quiet; then
  echo "❌ 미커밋 변경사항 있음. 먼저 commit 또는 stash 하세요."
  exit 1
fi

# 2. 현재 브랜치 확인 (main 직접 수정 방지)
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "❌ main 브랜치 직접 수정 금지. feature 브랜치를 만드세요."
  exit 1
fi

# 3. 체크포인트 태그 생성
CHECKPOINT="checkpoint-$(date +%Y%m%d-%H%M%S)"
git tag "$CHECKPOINT"
echo "✅ 체크포인트 생성: $CHECKPOINT"
echo "   문제 발생 시: git reset --hard $CHECKPOINT"

echo "안전 체크 통과. 자동화 시작..."

2. 권한 최소화 — 도구 제한이 안전의 기본

# 위험 순서: Read < Edit < Bash(읽기) < Bash(쓰기) < Bash(네트워크) < --dangerouslySkipPermissions

# 분석 작업 — 읽기만
claude -p "코드 품질 분석" --allowedTools "Read,Glob,Grep"

# 수정 작업 — 편집만
claude -p "린트 오류 수정" --allowedTools "Read,Edit,Glob,Grep"

# 빌드 작업 — 지정된 명령만
claude -p "빌드 테스트" --allowedTools "Read,Edit,Bash(npm run build*),Bash(npx tsc*)"

# 절대 금지 (로컬 환경)
claude -p "..." --dangerouslySkipPermissions  # ← 격리 환경에서만

3. 인간 승인 체크포인트 (Human-in-the-Loop)

모든 자동화가 완전 자동이어야 하는 것은 아닙니다. 위험도가 높은 작업에는 사람의 확인을 의무화하세요.

#!/bin/bash
# 자동화 + 인간 승인 조합

echo "📋 1단계: 분석 (자동)"
claude -p "수정할 파일과 변경 내용 계획을 analysis.md로 저장" \
  --allowedTools "Read,Glob,Grep,Write"

echo ""
echo "=== 변경 계획 미리보기 ==="
cat analysis.md

echo ""
read -p "⚠️ 위 계획으로 실제 수정을 진행할까요? (yes/N): " confirm

if [ "$confirm" != "yes" ]; then
  echo "취소됨. analysis.md 확인 후 수동으로 진행하세요."
  exit 0
fi

echo "🔧 2단계: 실제 수정 (자동 + 승인됨)"
claude -p "analysis.md의 계획대로 파일 수정 실행" \
  --allowedTools "Read,Edit,Glob,Grep"

echo ""
echo "=== 변경사항 요약 ==="
git diff --stat

read -p "✅ 변경사항을 커밋할까요? (y/N): " commit_confirm
if [ "$commit_confirm" = "y" ]; then
  git add -A
  git commit -m "auto: Claude Code 자동 수정"
fi

4. 프로덕션 배포 절대 금지 목록

# settings.json — 자동화에서 절대 실행 불가 명령 차단
{
  "permissions": {
    "deny": [
      "Bash(git push --force*)",
      "Bash(git push origin main*)",
      "Bash(git push origin master*)",
      "Bash(rm -rf*)",
      "Bash(DROP TABLE*)",
      "Bash(DELETE FROM* WHERE*)",
      "Bash(npx vercel --prod*)",
      "Bash(npm publish*)",
      "Bash(curl -X DELETE*)"
    ]
  }
}

이 목록은 팀의 CLAUDE.md나 .claude/settings.json에 반드시 포함시키고, 새 팀원 온보딩 시 설명하세요. "실수로 프로덕션을 배포하는 것"과 "실수로 DB 테이블을 삭제하는 것"은 모두 코드 한 줄로 막을 수 있습니다.

5. 롤백 계획 — 빠른 복구가 진짜 안전

#!/bin/bash
# 롤백 스크립트 — 자동화 실패 시 즉시 실행

CHECKPOINT=$1  # git tag 이름

if [ -z "$CHECKPOINT" ]; then
  echo "사용법: ./rollback.sh checkpoint-20260617-143022"
  echo ""
  echo "사용 가능한 체크포인트:"
  git tag | grep "checkpoint-" | tail -10
  exit 1
fi

echo "⚠️ 롤백 시작: $CHECKPOINT"
echo "현재 상태 백업..."
git stash push -m "rollback-backup-$(date +%Y%m%d-%H%M%S)"

echo "체크포인트로 복원..."
git reset --hard "$CHECKPOINT"

echo "✅ 롤백 완료"
echo "복원된 상태:"
git log --oneline -3

6. 자동화 범위 명확히 정하기

• 자동화 OK: 타입 오류 수정, 린트 오류 수정, 번역 키 추가, 테스트 생성, 코드 분석, 커밋 메시지 초안, 문서 생성
• 사람 승인 필요: DB 스키마 변경, 의존성 업그레이드, API 계약 변경, 보안 관련 코드, 비즈니스 로직 변경
• 자동화 절대 불가: 프로덕션 배포, DB 데이터 삭제/수정, 외부 결제 API 호출, 이메일/SMS 발송, 접근 권한 변경

7. 팀 자동화 원칙 문서화 (CLAUDE.md 예시)

## 자동화 안전 원칙

### 자동 허용
- 타입 오류, 린트 오류 자동 수정
- 번역 키 누락 추가 (messages/*.json)
- 테스트 파일 생성
- 커밋 메시지 초안 생성

### 반드시 사람 확인
- supabase/migrations/ 파일 생성/수정
- package.json 의존성 변경
- 인증/권한 관련 코드
- 환경변수 추가/변경

### 절대 금지 (자동화로)
- git push origin main (hotfix 제외)
- DB 데이터 직접 수정/삭제
- .env.local 파일 수정
- Vercel --prod 배포

자동화의 성숙도는 "얼마나 많은 것을 자동화했는가"가 아니라 "언제 멈춰야 하는지 아는가"로 측정됩니다. 경험 많은 자동화 팀은 더 많은 것을 자동화하는 것이 아니라 더 명확한 경계를 갖고 있습니다. 오늘 이 과정에서 배운 권한 설정, 체크포인트, 인간 승인 패턴이 그 경계를 만드는 도구들입니다.

핵심 정리

• 자동화 전 git 체크포인트 태그 생성 필수 — 문제 발생 시 git reset --hard [태그]로 즉시 복원 가능
• settings.json deny 목록으로 프로덕션 배포·DB 삭제·강제 push 차단 — 실수 한 번으로 팀 전체를 보호
• 자동화 범위 문서화(CLAUDE.md) + 인간 승인 체크포인트 — "자동화 OK / 승인 필요 / 절대 불가" 세 범주로 팀 기준 공유

관련 검색어  ·  클로드 코드  ·  Claude Code  ·  자동화 안전장치  ·  최소 권한 원칙  ·  롤백 전략  ·  자동화 베스트 프랙티스  ·  AI 자동화 보안