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 export를 사용하고 default export는 사용하지 않음”)
- 코드를 읽어도 명확하지 않은 아키텍처 결정(“
lib/디렉토리는 서비스 간에 공유됩니다. 여기에 서비스별 로직을 추가하지 마세요.”) - 알려진 문제점(“
config.ts파일은 빌드 시 생성되므로 수동으로 편집하지 마세요.”) - 워크플로 제약 조건(“변경을 수행하기 전에 항상 브랜치를 생성하고, PR을 열기 전에 원격으로 푸시하세요.”)
넣지 말아야 할 내용:
- 디렉토리 목록 및 파일 트리 — Claude는 저장소에서 이를 읽습니다.
- 의존성 목록 —
package.json,pyproject.toml등에서 확인 가능합니다. - 기존 코드가 무엇을 하는지에 대한 설명 — Claude는 소스 코드를 직접 읽습니다.
- 최근 변경 사항 — Claude는 필요할 때
git log와git diff를 사용합니다.
CLAUDE.md는 코드베이스에서 파생할 수 없는 내용에 집중하세요. 200줄 이상의 파일은 더 많은 컨텍스트를 소비하고 준수 신뢰성을 떨어뜨립니다. Claude Code의 /doctor 명령어는 체크인된 CLAUDE.md를 감사하고 코드에서 파생 가능한 콘텐츠를 제거하도록 제안합니다. 이는 부풀려진 파일을 다듬는 유용한 방법입니다.
효과적인 규칙 작성
구체성이 중요합니다. 비교해 보세요:
# 모호함 — 일관성 낮음
프로젝트 코딩 표준을 따르세요.
# 구체적 — 일관성 높음
- npm이나 yarn이 아닌 pnpm을 사용하세요.
- 모든 커밋 전에 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 프론트매터를 사용하여 로드 시점을 제어합니다:
---
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의 프로젝트 설정은 해당 저장소에만 적용됩니다. 프로젝트 설정이 사용자 설정과 겹치는 경우 프로젝트 설정이 우선합니다.
팀에서 MCP 도구에 대한 패키징 참조도 필요한 경우, 이 가드레일을 Claude Code 플러그인 문서 가이드와 함께 사용하세요. 이 가이드는 MCP 플러그인이 규칙, 훅 및 독립형 구성과 관련하여 어디에 위치하는지 설명합니다.
자동 메모리: 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 -p, Agent SDK 또는 CI 파이프라인을 통해 Claude Code를 자율적으로 실행하면 규칙 설정의 중요성이 더욱 커집니다. 에이전트는 중단 없이 수십 개의 도구 호출을 완료할 수 있으며, 중간에 오해를 잡기 위한 대화형 피드백이 없습니다.
기호(preference)가 아닌 명시적 제약 조건을 작성하세요. 대화형 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 문서, 다단계 배포 절차, 문제 해결 매뉴얼은 /deploy 또는 /debug로 호출하는 스킬에 속하며, 관련이 없을 때도 컨텍스트를 소비하는 CLAUDE.md에는 속하지 않습니다.
자동 메모리를 정기적으로 검토하세요. 자동 메모리는 시간이 지남에 따라 축적됩니다. 빌드 명령어가 변경되고, 규칙이 리팩터링되고, 테스트 패턴이 바뀝니다. v2로 마이그레이션했는데 "v1 API 클라이언트를 사용하세요"라는 오래된 메모 메모는 자율 실행에서 미묘한 버그를 유발할 수 있습니다. 프로젝트 구조를 크게 변경할 때 ~/.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가 매번 프로젝트 규칙을 다시 배울 필요가 없습니다. 여러 범위에서 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가 규칙 범위와 일치하는 파일로 작업할 때만 로드되는 경로 범위 지정 규칙 파일을 보관합니다. 이를 통해 모든 세션에 로드하지 않고도 상세하고 도메인별 규칙을 작성할 수 있습니다. 규칙은 패턴을 지정하는 paths 글로브가 있는 선택적 YAML 프론트매터가 있는 마크다운 파일입니다. paths 프론트매터가 없는 규칙은 추가 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 에이전트 사용 방법: 설정, 도구, 권한 및 샌드박스 워크플로
- Claude Code 플러그인: MCP 도구가 Claude Code를 외부 기능으로 확장하는 방법
- Claude Code CLI 문서: 설정, 슬래시 명령어 및 LLM API 통합
- Claude Code SDK: Python 및 TypeScript로 자율 에이전트 구축
- Novita의 Agent Sandbox로 코딩 에이전트 구축하기
출처: 2026년 7월 21일 확인: Claude Code 메모리 문서, Claude Code 기능 개요, Novita AI LLM API
