.claude/ 폴더 구조 분석

.claude/

클로드 코드의 동작을 제어하는 핵심 디렉터리로, 프로젝트 별 규칙, 명령, 권한, 메모리 상태를 관리

 

프로젝트 루트의 폴더는 팀 단위 설정을 포함하여 Git에 커밋됨

 

홈 디렉터리 (~/.claude/)의 폴더는 개인 설정과 세션 기록을 저장하며, 자동 메모리 및 개인 명령을 포함

 

 

 

 

 

CLAUDE.md - 클로드의 지침서

Claude Code 세션 시작 시 가장 먼저 읽는 파일로, Claude의 행동 원칙과 프로젝트 규칙을 정의

 

프로젝트 루트의 CLAUDE.md는 팀 공통 규칙

~/.claude/CLAUDE.md는 전역 개인 규칙

하위 폴더의 CLAUDE.md는 폴더별 규칙 담당

 

클로드는 여러 CLAUDE.md 파일을 병합하여 적용

 

권장 내용은 빌드, 테스트 명령, 주요 아키텍처 결정, 비직관적 제약사항, 네이밍 및 에러처리 규칙 등

200줄 이하 유지가 권장되며, 과도한 길이는 클로드의 준수율을 저하시킴

 

 

 

 

 

CLAUDE.local.md - 개인별 오버라이드

팀 공통 규칙과 별도로 개인 선호를 반영할 수 있는 파일

프로젝트 루트에 CLAUDE.local.md를 생성하면 클로드가 이를 함께 읽음

.gitignore에 자동 포함되어 저장소에 커밋되지 않음

 

 

 

 

 

rules/ - 모듈형 규칙 관리

CLAUDE.md가 커질 경우 .claude/rules/ 폴더로 분리해 관리

각 규칙 파일은 주제별로 분리되어 유지보수가 용이

> code-style.md, testing.md 등으로 관리

 

yaml 프런트매터의 paths 필드를 사용하면 특정 경로에만 적용되는 규칙 지정 가능

경로 지정이 없는 규칙은 모든 세션에 항상 로드됨

 

 

 

 

 

commands/ - 사용자 정의 슬래시 명령

! 백틱 구문으로 셀 명령 실행 결과를 Claude 프롬프트에 삽입 가능

> !git diff main ... HEAD

 

$ARGUMENTS 변수를 사용해 명령 실행 시 인자 전달 가능

 

 

 

 

 

skills/ - 자동 실행 워크 플로우

명령과 유사하지만 자동으로 트리거되는 워크플로우로 작동

클로드가 대화 내용을 분석해 적절한 상황에서 자동 실행

 

각 스킬은 하위 폴더의 SKILL.md 파일로 정의되며, yaml 프런트매터로 트리거 조건과 허용 도구 지정

> security-review.md 스킬은 보안 관련 대화 시 자동 실행

 

스킬 폴더에는 DETAILED_GUIDE.md 등 보조 문서나 템플릿 파일 포함 가능

개인 스킬은 ~/.claude/skills에 저장하여 전역적으로 사용 가능

 

 

 

 

 

agents/ - 전문 서브 에이전트

.claude/agents/ 폴더에는 특정 역할을 수행하는 서브 에이전트 (persona) 정의 

각 에이전트는 독립된 시스템 프롬프트, 모델, 도구 접근 권한을 가짐

 

tools 필드로 접근 가능한 도구를 제한해 보안 및 역할 분리 구현

model 필드로 작업에 맞는 클로드 모델 선택 가능

클로드는 필요 시 해당 에이전트를 별도 컨텍스트에서 실행해 결과만 요약 보고

 

 

 

 

 

settings.json - 권한 및 프로젝트 설정

.claude/settings.json는 클로드의 명령 실행 권한과 파일 접근 범위를 정의

 

$schema 필드는 VSCode 등에서 자동 완성과 유효성 검사 지원

allow 목록은 자동 승인 명령

deny 목록은 완전 차단 명령 지정

 

목록에 없는 명령은 실행 전 사용자 확인 요청

개인별 권한 변경은 .claude/settings.local.json에 저장되며, git에 포함되지 않음

 

 

 

 

~/.claude/ - 전역 설정 및 메모리

~/.claude/CLAUDE.md는 모든 프로젝트에 공통 적용되는 개인 지침

 

~/.claude/projects/는 프로젝트 별 세션 기록과 자동 메모리 저장

> 클로드가 학습한 명령, 패턴, 구조적 통찰을 유지

> /memory 명령으로 조회 및 수정 가능

 

~/.claude/commands/ 

~/.claude/skills/

~/.claude/agents/

는 전역 개인 명령, 스킬, 에이전트 저장소

 

 

 

 

 

 

 

Reference

https://news.hada.io/topic?id=27941

.claude/ 폴더 구조 분석 | GeekNews