Claude Code 규칙은 CLAUDE.md 파일에 저장됩니다. 프로젝트 저장소, 홈 디렉토리 또는 조직 구성에 배치하는 마크다운 파일로, Claude가 모든 세션 시작 시 읽어갑니다. .claude/rules/의 경로 스코프 규칙, 권한을 위한 settings.json, 학습된 선호도를 위한 자동 메모리와 결합하여, 규칙 시스템은 어떤 작업에서든 코딩 에이전트의 동작을 정밀하고 지속적으로 제어할 수 있게 해줍니다.
Claude Code 규칙이란?
각 Claude Code 세션은 빈 컨텍스트 창으로 시작합니다. 규칙은 Claude가 처음부터 시작하거나 같은 실수를 반복하지 않도록 필요한 컨텍스트를 미리 로드하는 방법입니다.
두 가지 상호 보완적인 시스템이 이를 처리합니다:
CLAUDE.md 파일 은 사용자가 작성하는 마크다운 파일로, Claude가 모든 세션 시작 시 읽어갑니다. 항상 적용되어야 하는 지침(빌드 명령어, 코드 규칙, 아키텍처 결정, 강제 제약 조건)에 사용하세요.
자동 메모리 는 세션 중 사용자가 준 수정 사항과 선호도를 바탕으로 Claude가 스스로 작성하는 노트입니다. 이는 자동으로 축적되며, Claude가 저장할 가치가 있는 것을 결정하고 향후 세션에서 해당 노트를 다시 읽어옵니다.
둘 다 세션 시작 시 컨텍스트에 로드되지만, 강제 구성은 아닙니다. 이는 Claude가 컨텍스트로 따라야 하는 지침입니다. 특정 명령어를 Claude가 무엇을 하기로 결정하든 관계없이 차단하는 하드 강제 적용을 위해서는 PreToolUse 훅이나 settings.json의 deny 규칙이 필요합니다. 이 구분은 예측 가능한 동작을 원하는 자율 실행에서 중요합니다.
CLAUDE.md 파일 위치와 범위
Claude Code는 여러 위치에서 CLAUDE.md 파일을 로드하며, 각각 다른 범위를 다룹니다. 가장 광범위한 것부터 가장 구체적인 순서로 로드됩니다:
| 위치 | 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md |
기기의 모든 프로젝트 | 개인 선호도, 전역 워크플로 습관 |
./CLAUDE.md (저장소 루트) |
해당 프로젝트의 모든 세션 | 프로젝트 규칙, 빌드 명령어, 팀 공유 규칙 |
./CLAUDE.local.md (저장소 루트) |
로컬 세션만 | 개발자별 선호도; .gitignore에 추가 |
./src/CLAUDE.md (하위 디렉토리) |
해당 디렉토리 파일을 다루는 세션 | 프로젝트 전체에 적용되지 않는 모듈별 규칙 |
발견된 모든 파일은 컨텍스트에 연결됩니다 — 서로 덮어쓰지 않습니다. 연결 내에서 파일 시스템 루트에서 작업 디렉토리까지의 콘텐츠는 가장 좁은 범위가 마지막에 오도록 정렬되므로, 사용자 명령어 뒤에 프로젝트 명령어가 나타납니다. 이는 자연스러운 특수성을 제공합니다: 프로젝트 규칙이 사용자 수준 규칙과 충돌할 경우 프로젝트 규칙이 우선합니다.
CLAUDE.md 내에서 @path 참조를 사용하여 추가 파일을 가져올 수 있습니다:
@./docs/architecture.md
@./CONTRIBUTING.md
가져온 파일은 CLAUDE.md 자체와 마찬가지로 세션 시작 시 로드됩니다. 가져오기는 조직화에 유용하지만 컨텍스트를 절약하지는 않습니다 — 가져온 콘텐츠는 토큰 예산에 포함됩니다.
팀의 경우: 프로젝트 CLAUDE.md를 소스 제어에 커밋하세요. 이렇게 하면 모든 개발자의 Claude 세션과 CI 기반 에이전트 실행이 동일한 공유 컨텍스트로 시작됩니다. 이를 .eslintrc나 pyproject.toml처럼 취급하세요.
CLAUDE.md에 넣을 내용
가장 유용한 콘텐츠는 매 세션마다 다시 설명해야 하는 내용이나, 새 팀원이 첫 시간에 알아야 할 내용입니다.
좋은 후보:
- 기본값과 다른 빌드 및 테스트 명령어 (
npm test가 아닌./scripts/test.sh --ci) - 린터가 포착하지 못하는 코드 규칙(“공유 유틸리티에서 모든 곳에 named exports 사용; default exports 사용 금지”)
- 코드를 읽어도 명확하지 않은 아키텍처 결정(“
lib/디렉토리는 서비스 간에 공유됩니다 — 거기에 서비스별 로직을 추가하지 마세요”) - 알려진 문제점(“
config.ts파일은 빌드 시 생성됩니다; 수동으로 편집하지 마세요”) - 워크플로 제약 조건(“변경을 가하기 전에 항상 브랜치를 만드세요; PR을 열기 전에 원격으로 푸시하세요”)
넣지 말아야 할 것:
- 디렉토리 목록 및 파일 트리 — Claude는 저장소에서 직접 읽습니다
- 의존성 목록 —
package.json,pyproject.toml등에서 확인 가능 - 기존 코드가 무엇을 하는지에 대한 설명 — Claude는 소스 코드를 직접 읽습니다
- 최근 변경 사항 — Claude는
git log와git diff를 사용하여 히스토리가 필요할 때 확인합니다
CLAUDE.md는 코드베이스를 읽어서 유도할 수 없는 내용에 집중하세요. 200줄이 넘는 파일은 더 많은 컨텍스트를 소비하고 준수 신뢰성을 떨어뜨립니다. Claude Code의 /doctor 명령어는 체크인된 CLAUDE.md를 감사하고 코드에서 유도 가능한 내용을 제거하도록 제안합니다 — 불필요하게 커진 파일을 다듬는 유용한 방법입니다.
효과적인 규칙 작성
구체성이 중요합니다. 비교해보세요:
# 모호함 — 일관성 낮음
프로젝트 코딩 표준을 따르세요.
# 구체적 — 일관성 높음
- pnpm 사용, npm이나 yarn 사용 금지
- 모든 커밋 전에 pnpm test 실행; 테스트 실패 시 커밋 금지
- 모든 공유 타입은 src/types/index.ts에서 내보내기 — 컴포넌트 파일에 인라인으로 타입 정의 금지
- data/ 디렉토리는 테스트에서 읽기 전용; tests/fixtures/의 테스트 픽스처 사용
모든 규칙은 추가 설명 없이 실행 가능해야 합니다. 규칙의 근거를 누군가에게 설명해야 한다면, 인라인으로 근거를 추가하세요 — Claude가 에지 케이스에서 규칙을 올바르게 적용하는 데 도움이 됩니다.
.claude/rules/를 사용한 경로 스코프 규칙
.claude/rules/ 디렉토리를 사용하면 특정 파일 패턴에 규칙을 연결할 수 있으며, 모든 세션에 로드하지 않아도 됩니다. Claude는 .claude/rules/에서 파일을 발견하고 일치하는 파일로 작업할 때 로드합니다.
TypeScript 모노레포의 일반적인 구조:
.claude/rules/
api.md # src/api/** 규칙 — 요청 검증, 에러 형식
components.md # src/components/** 규칙 — prop 타입, 스타일링 규칙
tests.md # tests/** 규칙 — 픽스처 패턴, 모크 설정
database.md # migrations/ 및 models/ 규칙 — 마이그레이션 명명, 쿼리 패턴
각 규칙 파일은 로드 시점을 제어하는 paths 필드가 있는 YAML frontmatter를 사용합니다:
---
paths:
- "src/api/**/*.ts"
- "src/api/**/*.test.ts"
---
# API 개발 규칙
- 모든 라우트 핸들러는 비즈니스 로직 전에 zod로 입력을 검증해야 함
- 에러는 `{ error: string; code: string }`로 반환 — 일반 문자열 사용 금지
- 속도 제한은 게이트웨이에서 적용됨; 핸들러 내부에 추가하지 마세요
paths 필드가 없는 규칙은 프로젝트 CLAUDE.md의 콘텐츠와 마찬가지로 세션 시작 시 조건 없이 로드됩니다. paths가 있는 규칙은 Claude가 해당 패턴과 일치하는 파일을 열 때만 로드됩니다.
이렇게 하면 프로젝트 루트 CLAUDE.md를 간결하게 유지하고, 스택의 한 계층에 대한 상세 규칙이 다른 영역에 집중된 세션에서 컨텍스트를 채우지 않도록 할 수 있습니다.
settings.json과 CLAUDE.md의 차이
CLAUDE.md는 Claude가 알고 의도하는 것을 제어합니다. settings.json은 Claude가 실제로 수행하도록 허용된 것을 제어합니다.
| CLAUDE.md | settings.json | |
|---|---|---|
| 목적 | 지침 및 컨텍스트 | 권한 및 구성 |
| 강제 여부 | 아니요 — Claude가 지침으로 따라야 함 | 예 — deny 규칙이 도구 호출을 무조건 차단 |
| 형식 | 자유 형식 마크다운 | 구조화된 JSON |
| 위치 | ./CLAUDE.md, ~/.claude/CLAUDE.md |
.claude/settings.json, ~/.claude/settings.json |
.claude/settings.json의 프로젝트 settings.json:
{
"permissions": {
"allow": [
"Bash(pnpm test)",
"Bash(pnpm build)",
"Bash(git status)",
"Bash(git diff *)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(git push --force*)",
"Bash(git reset --hard*)"
]
}
}
allow 목록은 특정 명령어를 사전 승인하여 Claude가 프롬프트 없이 실행할 수 있게 합니다. 이는 신뢰하는 작업에 대해 대화형 세션 속도를 높입니다. deny 목록은 명령어를 무조건 차단합니다 — Claude가 무엇을 결정하든, CLAUDE.md가 무엇을 말하든 관계없이. 프로덕션 데이터나 인프라에 대한 되돌릴 수 없는 작업에는 deny를 사용하세요.
사용자 수준 설정(~/.claude/settings.json)은 모든 프로젝트에 적용됩니다. 프로젝트 설정(.claude/settings.json)은 해당 저장소에서만 적용됩니다. 프로젝트 설정이 사용자 설정보다 우선합니다.
자동 메모리: Claude의 노트
자동 메모리는 CLAUDE.md의 대응물입니다. CLAUDE.md가 사용자가 작성하는 지침인 반면, 자동 메모리는 세션 중 학습한 내용을 바탕으로 Claude가 스스로 작성하는 노트입니다.
세션 중 Claude를 수정하면(“이 프로젝트에서는 Jest가 아닌 Vitest를 사용합니다”) 이를 ~/.claude/projects/<repo>/memory/에 노트로 저장할 수 있습니다. 다음 세션에서 Claude는 해당 노트를 다시 읽고 다시 말하지 않아도 수정 사항을 적용합니다.
메모리 디렉토리에는 다음이 포함됩니다:
~/.claude/projects/<repo>/memory/
MEMORY.md # Claude가 다른 파일을 찾는 데 사용하는 인덱스; 각 세션에서 처음 200줄 로드
debugging.md # Claude가 이 저장소에서 문제를 해결하면서 발견한 패턴
conventions.md # Claude가 사용자의 수정 사항에서 학습한 규칙
이는 머신 로컬이며 저장소별입니다. 자동 메모리는 CLAUDE.md를 대체하기보다 보완합니다: CLAUDE.md는 팀 공유 프로젝트 규칙용이고, 자동 메모리는 사용자와 함께 작업하면서 Claude가 학습한 개인 패턴용입니다.
자동 메모리는 읽을 수 있는 마크다운으로, 언제든지 편집하거나 삭제할 수 있습니다. 세션 내에서 /memory를 실행하여 파일을 탐색하고 편집하세요. 내용이 오래되었거나 잘못된 경우 삭제하세요 — Claude는 더 이상 오래된 규칙을 적용하지 않습니다.
에이전틱 코딩을 위한 모범 사례
Claude Code를 자율적으로 실행할 때 — claude -p, Agent SDK, 또는 CI 파이프라인을 통해 — 규칙 설정의 중요성이 더욱 커집니다. 에이전트는 수십 번의 도구 호출을 멈춤 없이 완료할 수 있으며, 실행 중간에 오해를 잡아낼 상호작용이 없습니다.
선호도가 아닌 명시적 제약 조건을 작성하세요. 대화형 Claude는 명확히 물어볼 수 있습니다. 자율 실행은 컨텍스트에 있는 내용으로 작업합니다. "데이터베이스 스냅샷을 먼저 생성하지 않고 마이그레이션 파일을 수정하지 마세요"가 중요하다면, CLAUDE.md에 있어야 합니다. Claude가 코드베이스 구조에서 제약 조건을 유추할 것이라고 가정하지 마세요.
되돌리기 어려운 작업에는 deny 규칙을 사용하세요. Bash(pnpm build)를 사전 승인하면 대화형 세션 속도가 빨라지고 위험이 낮습니다. 하지만 자율 실행의 경우, deny 목록은 프로덕션 인프라를 건드리거나, git 히스토리에 영구적으로 커밋하거나, 데이터를 삭제하는 작업에 대한 안전망입니다.
프로젝트 CLAUDE.md를 버전 관리에 유지하세요. 저장소 루트에 커밋된 CLAUDE.md는 대화형 세션, CI 실행, 모든 팀원의 로컬 에이전트에 일관되게 적용됩니다. 이는 코드베이스에서 “올바른” 것이 무엇인지 정의하는 규칙을 위한 올바른 위치입니다.
도메인별 콘텐츠에는 .claude/rules/를 사용하세요. 프로젝트에 뚜렷한 계층(프론트엔드 컴포넌트, 백엔드 API, 데이터베이스 스키마, 인프라 스크립트)이 있는 경우, 각 계층의 규칙을 경로 스코핑과 함께 .claude/rules/에 넣으세요. 모든 내용이 담긴 400줄짜리 단일 CLAUDE.md는 Claude가 탐색하기 어렵고 세션당 더 많은 컨텍스트를 소비합니다.
참조 자료는 스킬로 옮기세요. 스킬(.claude/skills/)은 세션 시작 시가 아닌 요청 시 로드됩니다. 긴 API 문서, 여러 단계의 배포 절차, 문제 해결 플레이북은 CLAUDE.md가 아닌 /deploy나 /debug로 호출하는 스킬에 속합니다.
자동 메모리를 주기적으로 검토하세요. 자동 메모리는 시간이 지남에 따라 축적됩니다. 빌드 명령어가 변경되고, 규칙이 리팩토링되고, 테스트 패턴이 바뀝니다. "v1 API 클라이언트를 사용하세요"라고 말하는 오래된 메모리 노트는 v2로 마이그레이션한 경우 자율 실행에서 미묘한 버그를 일으킬 수 있습니다. 프로젝트 구조를 크게 변경할 때 ~/.claude/projects/<repo>/memory/를 감사하세요.
오픈소스 모델을 규칙 설정과 함께 사용하기
구축한 CLAUDE.md 컨텍스트와 .claude/rules/는 어떤 모델이 추론을 처리하든 동일하게 작동합니다. 규칙이 작성되면 모델 백엔드를 전환해도 모든 것이 유지되며, Novita AI의 LLM API를 통한 오픈소스 모델은 대량의 에이전틱 작업에 실용적인 옵션입니다.
구성은 하나의 환경 변수입니다:
export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"
ANTHROPIC_BASE_URL이 Novita AI를 가리키면, Claude Code는 모든 추론 요청을 api.anthropic.com 대신 Novita의 Anthropic 호환 엔드포인트로 보냅니다. CLAUDE.md, 경로 스코프 규칙, settings.json은 모두 이전과 동일하게 적용됩니다 — 규칙 계층은 모델 선택보다 상위에 있습니다.
Novita AI는 Qwen3-Coder, GLM-4.7, MiniMax M2.5, DeepSeek V4를 포함한 코딩 중심의 오픈웨이트 모델을 호스팅합니다. 이 모델들은 다단계 도구 사용과 함수 호출에 최적화되어 있어, Claude Code가 파일 편집, 셸 명령어, 저장소 탐색을 위해 내부적으로 사용하는 도구 호출 패턴에 잘 맞습니다.
대규모로 에이전틱 작업을 실행하는 팀(코드 리뷰 파이프라인, 대규모 저장소 자동 리팩토링, 테스트 생성)의 경우, Novita의 오픈웨이트 모델은 일반적으로 백만 토큰당 폐쇄형 소스 대안보다 훨씬 저렴하면서도 프로젝트 규칙을 효과적으로 읽고 적용합니다.
프로덕션 코드베이스에 대해 에이전트를 실행하고 deny 규칙 이상의 추가 안전 계층을 원한다면, Novita의 LLM API를 Novita의 Agent Sandbox와 함께 사용하는 것을 고려하세요. 샌드박스는 에이전트에게 호스트 시스템과 격리된 파일 작업 및 명령어 실행을 위한 완전한 Linux 환경을 제공합니다. CLAUDE.md 컨텍스트는 작업과 함께 이동하며, 실행 위험은 격리된 상태로 유지됩니다.
FAQ
Claude Code에서 CLAUDE.md란 무엇인가요?
CLAUDE.md는 Claude Code에 세션 간 지속적인 지침을 제공하는 마크다운 파일입니다. 세션 시작 시 로드되므로 매번 프로젝트 규칙을 다시 가르칠 필요가 없습니다. 여러 범위에서 CLAUDE.md 파일을 가질 수 있습니다: 모든 곳에 적용되는 개인 선호도를 위한 사용자 수준(~/.claude/CLAUDE.md), 버전 관리에 체크인된 팀 공유 규칙을 위한 프로젝트 수준(저장소 루트), 모듈별 규칙을 위한 하위 디렉토리 수준.
claude rules md 파일에는 무엇을 넣어야 하나요?
매 세션마다 다시 설명해야 할 내용을 작성하세요: 빌드 및 테스트 명령어, 프레임워크 기본값과 다른 코딩 규칙, 아키텍처 제약 조건, 알려진 코드베이스 문제점. Claude가 코드베이스 자체에서 유도할 수 있는 내용(파일 트리, 의존성 목록, 기존 코드 설명)은 넣지 마세요. 일관된 준수를 위해 파일을 200줄 미만으로 유지하세요.
Claude Code에서 CLAUDE.md와 settings.json의 차이는 무엇인가요?
CLAUDE.md는 Claude가 지침으로 따라야 하는 명령어입니다. settings.json은 Claude Code가 시스템 수준에서 강제하는 구성입니다. CLAUDE.md의 규칙은 Claude가 의도하는 바를 형성하고, settings.json의 deny 항목은 도구 호출을 무조건 차단합니다. Claude가 무엇을 결정하든 관계없이 절대 발생해서는 안 되는 작업(되돌릴 수 없는 삭제, 강제 푸시, 프로덕션 환경 작업)에는 CLAUDE.md가 아닌 settings.json을 사용하세요.
.claude/rules/ 디렉토리는 무엇인가요?
.claude/rules/는 Claude가 규칙의 범위와 일치하는 파일로 작업할 때만 로드되는 경로 스코프 규칙 파일을 보관합니다. 이를 통해 모든 세션에 로드하지 않고도 상세한 도메인별 규칙을 작성할 수 있습니다. 규칙은 선택적 YAML frontmatter로 paths glob 패턴을 지정하는 마크다운 파일입니다. paths frontmatter가 없는 규칙은 추가 CLAUDE.md 콘텐츠처럼 세션 시작 시 조건 없이 로드됩니다.
CLAUDE.md는 CI 및 자동화된 claude code 작업에서 작동하나요?
네. 저장소 디렉토리에서 실행되는 모든 claude -p 호출, Agent SDK 호출, 또는 CI 파이프라인은 프로젝트의 CLAUDE.md를 로드합니다. 이는 CLAUDE.md를 대화형 및 자동화된 컨텍스트 모두에서 일관된 동작을 강제하는 데 효과적으로 만듭니다. 버전 관리에 커밋하면 모든 실행(로컬 및 CI)이 동일한 공유 컨텍스트로 시작됩니다.
claude code 컨텍스트는 어떻게 작동하며 어떻게 관리하나요?
컨텍스트는 현재 세션의 토큰 예산입니다. CLAUDE.md 파일, 가져온 참조, 자동 메모리, 대화 히스토리가 모두 이에 포함됩니다. CLAUDE.md를 간결하게 유지하고, .claude/rules/를 사용하여 관련 있을 때만 도메인 콘텐츠를 로드하고, /compact를 사용하여 연속성을 잃지 않고 긴 세션을 요약하여 관리하세요. /compact 후 Claude는 디스크에서 프로젝트 루트 CLAUDE.md를 다시 읽고 자동으로 세션에 다시 주입합니다.
팀에서 에이전틱 코딩을 위한 claude code 모범 사례를 어떻게 사용하나요?
모든 팀원과 CI 에이전트가 동일한 규칙을 공유하도록 프로젝트 CLAUDE.md를 저장소에 커밋하세요. 도메인별 콘텐츠에는 경로 스코핑과 함께 .claude/rules/를 사용하세요. 자동화된 컨텍스트에서 절대 실행되어서는 안 되는 작업에는 .claude/settings.json에 deny 규칙을 추가하세요. 자동 메모리를 CI에서 제외하세요 — 머신 로컬이며 개발자별입니다; 커밋된 CLAUDE.md가 공유 동작의 진실 공급원입니다.
Novita AI는 개발자가 간단한 API를 사용하여 AI 모델을 쉽게 배포할 수 있도록 하면서, 구축 및 확장을 위한 저렴하고 안정적인 GPU 클라우드를 제공하는 AI 클라우드 플랫폼입니다.
추천 아티클
- Claude Code CLI 문서: 설정, 슬래시 명령어, LLM API 통합
- Claude Code SDK: Python 및 TypeScript로 자율 에이전트 구축
- Novita의 Agent Sandbox로 코딩 에이전트 구축하기
출처 확인: 2026년 7월 21일 — Claude Code 메모리 문서, Claude Code 기능 개요, Novita AI LLM API
