CLAUDE.md 설계 완전 가이드 — 권한 레벨별 템플릿으로 「AI가 멋대로 사고 치는 것」을 방지하기

Claude Code를 도입하고 가장 먼저 해야 할 일은 코드를 작성하게 하는 것이 아니라, 「해도 되는 일/하면 안 되는 일」을 정의하는 CLAUDE.md를 작성하는 것입니다.

이 글을 읽으면 다음 내용을 알 수 있습니다.

• CLAUDE.md의 역할과 AGENTS.md와의 명확한 차이
• 개인 개발·팀 개발·운영 환경의 3가지 권한 레벨별 템플릿
• auto 모드와 확인 모드의 실전적인 구분 사용법
• .claude/settings.json의 리스크 레벨별 설정
• CLAUDE.md가 없어서 실제로 사고가 날 뻔했던 경험담

「AI가 멋대로 사고 치는 것」을 방지하는 메커니즘은 코드 품질의 문제가 아니라 설계의 문제입니다. 차근차근 설명하겠습니다.

항목	버전 등
Claude Code	최신 버전 (2025년 7월 기준)
...

CLAUDE.md는 Claude Code가 태스크를 실행할 때 자동으로 읽어들이는 지시서입니다. 프로젝트 루트(Project Root)에 배치하면, Claude는 이 파일의 내용을 시스템 프롬프트(System Prompt)의 일부로 해석합니다.

구체적으로 다음과 같은 내용을 정의할 수 있습니다.

• 프로젝트 개요 및 기술 스택 (Tech Stack)
• 코딩 규약 및 명명 규칙 (Naming Convention)
• 해도 되는 일 (허가 작업)
• 하면 안 되는 일 (금지 작업)
• 워크플로우(Workflow) 절차

혼동하기 쉬운 AGENTS.md와의 역할을 정리합니다.

비교 항목	CLAUDE.md	AGENTS.md
대상 도구	Claude Code 전용	여러 AI 에이전트 공통
...	~/, 프로젝트 루트, 서브 디렉토리	프로젝트 루트

포인트: CLAUDE.md는 「Claude Code를 위한 업무 명령서」, AGENTS.md는 「어떤 AI라도 읽을 수 있는 자기소개 카드」라고 이해하면 정리하기 쉽습니다.

CLAUDE.md는 3가지 레벨로 배치할 수 있으며, 모든 내용이 병합(Merge)되어 읽힙니다.

• 사용자 글로벌(~/.claude/CLAUDE.md) — 모든 프로젝트 공통 규칙
• 프로젝트 루트(./CLAUDE.md) — 해당 리포지토리 고유 규칙
• 서브 디렉토리(./src/CLAUDE.md) — 특정 디렉토리 전용 규칙

모순되는 지시가 있을 경우, 더 구체적인(깊은) 레벨이 우선됩니다.

Low Risk (개인 개발)
속도 중시. 자신만 사용하는 프로젝트로, 다소 망가져도 즉시 고칠 수 있다는 전제입니다.

# CLAUDE.md — 개인 개발 프로젝트
## 프로젝트 개요
- 개인 블로그 Next.js 앱
...

Medium Risk (팀 개발)
팀원의 코드에 영향을 미치므로, 파괴적인 작업에는 확인 과정을 거칩니다.

# CLAUDE.md — 팀 개발 프로젝트
## 프로젝트 개요
- SaaS 관리 화면 (React + Go)
...

High Risk (본방 운영)
운영 환경에 가까운 코드를 다루는 경우. 원칙적으로 모두 확인 모드입니다.

# CLAUDE.md — 본방 운영 프로젝트
## ⚠️ 중요: 이 프로젝트는 운영 환경에 영향을 미칩니다
## 프로젝트 개요
...

Claude Code에는 작업을 자동 실행하는 auto 모드와 사용자에게 확인을 요청하는 확인 모드가 있습니다. 어느 것을 사용할지는 「작업의 리스크 레벨」로 판단합니다.

allowedTools는 .claude/settings.json에서 정의하며, 확인 없이 자동 실행을 허가할 도구를 지정합니다.

{
  "permissions": {
    "allowedTools": [
      ...
    ]
  }
}

중요: allowedTools에 추가할수록 Claude Code의 자율성이 높아지지만, 사고 리스크도 비례해서 높아집니다. 망설여진다면 추가하지 않는 것이 안전합니다.

.claude/settings.json은 CLAUDE.md와 나란히 중요한 설정 파일입니다. CLAUDE.md가 「자연어 지시서」인 반면, settings.json은 「기계적인 권한 제어」를 담당합니다.

Low Risk (개인 개발)

{
  "permissions": {
    "allowedTools": [
      ...
    ]
  }
}

Medium Risk (팀 개발)

{
  "permissions": {
    "allowedTools": [
      ...
    ]
  }
}

High Risk (본방 운영)

{
"permissions": {
"allowedTools": [
...

settings.json만으로는 "왜 그 조작이 금지되어 있는지"를 Claude에게 전달할 수 없습니다. CLAUDE.md에서 이유를 자연어로 설명함으로써, Claude는 금지된 조작의 **의도 (Intent)**를 이해하고, 유사한 위험한 조작도 자발적으로 피하게 됩니다.

어느 팀 개발 프로젝트에서 CLAUDE.md를 정비하기 전의 일입니다.

상황:

Claude Code에 "사용자 테이블에 프로필 이미지 컬럼을 추가해줘"라고 지시했습니다. Claude는 다음을 순서대로 실행했습니다.

• 마이그레이션 (Migration) 파일 생성 ✅
• 모델 (Model) 파일 업데이트 ✅

🚨 npx prisma migrate deploy를 실행하려고 시도함

다행히 확인 프롬프트가 표시되어 멈출 수 있었지만, 만약 allowedTools에 Bash(npx *)를 와일드카드로 허용했다면, 운영(Production) 연결용 .env가 로드된 상태로 마이그레이션이 실행될 뻔했습니다.

이 사고 이후, 다음과 같은 내용을 CLAUDE.md에 추가했습니다.

## 데이터베이스 조작 규칙
- 마이그레이션 파일의 "생성"은 허용한다
- 마이그레이션의 "실행" (migrate deploy / migrate dev)은 금지한다
...

나아가 settings.json에도 추가했습니다.

{
"permissions": {
"denyTools": [
...

이중 방어가 핵심입니다. settings.json에서 기계적으로 차단하고, CLAUDE.md에서 이유를 설명합니다. 이렇게 함으로써 Claude는 "prisma migrate는 사용할 수 없으니, 대신 마이그레이션 파일을 생성하고 사용자에게 실행을 안내하자"라는 올바른 행동을 선택하게 되었습니다.

다른 상황에서는 리베이스 (Rebase) 후에 "푸시해줘"라고 가볍게 부탁했더니, git push --force origin main을 제안한 적도 있습니다. main 브랜치에 대한 --force는 치명적입니다.

## Git 조작 규칙
- git push는 일절 자동 실행하지 말 것
- force push는 절대로 제안하지 말 것
...

이를 작성한 이후부터 Claude는 반드시 "push 준비가 되었습니다. 다음 명령어를 수동으로 실행해 주세요"라고 안내하게 되었습니다.

Anthropic의 공식 문서에 CLAUDE.md의 베스트 프랙티스 (Best Practices)가 기재되어 있습니다.

먼저 시작한다면, 이 최소 구성부터 시작하세요.

# CLAUDE.md
## 프로젝트 개요
(1~2줄로 프로젝트 설명)
...

CLAUDE.md는 처음부터 완벽하게 만들 필요가 없습니다. 운영하면서 다음과 같은 사이클로 키워나가세요.

• 최소 구성으로 시작한다

• Claude가 위험한 조작을 하면, 그 규칙을 추가한다

• 팀원으로부터 "Claude가 이걸 해서 곤란했다"라는 보고가 있으면 추가한다

• 한 달에 한 번, 불필요해진 규칙을 정리한다

• **CLAUDE.md는 "AI를 위한 업무 명령서"**이며, Claude Code 도입 시 가장 먼저 작성해야 할 파일입니다. settings.json과의 이중 방어로 사고를 예방합니다.

• 권한 레벨은 3단계(개인/팀/운영)로 설계합니다. 리스크가 높아질수록 auto 모드의 허용 범위를 좁히고, 금지 사항을 엄격하게 설정합니다.

• CLAUDE.md는 키워나가는 것입니다. 최소 구성에서 시작하여, 실제 사고나 아찔했던 순간(Hiyari-hatto)을 바탕으로 규칙을 추가해 나가는 것이 가장 실천적입니다.