Claude Code 구성을 위한 .claude/ 폴더 구조 이해하기

프로젝트 및 전역 구성 폴더

.claude 디렉터리는 두 가지가 있습니다: 하나는 git에 커밋되는 팀 구성을 위한 프로젝트 루트에 있고, 다른 하나는 세션 기록과 같은 개인 선호도 및 기기 로컬 상태를 위한 홈 디렉터리(~/.claude/)에 있습니다.

CLAUDE.md: 지침 매뉴얼

CLAUDE.md는 각 세션 시작 시 Claude의 시스템 프롬프트에 로드되어 대화 내내 따릅니다. 프로젝트 루트, 전역 선호도를 위한 ~/.claude/, 또는 폴더별 규칙을 위한 하위 디렉터리에 CLAUDE.md를 둘 수 있습니다.

효과적인 CLAUDE.md 내용에는 다음이 포함됩니다:

• 빌드, 테스트, 린트 명령어(npm run test, make build 등)
• 주요 아키텍처 결정 사항
• 명확하지 않은 함정
• 가져오기 규칙, 명명 패턴, 오류 처리 스타일
• 주요 모듈의 파일 및 폴더 구조

CLAUDE.md는 200줄 이하로 유지하세요. 그보다 긴 파일은 너무 많은 컨텍스트를 소비하기 시작하여 Claude의 지침 준수도가 떨어집니다.

CLAUDE.md 구조 예시

# 프로젝트: Acme API

명령어
npm run dev # 개발 서버 시작
npm run test # 테스트 실행 (Jest)
npm run lint # ESLint + Prettier 검사
npm run build # 프로덕션 빌드

아키텍처

• Express REST API, Node 20
• Prisma ORM을 통한 PostgreSQL
• 모든 핸들러는 src/handlers/에 위치
• 공유 타입은 src/types/에

규칙

• 모든 핸들러에서 요청 검증에 zod 사용
• 반환 형태는 항상 { data, error }
• 클라이언트에 스택 추적을 절대 노출하지 않음
• console.log 대신 로거 모듈 사용

주의사항

• 테스트는 모의 객체가 아닌 실제 로컬 DB를 사용합니다. 먼저 npm run db:test:reset 실행
• 엄격한 TypeScript: 사용하지 않는 가져오기는 절대 없음

  CLAUDE.local.md를 통한 개인 재정의

  전체 팀에 적용되지 않는 개인 선호도를 위해 프로젝트 루트에 CLAUDE.local.md를 생성하세요. Claude는 기본 CLAUDE.md와 함께 이를 읽으며, 개인적인 조정이 저장소에 절대 들어가지 않도록 자동으로 gitignore됩니다.

  rules/ 폴더를 통한 모듈식 지침

  더 큰 팀의 경우, rules/ 폴더는 단일 큰 CLAUDE.md 파일보다 확장성이 더 좋은 모듈식 지침을 제공합니다.

  📖 전체 소스 읽기: HN AI Agents