.claude 폴더의 구조와 역할 분석

섹션별 상세

01

Claude 기반 도구들은 프로젝트의 연속성을 위해 .claude라는 숨김 폴더를 생성하여 로컬 상태를 관리한다. 이 폴더는 모델이 프로젝트 내부에서 어떻게 행동해야 하는지에 대한 구성 정보와 캐시된 데이터를 저장하는 저장소 역할을 수행한다. 이를 통해 매번 처음부터 시작하는 대신 이전 작업의 맥락을 이어받아 효율적인 상호작용이 가능해진다.

02

.claude 폴더 내부의 config.json 파일은 모델 선택 및 API 설정과 같은 프로젝트별 동작 규칙을 정의한다. 시스템은 작업 시작 시 이 파일을 가장 먼저 참조하여 제약 사항과 워크플로 구조를 파악한다. 설정이 잘못되었을 때 가장 먼저 확인해야 할 핵심 파일이며 시스템의 진실 공급원(Source of Truth)이 된다.

03

memory/ 및 context/ 디렉터리는 대화 기록이나 임베딩 데이터를 저장하여 모델에게 인위적인 기억력을 부여한다. 모델 자체는 실행 간에 정보를 기억하지 못하지만, 이 폴더에 저장된 데이터를 로드함으로써 이전 상호작용과 일치하는 응답을 생성할 수 있다. 이는 복잡한 에이전트 워크플로에서 상태를 유지하는 데 필수적인 요소이다.

04

작업 실행 시 시스템은 읽기-처리-쓰기의 순환 과정을 거치며 .claude 폴더를 업데이트한다. 먼저 설정을 읽고 컨텍스트를 로드한 뒤, 모델이 작업을 수행하고 그 과정에서 발생하는 로그와 캐시를 다시 폴더에 기록한다. 이러한 루프를 통해 각 실행 결과가 다음 작업의 기반이 되는 데이터 지속성이 확보된다.

text

.claude/
 config.json
 memory/
 agents/
 logs/
 cache/

.claude 폴더의 일반적인 디렉터리 구조 예시

05

.claude 폴더를 삭제하더라도 시스템이 영구적으로 고장 나지는 않지만 로컬에 구축된 모든 지식이 소실된다. 삭제 시 설정값, 캐시된 데이터, 이전 작업의 맥락이 모두 사라져 다음 실행 시 속도가 느려지거나 동작 방식이 변할 수 있다. 다만 설정 오류나 상태 오염이 의심될 때는 폴더를 삭제하여 깨끗한 상태로 리셋하는 용도로 활용할 수 있다.

bash

claude run "Summarize all user feedback from the last 7 days"

Claude CLI를 통해 다단계 작업을 실행하는 명령어 예시

.claude 폴더의 운영 흐름을 보여주는 순환 다이어그램 — Diagram사용자가 작업을 시작하면 config.json을 읽고 컨텍스트 데이터를 로드한 뒤, .claude 폴더에 업데이트를 기록하고 연속성을 유지하며 결과를 저장하는 전체 사이클을 시각화한다. 각 단계가 어떻게 폴더와 상호작용하는지 명확히 보여준다.

Claude 시스템과 .claude 폴더 간의 데이터 교환 아키텍처 — Diagram사용자 입력이 처리 레이어를 거쳐 실행되고 출력되는 과정에서 .claude 폴더(저장 레이어)가 어떻게 설정 로드와 로그 저장을 담당하는지 구조적으로 설명한다. 시스템의 처리 계층과 저장 계층의 분리를 명확히 나타낸다.

용어 해설

로컬 상태(Local State): — 애플리케이션이 실행되는 동안 로컬 환경에 저장되는 데이터의 현재 상태이다. Claude 도구는 이를 통해 이전 작업의 맥락이나 설정을 기억하며, 세션 간의 연속성을 유지하는 역할을 한다.
에이전트 기반 워크플로(Agent-based Workflow): — AI 모델이 단순한 답변을 넘어 스스로 도구를 사용하고 다단계 작업을 수행하는 실행 흐름이다. 각 단계의 진행 상황과 의사결정 내역을 저장하기 위해 로컬 저장소가 필수적으로 요구된다.
지속성(Persistence): — 프로그램이 종료된 후에도 데이터가 사라지지 않고 유지되는 특성이다. .claude 폴더는 프로젝트별 설정과 메모리를 파일 형태로 저장하여 다음 실행 시에도 동일한 환경을 제공한다.
컨텍스트 윈도우(Context Window): — 모델이 한 번에 처리할 수 있는 정보의 범위이다. .claude 폴더 내의 캐시와 메모리는 이 윈도우에 주입될 핵심 정보를 관리하여 모델의 응답 정확도와 일관성을 높인다.

기술

Claude
CLI
JSON

활용 사례

로컬 AI 에이전트 워크플로 관리
프로젝트별 맞춤형 LLM 설정 유지
다단계 AI 작업의 상태 보존 및 디버깅