[Claude] 환경 설정과 CLAUDE.md, 규칙(Rules) 구성법

새로운 도구를 도입할 때 가장 먼저 마주하는 벽은 '설정'이다. 특히 Claude Code처럼 강력한 권한을 가진 도구는 어디서부터 어디까지 허용할지, 그리고 내가 이전에 했던 말을 어떻게 기억하게 할지가 효율성을 결정짓는 핵심이다.

Claude Code는 단순히 일회성 대화를 나누는 챗봇이 아니다. 프로젝트의 아키텍처를 이해하고, 팀의 코딩 컨벤션을 따르며, 지난번의 실수를 반복하지 않도록 설계된 '동료'에 가깝다. 오늘은 Claude Code의 복잡한 설정 범위와 우선순위를 정리하고, 프로젝트의 영혼이라 할 수 있는 CLAUDE.md와 '자동 메모리' 기능을 어떻게 조화롭게 사용할지 학습 노트 형식으로 기록해 본다.

 

1. 주요 특징 및 핵심 로직 (Main Features & Logic)

Claude Code의 설정과 메모리는 '범위(Scope)'와 '계층(Hierarchy)'이라는 두 가지 축으로 움직인다.

🔍 설정 범위 시스템 (Configuration Scopes)

Claude Code는 설정이 적용되는 위치에 따라 영향을 받는 대상과 공유 여부를 결정한다.

Managed	시스템 수준 (managed-settings.json)	머신의 모든 사용자	예 (조직 정책)
User	~/.claude/	모든 프로젝트의 사용자	아니오 (개인 취향)
Project	./.claude/	해당 저장소의 모든 협업자	예 (Git 커밋 포함)
Local	.claude/settings.local.json	현재 저장소의 나만 적용	아니오 (Git-ignored)

우선순위 로직: 구체적인 범위가 넓은 범위를 덮어쓰지만, Managed(관리) 설정은 그 무엇으로도 재정의할 수 없는 절대적인 권한을 가진다.

• Managed > CLI 인수 > Local > Project > User

 

2. 상세 가이드 및 심층 분석 (Detailed Guide)

📌 STEP 1. Claude의 기억 장치: CLAUDE.md vs 자동 메모리

Claude Code는 매 세션을 백지상태에서 시작하지만, 아래 두 가지 시스템을 통해 과거의 지식을 수혈받는다.

구분	CLAUDE.md 파일	자동 메모리 (Auto Memory
작성 주체	사용자 (직접 작성)	Claude (자동 기록)
내용	프로젝트 규칙, 빌드 명령, 아키텍처	학습된 패턴, 디버깅 경험, 사용자 선호도
주요 용도	"항상 X를 수행하세요" 식의 명시적 가이드	"저번에 이 명령어로 해결했었지" 식의 경험 지식

 

📌 STEP 2. 효과적인 지침(Instructions) 구성법

단순히 파일을 만드는 것보다 '어떻게 구조화하느냐'가 Claude의 준수율을 결정한다.

1. 구체성 확보: "코드를 예쁘게 짜줘"보다는 "2칸 들여쓰기 사용"이라고 적어야 한다.
2. 경로 범위 규칙 (.claude/rules/): 프로젝트가 커지면 모든 지침을 한 파일에 넣지 말고, 특정 경로에만 적용되는 규칙을 만드는 것이 좋다.
3. 외부 파일 가져오기: @README.md나 @package.json처럼 이미 존재하는 문서를 참조하여 중복 작성을 피할 수 있다.

 

📌 STEP 3. .claude/rules/를 활용한 세밀한 규칙 관리

대규모 프로젝트에서 모든 규칙을 CLAUDE.md 하나에 넣으면 컨텍스트 윈도우를 과도하게 사용하게 된다. 이를 해결하기 위해 모듈화된 규칙을 사용하자.

• 경로별 규칙 (Path-specific Rules): YAML frontmatter를 사용하여 특정 파일 형식이나 디렉토리에만 규칙을 적용할 수 있다. Claude가 해당 경로의 파일을 읽을 때만 이 지침이 활성화되므로 매우 효율적이다.

--- 
paths: 
   - "src/api/**/*.ts"
--- 
# API 설계 규칙 
- 모든 응답은 `ApiResponse` 포맷을 따를 것. 
- 정적 팩토리 메서드(`ok()`, `error()`) 사용.

• 디렉토리 구조: frontend/, backend/와 같이 하위 폴더로 나누어 규칙을 정리할 수 있다.
• 사용자 수준 규칙: ~/.claude/rules/에 저장한 규칙은 모든 프로젝트에 공통 적용되는 나만의 코딩 철학이 된다.
• 심볼릭 링크 활용: 여러 프로젝트에서 동일한 규칙 세트를 공유하고 싶다면 ln -s를 이용해 .claude/rules/ 폴더에 링크를 걸어주면 된다.

 

📌 STEP 4. 서브에이전트 및 플러그인 확장

Claude Code는 특정 역할에 특화된 서브에이전트를 구성할 수 있다.

• 서브에이전트 위치: 사용자용(~/.claude/agents/), 프로젝트용(.claude/agents/)으로 구분되어 저장된다.
• 플러그인 관리: /plugin 명령어를 통해 마켓플레이스에서 필요한 기능을 추가할 수 있으며, enabledPlugins 설정을 통해 프로젝트별 활성화 여부를 제어한다.

 

3. 실전 설정 및 보안 가이드 (Security & Config)

🛡️ 민감 파일 접근 차단

비밀번호나 API 키가 포함된 파일은 Claude가 아예 읽지 못하도록 설정해야 한다. .claude/settings.json 파일의 permissions.deny 섹션을 활용하자.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  },
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md" // 불필요한 상위 설정 로드 방지
  ]
}

🛠️ 사용자 경험(UX) 최적화

Vim 모드나 언어 설정은 User 범위에 지정하여 손에 익은 환경을 유지하자.

• 편집기 모드: editorMode: "vim"
• 응답 언어: language: "korean"
• 확장 사고: alwaysThinkingEnabled: true (복잡한 로직 설계 시 유리)

 

4. 트러블슈팅: 지침이 지켜지지 않을 때

1. 파일 로드 확인: /memory 명령어를 입력해 현재 세션에 어떤 CLAUDE.md와 규칙 파일이 로드되었는지 체크하자. 리스트에 없다면 Claude는 그 지침을 모르는 상태다.
2. 명령어 충돌: 여러 파일에서 서로 다른 지침(예: "탭 사용" vs "스페이스 사용")을 내리고 있는지 확인하자. 상충할 경우 Claude는 임의로 하나를 선택한다.
3. 압축(/compact) 후 소실: 대화가 길어져 /compact를 실행하면 대화 중 전달한 지침은 사라질 수 있다. 중요한 룰은 반드시 CLAUDE.md에 영구 기록해야 한다.
4. 파일 크기 제한: MEMORY.md의 처음 200줄(약 25KB)만 로드된다. 내용이 너무 많아지면 Claude가 상세 내용을 별도 주제 파일(예: patterns.md)로 분산하도록 유도하자.

 

5. 마무리 

Claude Code를 잘 쓰는 비결은 "Claude를 똑똑한 신입 개발자로 대우하는 것"에 있다. 신입에게 프로젝트의 룰을 설명하듯 CLAUDE.md를 친절하게 적어주고, 그가 스스로 배운 것(자동 메모리)을 가끔씩 검토해 주는 과정이 필요하다.

이러한 설정 체계가 처음에는 복잡해 보일 수 있지만, 한 번 제대로 구축해 두면 어떤 환경에서든 유사한 결과값을 얻을 수 있을 것이다.