Claude Code의 .claude/ 폴더, 안에 뭐가 들어있을까?

AI 코딩 어시스턴트의 "기억 저장소"

Claude Code를 써보신 분이라면 프로젝트 루트에 .claude/라는 폴더가 생기는 걸 보셨을 거예요. 대부분은 "뭔가 설정 파일이겠지" 하고 넘어가는데요, 이 폴더의 구조를 제대로 이해하면 Claude Code를 훨씬 더 효과적으로 활용할 수 있어요. 최근 이 .claude/ 폴더의 내부 구조를 상세히 분석한 글이 올라와서, 그 내용을 바탕으로 핵심을 정리해볼게요.

.claude/ 폴더는 쉽게 말해 Claude Code가 여러분의 프로젝트를 "이해"하기 위해 참고하는 설정과 기억의 저장소예요. 마치 새로운 팀원이 입사했을 때 팀 위키나 온보딩 문서를 읽는 것처럼, Claude Code도 이 폴더에 있는 정보를 읽고 프로젝트의 맥락을 파악하는 거죠.

핵심 파일: CLAUDE.md

.claude/ 폴더에서 가장 중요한 파일은 단연 CLAUDE.md예요. 이 파일은 Claude Code에게 주는 "프로젝트 설명서" 같은 역할을 해요. 여기에 프로젝트의 코딩 컨벤션, 아키텍처 결정 사항, 자주 사용하는 명령어, 테스트 실행 방법 같은 것들을 적어두면 Claude Code가 이를 참고해서 더 적절한 코드를 생성해줘요.

이게 뭐냐면, 예를 들어 여러분 팀이 함수명에 camelCase 대신 snake_case를 쓰고, import 순서를 특정 방식으로 정렬하고, 에러 처리를 특정 패턴으로 한다고 해볼게요. 이런 걸 CLAUDE.md에 적어두면, Claude Code가 코드를 생성할 때 자동으로 그 컨벤션을 따라줘요. 적어두지 않으면 매번 "아니 우리는 이렇게 안 해" 하면서 수정해야 하는 거죠.

CLAUDE.md는 프로젝트 루트에 둘 수도 있고, .claude/ 폴더 안에 둘 수도 있어요. 프로젝트 루트에 두면 팀 전체가 공유하기 좋고, .claude/ 안에 두면 개인 설정처럼 쓸 수 있죠. 또한 사용자 홈 디렉토리의 ~/.claude/CLAUDE.md에 전역 설정을 둘 수도 있는데, 이건 모든 프로젝트에 공통으로 적용되는 개인 선호도를 적어두기에 좋아요.

settings.json과 기타 설정 파일들

.claude/ 폴더 안에는 settings.json 파일도 있어요. 이 파일에는 Claude Code의 동작을 제어하는 다양한 설정이 들어가는데요, 어떤 도구를 자동으로 허용할지, 어떤 명령어는 확인 없이 실행해도 되는지 같은 권한 관련 설정이 주를 이뤄요.

예를 들어 git status나 npm test 같은 안전한 명령어는 매번 "실행해도 될까요?" 하고 물어보지 않도록 자동 허용 목록에 넣어둘 수 있어요. 반면 rm -rf이나 git push --force 같은 위험한 명령어는 항상 확인을 거치도록 설정할 수 있고요. 이런 세팅을 잘 해두면 작업 흐름이 훨씬 매끄러워져요.

그 외에도 메모리 시스템과 관련된 파일들이 있어요. Claude Code는 대화 중에 배운 것들 — 예를 들어 사용자의 선호 스타일이나 프로젝트에 대한 중요한 맥락 정보 — 을 메모리 파일로 저장해둘 수 있거든요. 이 메모리 파일들도 .claude/ 하위에 관리돼요.

.gitignore에 넣어야 할까, 말아야 할까?

실무에서 자주 나오는 질문이 ".claude/ 폴더를 git에 커밋해야 하나?"인데요. 이건 상황에 따라 달라요. CLAUDE.md처럼 팀 전체가 공유하면 좋은 프로젝트 컨벤션 문서는 커밋하는 게 좋아요. 새 팀원이 Claude Code를 쓸 때도 같은 맥락을 공유할 수 있으니까요.

반면 settings.json이나 개인 메모리 파일은 .gitignore에 넣는 게 낫겠죠. 개인의 도구 허용 설정이나 대화 기록은 다른 팀원에게 의미가 없으니까요. 보통 CLAUDE.md는 커밋하고, 나머지 .claude/ 하위 파일들은 .gitignore에 추가하는 패턴을 많이 써요.

Cursor, GitHub Copilot 설정과 비교하면

AI 코딩 도구마다 비슷한 개념의 프로젝트 설정 파일이 있어요. Cursor는 .cursor/rules 폴더에 프로젝트 규칙을 정의하고, GitHub Copilot은 .github/copilot-instructions.md 같은 파일을 사용해요. Windsurf는 .windsurfrules를 쓰고요.

재미있는 건, 이런 AI 도구 설정 파일들이 점점 프로젝트의 "표준 문서"처럼 자리 잡아가고 있다는 거예요. 예전에는 README.md와 CONTRIBUTING.md가 프로젝트를 설명하는 핵심 문서였다면, 이제는 AI 도구를 위한 설정 파일도 그만큼 중요해지고 있는 셈이죠. AI가 코드를 작성하는 비중이 늘어날수록, "AI에게 프로젝트를 잘 설명하는 문서"의 가치도 함께 올라가는 거예요.

한국 개발자에게 주는 시사점

국내에서도 Claude Code를 비롯한 AI 코딩 도구 사용이 빠르게 늘고 있는데요, .claude/ 폴더를 제대로 활용하면 AI 어시스턴트의 품질이 확연히 달라져요. 특히 CLAUDE.md를 잘 작성해두는 게 핵심이에요.

당장 해볼 수 있는 것들을 이야기하자면, 먼저 프로젝트의 기술 스택과 디렉토리 구조를 CLAUDE.md에 적어보세요. 그 다음 팀의 코딩 컨벤션과 자주 쓰는 명령어를 추가하고요. 마지막으로 "이 프로젝트에서는 이런 식으로 하지 마" 같은 안티패턴도 적어두면 좋아요. 이렇게 해두면 Claude Code가 마치 팀에 몇 달 있었던 동료처럼 맥락을 이해하고 코드를 작성해줘요.