.claude 폴더란 무엇인가?

클로드 코드(Claude Code)를 프로젝트에서 처음 실행하면, 자동으로 생성되는 숨김 폴더다. Git이 .git 폴더로 버전 관리를 하듯, .claude 폴더는 Claude Code의 **프로젝트별 설정과 지침**을 저장하는 핵심 디렉토리다. 이 폴더에는 크게 claude.md, settings.json, .clauderc 세 가지 파일이 포함되며, 각 파일은 서로 다른 역할을 담당한다.

많은 개발자가 Claude Code의 기본 프롬프트만 사용하지만, .claude 폴더를 효과적으로 활용하면 AI 어시스턴트가 프로젝트의 맥락을 정확히 이해하고, 일관된 코드 스타일로 협업할 수 있다. 이 가이드에서는 .claude 폴더의 구조와 각 파일의 활용법을详细介绍한다.

claude.md: 프로젝트별 컨텍스트 설정

claude.md는 Claude Code에게 프로젝트의 목적, 규칙, 제약조건을 전달하는 **프로젝트 선언문**이다. 이 파일이 있으면 Claude는 각 세션마다 해당 프로젝트의 특성을 자동으로 파악한다.

프로젝트 개요
전자상거래 백엔드 API 서버 (Node.js + Express)
기술 스택
- Node.js 18+
- Express.js 4.x
- PostgreSQL 14
- Prisma ORM
코딩 규칙
- 모든 API 엔드포인트에 JSDoc 주석 필수
- 에러 처리는 try-catch 블록 사용
- 환경 변수는 .env.local에만 저장
디렉토리 구조
/src
  /controllers  - 라우트 핸들러
  /services     - 비즈니스 로직
  /models       - Prisma 스키마
  /middleware   - 미들웨어 함수

이렇게 설정하면 Claude Code는 매번 “Express API 프로젝트에서 user 컨트롤러 만들어줘"라고 설명할 필요 없이, 자동으로 프로젝트 구조와 규칙을 이해하고 코드를 생성한다. 새 팀원이 합류했을 때도 claude.md만 읽으면 프로젝트의 윤곽을 빠르게 파악할 수 있다.

settings.json과 .clauderc: 세밀한 동작 제어

settings.json은 Claude Code의 **전역 동작 방식**을 정의한다. 프로젝트 전체에 적용되는 설정으로, 에디터 통합, 자동 승인 규칙, 디렉토리 무시 설정 등을 지정할 수 있다.

{
  "editor": {
    "name": "VS Code",
    "command": "code"
  },
  "permissions": {
    "allow": [
      "Bash(mkdir)",
      "Bash(rm)",
      "Bash(git status)"
    ]
  },
  "expand": true,
  "dangerouslySkipConfirmations": false
}

.clauderc는 더 세밀한 **로컬 설정**을 제공하며, 전역