02-구조

02. 구조 — 4 스코프와 머지 순서

CLAUDE.md는 네 스코프에서 로드되며, 더 좁은 스코프가 더 넓은 스코프를 덮어쓴다.

스코프	위치	용도	공유
Managed policy	/etc/claude-code/CLAUDE.md (Linux/WSL) 등	조직 정책, 보안, 컴플라이언스	조직 전체
Project	./CLAUDE.md 또는 ./.claude/CLAUDE.md	팀 공유 코딩 표준·아키텍처	팀 (git)
User	~/.claude/CLAUDE.md	개인 선호 (들여쓰기, 셀 별칭)	본인 전용
Local	./CLAUDE.local.md	프로젝트별 개인 메모 (gitignore)	본인 전용

“More specific locations take precedence over broader ones.” — Anthropic 공식 의역: “더 좁은 스코프가 더 넓은 스코프를 덮어쓴다.”

/init 이 실제로 하는 일

1. 작업 트리 루트를 스캔(언어, 빌드 도구, 테스트 명령 추정).
2. 이미 CLAUDE.md가 있으면 덮어쓰지 않고 개선 제안을 한다.
3. 발견한 빌드/테스트 명령, 디렉토리 구조, 컨벤션을 마크다운으로 정리.
4. 사용자가 검토 후 저장.

“Run /init to generate a starting CLAUDE.md automatically. … If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.”
의역: “/init을 돌리면 시작용 CLAUDE.md가 자동 생성된다. 이미 존재하면 덮어쓰지 않고 개선을 제안한다.”

작성 원칙 4가지

공식 문서가 정리한 작성 원칙을 그대로 가져온다 — 검증 가능할 만큼 구체적이어야 한다.

• Size: 200줄 이하 목표.
• Structure: 마크다운 헤더와 불릿으로 그룹화.
• Specificity: “포맷 잘 해” → “2-space 들여쓰기 사용”.
• Consistency: 모순된 두 규칙이 있으면 모델은 임의로 고른다.