AI 가드레일 설계 가이드, AI가 선을 넘지 않게 하는 법

🐴 하네스 엔지니어링 시리즈 · 2편 / 6편

허용 범위 설계, 시스템 프롬프트 제약, CLAUDE.md 작성까지. AI 에이전트에게 "하지 말아야 할 것"을 가르치는 기술을 배웁니다.

⏱ 읽는 시간 약 10분  ·  🎯 난이도: 기초

📋 목차

1. 가드레일이란 무엇인가
2. 물리적 가드레일 vs 논리적 가드레일
3. 허용/차단 범위 설계 패턴
4. 실전: CLAUDE.md로 행동 규칙 작성하기
5. 보안 관점의 가드레일
6. 초보가 자주 하는 실수

👈

이전 편을 아직 못 읽으셨나요? 1편에서 하네스 엔지니어링의 전체 개념과 4대 구성요소를 먼저 소개했습니다. 처음이라면 1편부터 읽는 것을 추천드립니다.

🛡️ 가드레일이란 무엇인가

가드레일(Guardrail)은 AI 에이전트가 허용된 범위 안에서만 행동하도록 설계된 제약 시스템입니다. 고속도로 갓길에 설치된 방호벽처럼, AI가 절벽 밖으로 떨어지지 않도록 경계를 설정하는 것입니다.

가드레일이 없는 AI 에이전트는 아무리 좋은 의도로 설계해도 예측 불가능한 행동을 합니다. 반면 가드레일이 잘 설계된 AI는 명시적으로 허용된 일만 수행하기 때문에 신뢰할 수 있습니다.

💡

핵심 원칙: AI는 "착하게" 만드는 것이 아니라 "구조적으로 잘못된 행동을 할 수 없게" 만드는 것입니다. 의도가 아닌 설계로 안전을 확보합니다.

🔍 물리적 가드레일 vs 논리적 가드레일

🏗️ 물리적 가드레일

• 파일시스템 권한 제한
• 네트워크 접근 차단
• 읽기 전용 DB 연결

✓ AI가 아무리 시도해도 기술적으로 불가능. 가장 강력한 방어.

📝 논리적 가드레일

• 시스템 프롬프트 제약
• CLAUDE.md 규칙 선언
• 행동 지침 작성

✓ 유연하게 설정 가능. 물리적 가드레일과 병행 사용 권장.

⚡ 허용/차단 범위 설계 패턴

가드레일 설계의 핵심은 Allowlist(허용 목록)와 Denylist(차단 목록)를 명확히 정의하는 것입니다.

❌ Denylist만 쓰는 나쁜 설계

• ".env 파일은 읽지 마세요"
• "프로덕션 DB는 건드리지 마세요"
• "API 키는 노출하지 마세요"

❗ 막지 않은 것은 모두 허용됩니다. 구멍이 생깁니다.

✅ Allowlist 중심의 좋은 설계

• "src/ 폴더만 수정 가능"
• "읽기: docs/, tests/ 허용"
• "외부 API 호출: 불가"

✓ 명시적으로 허용된 것만 가능. 나머지는 자동 차단.

📄 실전: CLAUDE.md로 행동 규칙 작성하기

Claude Code는 프로젝트 루트에 CLAUDE.md 파일을 두면 AI가 항상 이 파일을 먼저 읽고 행동합니다. 프로젝트별 가드레일을 논리적으로 설정하는 가장 빠른 방법입니다.

📄 CLAUDE.md

# 프로젝트 행동 규칙 (하네스 가드레일)

## ✅ 허용 범위
- src/ 폴더 내 파일 읽기·수정
- tests/ 폴더 읽기·수정
- npm test, npm run lint 실행

## 🚫 절대 금지
- .env 파일 읽기·수정·출력 금지
- /secrets, *.key 파일 접근 금지
- 외부 네트워크 요청 금지 (curl, fetch 등)
- git push, 배포 명령어 금지

## ⚠️ 반드시 확인 후 실행
- 파일 삭제 전 항상 사용자에게 확인 요청
- 10줄 이상 변경 시 요약 후 승인 대기

## 📋 코딩 스타일
- TypeScript strict mode 준수
- 함수 단위 Jest 테스트 필수 작성

🔐 보안 관점의 가드레일

⚠️ 취약한 설정 vs 안전한 설정 // ❌ 취약: AI가 전체 파일시스템 접근 가능
// 사용자: "환경 변수 확인해줘"
// AI: cat .env → DB_PASSWORD=prod123 출력됨 💀

// ✅ 안전: 접근 범위를 명시적으로 제한
allowed_read: ["src/", "tests/", "docs/"]
denied_read: [".env", "*.pem", "*.key", "/secrets/"]

✅

보안 가드레일 체크리스트
□ 민감 파일(.env, *.key) 접근 차단 설정
□ 프로덕션 환경 접근 물리적으로 분리
□ 외부 네트워크 요청 허용 범위 명시
□ rm, sudo 등 위험 명령어 차단
□ AI 행동 로깅으로 추적 가능하게 설정

🚧 초보가 자주 하는 실수

❌ 실수 1: 너무 느슨한 가드레일

• "알아서 잘 해줘"
• 아무 제약 없이 AI 사용
• Denylist에만 의존

❌ 실수 2: 너무 엄격한 가드레일

• 모든 파일 접근 차단
• 매번 확인 요청 설정
• AI가 아무것도 못 함

🎯

정답: Allowlist 중심으로 최소 권한 원칙(Principle of Least Privilege)을 적용하되, 업무에 필요한 범위는 충분히 열어두세요.

 

📌

1. 가드레일은 물리적 + 논리적 두 레이어를 병행합니다.
2. Allowlist 중심으로 설계해야 구멍이 생기지 않습니다.
3. CLAUDE.md로 프로젝트별 행동 규칙을 선언적으로 관리하세요.
4. 민감 정보 접근은 물리적으로 차단하는 것이 가장 확실합니다.

 

📚 하네스 엔지니어링 시리즈 전체보기

• 완료 1편 — AI 에이전트에게 고삐가 필요한 이유
• NOW 2편 — 가드레일: AI가 선을 넘지 않게 하는 법
• 예정 3편 — 도구(Tools) 설계: AI에게 올바른 무기를 쥐여주기
• 예정 4편 — 메모리와 컨텍스트: AI가 기억하게 만드는 법
• 예정 5편 — 피드백 루프: AI 결과물을 검증하고 수정하는 시스템
• 예정 6편 — 하네스 풀 스택: 실전 AI 에이전트 파이프라인 설계

3편에서 계속됩니다 👉

AI에게 어떤 도구를 줄지 설계하는 법,
Tool Use & MCP 연동의 모든 것을 다음 편에서 다룹니다.