.claude/ 폴더 완전 해부: Claude Code 제어의 핵심

.claude/ 폴더란 무엇인가

Hacker News에서 347점을 기록하며 AI 개발자 커뮤니티의 폭발적인 관심을 받은 글이 있다. Daily Dose of DS의 "Anatomy of the .claude/ Folder"다. Claude Code를 사용하는 개발자 대부분이 프로젝트 루트에 .claude/ 폴더가 생겨나는 것을 알지만, 그 내부 구조를 정확히 파악하고 활용하는 사람은 많지 않다.

.claude/ 폴더는 단순한 설정 디렉터리가 아니다. Claude Code가 세션 전반에 걸쳐 팀의 규칙, 명령어, 권한 정책을 유지하게 만드는 실질적인 제어 센터다. 이를 제대로 이해하면 Claude가 프로젝트의 코딩 스타일, 아키텍처 결정, 팀의 비명시적 관행까지 따르게 만들 수 있다.

두 개의 .claude/ 디렉터리

가장 먼저 이해해야 할 것은 .claude/ 디렉터리가 두 곳에 존재한다는 사실이다:

위치	용도	Git 커밋 여부
`{프로젝트루트}/.claude/`	팀 공유 설정 (규칙, 명령어, 권한 정책)	✅ 커밋 권장
`~/.claude/`	개인 설정 (세션 히스토리, 자동 메모리)	❌ 개인 로컬 유지

프로젝트 레벨 폴더는 팀 전체가 동일한 규칙과 명령어, 권한 정책을 공유하도록 설계되어 있다. 글로벌 ~/.claude/ 폴더는 개인 취향과 머신 로컬 상태를 위한 공간이다. 한국 개발팀 관점에서는 .claude/ 폴더를 Git에 커밋하는 것이 팀 AI 코딩 품질 일관성을 유지하는 핵심 전략이다.

CLAUDE.md: AI 행동을 결정하는 핵심 파일

시스템 전체에서 가장 중요한 파일은 단연 CLAUDE.md다. Claude Code 세션이 시작되면 가장 먼저 이 파일을 읽어 시스템 프롬프트에 직접 로드한다. 여기에 무엇을 쓰든 Claude는 세션 전반에 걸쳐 그것을 따른다.

효과적인 CLAUDE.md의 핵심은 무엇을 쓰고 무엇을 쓰지 않느냐에 있다.

반드시 포함해야 할 내용

빌드/테스트/린트 명령어: npm run test, make build 등 실제 실행 명령
핵심 아키텍처 결정: "Turborepo 모노레포 사용", "의존성 주입 패턴 필수" 등
비명시적 함정(gotcha): "TypeScript strict 모드 활성화, 미사용 변수는 에러"
임포트 컨벤션과 네이밍 패턴: 팀 코딩 스타일 규칙
파일/폴더 구조 개요: 주요 모듈의 위치와 역할

포함하지 말아야 할 내용

린터나 포매터 설정에 있어야 하는 내용
링크로 대신할 수 있는 긴 문서
이론 설명 형태의 긴 단락

200줄 이하로 유지하는 것이 권장된다. 더 길어지면 컨텍스트를 과도하게 소비하고, 실제로 Claude의 지시 이행률이 떨어진다는 것이 현장 개발자들의 경험담이다.

CLAUDE.local.md: 개인 맞춤 설정

팀 전체가 아닌 개인에게만 적용되는 설정이 필요할 때는 CLAUDE.local.md를 사용한다. 프로젝트 루트에 생성하면 Claude가 메인 CLAUDE.md와 함께 읽지만, 자동으로 .gitignore에 추가되어 리포지터리에는 올라가지 않는다. 팀 전체 설정에 영향 없이 개인 선호를 적용할 수 있는 깔끔한 분리 방식이다.

rules/와 commands/: 팀 협업의 게임 체인저

관심사별 규칙 분리: rules/ 폴더

CLAUDE.md는 단일 파일 방식이어서 팀이 커지면 300줄짜리 거대한 파일로 불어나고 아무도 관리하지 않게 된다. .claude/rules/ 폴더가 이 문제를 해결한다.

rules/ 폴더 안의 모든 마크다운 파일은 CLAUDE.md와 함께 자동으로 로드된다. 관심사별로 파일을 분리할 수 있다:

.claude/rules/
├── api-conventions.md    # API 설계 규칙
├── testing.md            # 테스트 기준
├── error-handling.md     # 에러 처리 패턴
└── database.md           # DB 쿼리 관행

**경로 범위 규칙(path-scoped rules)**이 특히 강력하다. YAML 프론트매터를 추가하면 특정 파일이나 디렉터리에서 작업할 때만 해당 규칙이 활성화된다:

---
paths:
  - src/api/**
  - src/handlers/**
---
# API 전용 규칙
항상 request validation을 먼저 수행하고...

Claude는 React 컴포넌트를 편집할 때는 이 파일을 로드하지 않는다. src/api/나 src/handlers/ 내부에서 작업할 때만 활성화된다. paths 필드가 없는 규칙은 모든 세션에서 무조건 로드된다.

커스텀 슬래시 명령어: commands/ 폴더

.claude/commands/ 폴더의 모든 마크다운 파일이 커스텀 슬래시 명령어가 된다. review.md 파일을 만들면 /project:review 명령어가 생성된다. fix-issue.md는 /project:fix-issue가 된다.

핵심은 셸 명령어 실행과 결과 주입이다. 백틱 문법(!)으로 셸 명령을 실행하고 그 출력을 프롬프트에 직접 삽입할 수 있다:

아래 변경사항을 검토해주세요:

!git diff HEAD~1

/project:review를 실행하면 실제 git diff가 Claude의 프롬프트에 자동으로 들어간다. 저장된 텍스트가 아니라 실질적으로 유용한 동적 명령어가 된다. $ARGUMENTS를 사용하면 명령어 이름 뒤에 텍스트를 전달할 수도 있다.

프로젝트 명령어는 .claude/commands/에 커밋해 팀 전체가 공유한다. 개인 전용 명령어는 ~/.claude/commands/에 두면 /user:command-name 형태로 모든 프로젝트에서 사용할 수 있다.

고급 설정과 한국 개발팀 활용 전략

Skills vs Commands: 핵심 차이

Skills와 Commands는 겉보기엔 비슷하지만 트리거 방식이 근본적으로 다르다:

Commands: 사용자가 슬래시 명령어로 명시적으로 호출
Skills: Claude가 맥락을 보고 자동으로 적용 여부 판단

대규모 팀에서는 Skills로 코드 리뷰 기준이나 보안 체크리스트 같은 것을 자동 적용되도록 설정할 수 있다.

한국 개발팀 실전 활용 전략

한국 스타트업과 IT 기업 개발팀에서 .claude/ 폴더를 효과적으로 활용하는 방법:

1. 온보딩 단축: 새 팀원이 합류하면 .claude/ 폴더가 프로젝트 전반의 컨벤션을 Claude에게 자동 학습시킨다. 구두로 전달해야 했던 팀 관행이 코드로 문서화된다.

2. 코드 리뷰 자동화: commands/ 폴더에 팀 코드 리뷰 기준을 반영한 명령어를 만들면 일관된 품질 기준이 적용된다.

3. 점진적 AI 도입: rules/ 폴더로 AI 개입 범위를 세밀하게 제어할 수 있어, 한 번에 모든 것을 바꾸지 않고도 점진적으로 AI 코딩을 팀에 도입할 수 있다.

4. 보안 가드레일: 권한 정책 파일로 Claude가 절대 건드리면 안 되는 파일이나 디렉터리를 명시할 수 있다. 프로덕션 설정 파일이나 비밀 관리 모듈 같은 곳에 유용하다.

실무 체크리스트

# .claude/ 폴더 설정 체크리스트

- [ ] CLAUDE.md: 빌드/테스트 명령어 포함
- [ ] CLAUDE.md: 주요 아키텍처 결정 문서화
- [ ] CLAUDE.md: 200줄 이하 유지
- [ ] rules/: 관심사별 규칙 분리
- [ ] commands/: 반복 작업 명령어화
- [ ] .claude/ 폴더 Git 커밋
- [ ] CLAUDE.local.md를 .gitignore에 추가

현재 Claude Code를 사용하면서 .claude/ 폴더를 기본값으로 방치하고 있다면 지금이 바꿀 때다. 이 폴더를 제대로 구성하는 것만으로도 AI 코딩 세션의 품질과 일관성이 눈에 띄게 달라진다. Claude Code 치트시트 가이드와 Claude 코드 품질 분석도 함께 참고하면 더 효과적으로 활용할 수 있다.

FAQ

Q1: .claude/ 폴더를 Git에 커밋해야 하나요?

A: 프로젝트 레벨 .claude/ 폴더는 커밋을 강력 권장합니다. CLAUDE.md, rules/, commands/ 모두 팀 전체가 동일한 AI 코딩 환경을 갖추기 위한 설정이기 때문입니다. 단, CLAUDE.local.md는 자동으로 gitignore됩니다.

Q2: CLAUDE.md를 얼마나 자세하게 작성해야 하나요?

A: 200줄 이하를 권장합니다. 너무 길어지면 컨텍스트 비용이 증가하고 Claude의 지시 이행률이 실제로 낮아집니다. 핵심만 담고 나머지는 rules/ 폴더로 분리하세요.

Q3: 팀원마다 다른 설정을 원하면 어떻게 하나요?

A: CLAUDE.local.md를 사용하세요. 프로젝트 루트에 생성하면 개인 설정이 적용되고, .gitignore에 자동으로 추가되어 리포지터리에 올라가지 않습니다.

Q4: rules/ 폴더의 경로 범위 설정이 작동하지 않으면?

A: YAML 프론트매터 형식을 확인하세요. paths: 키 아래에 glob 패턴을 정확히 작성해야 하며, paths 필드가 없는 규칙은 모든 세션에서 항상 로드됩니다.

Q5: Claude Code의 권한 정책은 어디서 설정하나요?

A: .claude/settings.json 파일에서 설정합니다. 여기서 특정 도구나 파일 접근에 대한 허용/거부 정책을 세밀하게 설정할 수 있습니다. 팀 공유 정책은 이 파일을 Git에 커밋하면 됩니다.

관련 기사