Claude Code가 내 프로젝트를 기억하는 방법 — .claude/ 폴더 7가지 구조 완전 해부

.claude/ 폴더가 뭔지 먼저 알아야 합니다

Claude Code를 처음 써보면 강력하다는 느낌을 받지만, 동시에 한 가지 불편함을 체감하게 됩니다. 매번 새 세션을 시작할 때마다 "우리 프로젝트는 TypeScript를 쓰고, 테스트는 Jest로 하고, 커밋 메시지는 이 형식으로..."와 같은 설명을 반복해야 한다는 점입니다. 그 반복을 없애주는 것이 바로 .claude/ 폴더입니다.

.claude/ 폴더는 Claude Code의 핵심 제어 센터(control center)입니다. 이 폴더 안에 지시 파일, 권한 설정, 커스텀 명령어, 자동화 워크플로우를 넣어두면 Claude Code가 매 세션마다 자동으로 불러와 프로젝트 맥락을 유지합니다. 한 번 설정하면 매번 처음부터 설명할 필요가 없어집니다.

구조는 두 개의 독립적인 디렉토리(directory, 파일을 담는 폴더 단위)로 나뉩니다.

• 프로젝트 수준: .claude/ — 특정 프로젝트 루트에 위치하며, Git으로 팀원과 공유됩니다. 팀 전체가 따라야 할 설정을 여기에 넣습니다.
• 전역 수준: ~/.claude/ — 홈 디렉토리에 위치하며, 해당 컴퓨터의 모든 프로젝트에 적용됩니다. 개인 취향이나 개인 명령어를 여기에 넣습니다.

이 이중 구조 덕분에 팀 설정과 개인 설정이 완전히 분리됩니다. 팀원의 실수로 내 개인 설정이 덮어써지거나, 반대로 내 실험적 설정이 팀 전체에 영향을 주는 일이 없습니다.

7가지 구성 요소 — 각각 무슨 역할인가

CLAUDE.md — Claude의 장기 기억

CLAUDE.md는 .claude/ 폴더에서 가장 중요한 파일입니다. Claude Code가 새 세션을 시작할 때 자동으로 불러오는 주 지시 파일(primary instruction file)입니다. 여기에 적힌 내용은 Claude가 항상 알고 있는 프로젝트 기본 지식이 됩니다.

넣으면 좋은 내용들은 다음과 같습니다.

• 빌드 명령어 (예: npm run build, pytest tests/)
• 아키텍처(architecture, 시스템의 전체 구조와 구성 방식) 결정 사항
• 코딩 컨벤션(convention, 팀이 합의한 코드 작성 규칙)
• 중요한 파일 경로와 그 역할
• 절대 하면 안 되는 일 (예: 특정 파일 수정 금지)

Anthropic은 CLAUDE.md를 200줄 이하로 유지할 것을 권장합니다. 너무 많은 내용을 넣으면 Claude가 중요한 부분을 놓칠 수 있기 때문입니다. 아래는 실제 사용 예시입니다.

# 프로젝트: my-saas-app

## 빌드 및 실행
- 개발 서버: `npm run dev`
- 테스트: `npm run test`
- 빌드: `npm run build`

## 기술 스택
- 프레임워크: Next.js 14 (App Router)
- 언어: TypeScript (strict mode)
- 스타일링: Tailwind CSS
- DB: PostgreSQL + Prisma ORM

## 코딩 컨벤션
- 함수형 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 모든 API 함수는 /lib/api/ 에 위치
- 커밋 메시지: feat/fix/docs/refactor 접두사 필수

## 절대 하지 말 것
- .env 파일 수정 금지
- package.json의 의존성을 무단으로 추가하지 말 것

CLAUDE.local.md — 나만의 비밀 메모

CLAUDE.local.md는 CLAUDE.md와 동일하게 작동하지만, 한 가지 결정적인 차이가 있습니다. 자동으로 .gitignore에 추가되어 Git 저장소에 업로드되지 않습니다. 즉, 팀원에게 절대 노출되지 않는 개인 설정 공간입니다.

여기에 넣으면 좋은 내용들은 다음과 같습니다.

• 개인 개발 환경 특이사항 (예: 내 로컬 DB 포트가 팀과 다를 때)
• 실험 중인 개인 지시 사항
• 팀과 공유하기 민감한 내부 메모

rules/ — 상황별 맞춤 규칙

rules/ 폴더는 CLAUDE.md를 모듈식(modular, 독립적인 단위로 분리해 필요할 때만 불러오는 방식)으로 쪼갠 버전입니다. YAML 프론트매터(frontmatter, 파일 맨 위에 ---로 구분된 메타데이터 블록)로 특정 파일 경로 패턴에서만 활성화되도록 설정할 수 있습니다.

예를 들어, rules/testing.md 파일을 만들고 상단에 다음을 추가하면 테스트 파일을 작업할 때만 이 규칙이 적용됩니다.

---
path: "**/*.test.ts"
---

## 테스트 작성 규칙
- describe/it 블록 구조 필수
- 각 테스트는 독립적이어야 함 (외부 상태 의존 금지)
- 목(mock) 함수는 beforeEach에서 초기화
- 테스트 커버리지 80% 이상 유지

이렇게 하면 CLAUDE.md가 200줄을 넘지 않으면서도, 각 파일 유형별로 세밀한 규칙을 유지할 수 있습니다.

commands/ — 내가 만드는 슬래시 명령어

commands/ 폴더에 마크다운 파일을 넣으면 Claude Code에서 슬래시(slash) 명령어로 사용할 수 있습니다. 파일 이름이 곧 명령어 이름이 됩니다.

예를 들어 commands/review.md 파일을 만들면 Claude Code에서 /project:review를 입력해 실행할 수 있습니다. 백틱(backtick) 구문을 사용하면 셸 명령어도 실행할 수 있습니다.

# 코드 리뷰 명령어

현재 변경사항을 코드 리뷰해주세요.

## 변경된 파일 목록
`git diff --name-only HEAD`

## 체크리스트
- [ ] 타입 안전성 확인
- [ ] 에러 핸들링 누락 여부
- [ ] 테스트 커버리지 확인
- [ ] 성능 문제 가능성
- [ ] 보안 취약점 여부

위 항목을 기준으로 상세 리뷰를 작성해주세요.

자주 반복하는 작업을 명령어로 만들어두면 타이핑 몇 글자로 복잡한 작업 지시를 실행할 수 있습니다. 예를 들어 /project:deploy-check, /project:changelog, /project:api-doc 같은 명령어를 팀 전체가 공유할 수 있습니다.

skills/ — 말만 하면 자동 실행

skills/ 폴더는 commands/보다 한 단계 더 자동화된 워크플로우(workflow, 작업이 순서대로 자동 처리되는 흐름)를 담습니다. 명령어를 직접 입력하지 않아도, 작업 설명이 스킬의 조건과 매칭되면 Claude가 자동으로 해당 스킬을 실행합니다.

각 스킬 폴더에는 반드시 SKILL.md 파일이 있어야 하며, 이 파일에 스킬의 트리거 조건과 실행 절차를 정의합니다. 예를 들어 "새 API 엔드포인트 추가해줘"라고 말하면, Claude가 해당 스킬을 인식하고 라우터 파일 수정 → 컨트롤러 생성 → 테스트 작성 → 문서 업데이트 순서로 자동 처리하는 식입니다.

agents/ — 전문 분야 AI 부하직원

agents/ 폴더에는 특정 작업에 특화된 서브에이전트(sub-agent, 메인 AI가 특정 작업을 위임하는 전문 AI 인스턴스)를 정의할 수 있습니다. 각 에이전트는 고유한 시스템 프롬프트(system prompt, AI의 행동 방식과 역할을 정의하는 초기 지시문)를 가지며, 필요에 따라 다른 모델을 선택할 수도 있습니다.

가장 중요한 특징은 도구 접근 권한 제한입니다. 예를 들어 문서 작성 에이전트에게는 파일 읽기·쓰기 권한만 주고 셸 실행 권한은 주지 않는 식으로, 에이전트가 의도치 않게 시스템에 영향을 주는 것을 막을 수 있습니다.

settings.json — 무엇을 허락하고 막을지

settings.json은 Claude Code의 권한 설정 파일입니다. bash 명령어, 파일 작업, API(Application Programming Interface, 프로그램 간 통신을 위한 규격) 접근에 대해 허용(allowlist)과 거부(denylist) 목록을 정의합니다.

{
  "permissions": {
    "allow": [
      "bash:npm run *",
      "bash:git *",
      "bash:pytest *",
      "read:src/**",
      "write:src/**"
    ],
    "deny": [
      "read:.env",
      "read:.env.*",
      "bash:rm -rf *",
      "bash:curl *",
      "write:package.json"
    ]
  }
}

위 예시에서는 .env 파일 읽기를 명시적으로 차단했습니다. API 키나 데이터베이스 비밀번호가 담긴 환경 변수 파일이 Claude에게 노출되지 않도록 하는 것입니다. 팀 환경에서 settings.json을 Git에 포함시키면 모든 팀원이 동일한 권한 정책을 따르게 됩니다.

지금 당장 시작하는 방법 (3단계)

처음 .claude/ 폴더를 설정하는 가장 빠른 방법은 Claude Code의 내장 명령어를 활용하는 것입니다. Anthropic이 권장하는 시작 경로는 다음과 같습니다.

1단계 — 초기화: Claude Code 터미널에서 아래 명령어를 실행합니다.

/init

이 명령어 하나로 Claude가 현재 프로젝트를 분석해 기본 CLAUDE.md를 자동 생성합니다. 이미 있는 package.json, README.md, 디렉토리 구조를 읽어 적절한 내용을 채워 넣습니다.

2단계 — CLAUDE.md 편집 및 settings.json 추가: 자동 생성된 CLAUDE.md를 열어 팀의 실제 컨벤션에 맞게 수정하고, settings.json에 보안 규칙을 추가합니다.

{
  "permissions": {
    "deny": [
      "read:.env",
      "read:.env.local",
      "read:secrets/**"
    ]
  }
}

3단계 — commands/ 1~2개 생성 후 rules/ 모듈화: 팀에서 자주 쓰는 작업을 commands/에 추가하고, CLAUDE.md가 길어지기 시작하면 rules/로 분리합니다. 한 번에 완벽하게 만들려 하지 말고, 사용하면서 점진적으로 개선하는 것이 좋습니다.

왜 HN에서 당일 최고 참여를 기록했나

Daily Dose of DS의 .claude/ 폴더 해부 글은 Hacker News(HN, 스타트업·개발자 커뮤니티의 대표적인 뉴스 큐레이션 플랫폼)에서 359 포인트, 185 댓글을 기록하며 해당 날 최고 AI 관련 참여를 기록했습니다. 이 반응이 말해주는 것이 있습니다.

Claude Code를 쓰는 개발자들이 가장 원하는 것은 단순히 "AI가 코드를 써주는" 기능이 아닙니다. AI가 자신의 프로젝트 맥락을 이해하고, 팀의 규칙을 따르고, 반복적인 작업을 자동화해주는 기능입니다. .claude/ 폴더는 그 요구를 정확히 충족합니다.

HN 댓글에서 가장 많이 언급된 사용 사례는 다음 3가지였습니다.

• 대규모 레거시(legacy, 오래된 기존 시스템이나 코드베이스) 코드베이스 온보딩 — 새 팀원이 CLAUDE.md만 읽어도 프로젝트 전체 구조를 이해할 수 있도록 문서화
• 보안 민감 환경에서의 settings.json 활용 — 금융, 의료 스타트업에서 AI가 절대 접근하면 안 되는 파일을 명시적으로 차단
• 팀별 코딩 스타일 표준화 — rules/ 폴더로 Python, JavaScript, SQL 각각의 컨벤션을 분리 관리

Claude Code는 단순한 AI 어시스턴트가 아닙니다. .claude/ 폴더를 제대로 설정하면, 팀의 맥락을 완전히 이해하고 팀의 방식대로 일하는 개발 파트너가 됩니다. 그 설정의 시작점은 /init 한 줄입니다.

관련 콘텐츠 — Easy클코로 AI 시작하기 | 무료 학습 가이드 | AI 뉴스 더보기