Claude Code 설정 파일 CLAUDE.md
은 배치 위치에 따라 스코프가 달라집니다. 이 3단계 구조를 의식하여 설계하면, 프로젝트 간의 설정 관리가 극적으로 쉬워집니다.
Layer 1: ~/.claude/CLAUDE.md ← 글로벌 (전체 프로젝트 공통)
Layer 2: <repo>/CLAUDE.md ← 프로젝트 (리포지토리 고유)
Layer 3: <repo>/<dir>/CLAUDE.md ← 디렉토리 (필요할 때만)
| 단계 | 스코프 | 적용 타이밍 |
|---|
| Layer 1 | 전체 프로젝트 | 항상 로드 |
| ... | | |
| 전체 프로젝트에서 공통하는 규칙: | | |
## 환경
- WSL2 Ubuntu / 타임아웃: 10분
## 기본 규칙
...
무엇을 넣을까: 환경 의존적이지 않은 규칙・LLM 정책・보안 규칙・브랜치 운영
리포지토리 고유의 규칙:
## 프로젝트 개요
- Flask 물품 관리 시스템
- 테스트: pytest
...
무엇을 넣을까: 프로젝트 개요・코딩 규약・디렉토리 구조
특정 디렉토리에서만 필요한 규칙 (필요할 때만):
## 이 디렉토리의 주의점
- 스크레이핑 코드: 대상 사이트의 ToS를 확인할 것
- 프록시 경유로 접근할 것
무엇을 넣을까: 디렉토리 특유의 제약・주의사항
글로벌 설정은 여러 장소에 존재:
~/.claude/CLAUDE.md ← 실행 환경
obsidian-ssot/01_DECISIONS/claude-code/설정파일/ ← 이력 관리
변경 시에는 양쪽을 모두 업데이트합니다. obsidian-ssot 측에서 변경 이력을 관리합니다.
# ❌ ~/.claude/CLAUDE.md에 적어서는 안 되는 것
## atelier-kyo-manager
- Flask 애플리케이션
...
→ 전체 프로젝트에 적용되어 버립니다.
# ❌ 리포지토리의 CLAUDE.md에 적어서는 안 되는 것
## API Keys
- MINIMAX_API_KEY=xxx ← 값은 쓰지 않습니다
→ 환경 변수나 secrets.env로 관리합니다.
# ❌ 모든 디렉토리에 CLAUDE.md를 배치하는 것
src/CLAUDE.md
src/models/CLAUDE.md
...
→ 정보가 분산되어 관리할 수 없습니다. Layer 3는 정말로 필요할 때만입니다.
| 단계 | 스코프 | 무엇을 넣을까 |
|---|
| Layer 1 | 전체 프로젝트 | 환경・LLM 정책・보안 |
| ... | | |
- 시크릿 관리 인시던트에서 배우는 Claude Code 안전 운영 — API 키 유출 방지 다층 방어
- Claude Code 백로그 관리를 Hooks로 자동화 — 태스크의 자동 로드・아카이브
- WSL2 + tmux로 Claude Code를 상시 가동 — 개발 환경의 상시 가동 구성
- Context Engineering 입문 — 47KB의 정체와 대책 — 컨텍스트 최적화의 기초
이 기사는 Claude Code (GLM-5.1)와 함께 작성했습니다.
본 기사는 개인 Zenn에서도 공개하고 있습니다.
