클로드 코드의 .claude 폴더 속 핵심 요소 정복하기

한눈에 보기

• 출발점: 2026년 3월 23일 공개된 해외 데이터 과학 뉴스레터 원문 글
• 핵심 뜻: .claude 폴더는 숨김 폴더가 아니라 클로드 코드의 행동 기준을 담는 작업실
• 가장 중요한 파일: CLAUDE.md, 프로젝트 설명서이자 작업 안내문 역할
• 꼭 구분할 점: 프로젝트 안 폴더와 내 컴퓨터 안 폴더는 쓰임새가 다름
• 최신 보정: 예전 사용자 정의 명령은 지금 작업 꾸러미 체계와 사실상 합쳐져 있음
• 실무 포인트: AI 코딩 도구를 잘 쓰는 팀은 모델보다 먼저 규칙, 권한, 공유 문서를 정리함

서론

클로드 코드를 처음 쓸 때 많은 사람이 가장 먼저 지나치는 곳이 있다. 바로 .claude 폴더다. 이름도 낯설고 숨김 폴더라서, 그저 프로그램이 알아서 쓰는 내부 공간처럼 보이기 쉽다.

하지만 실제로는 반대에 가깝다. 이 폴더는 클로드 코드가 이 저장소에서 어떤 방식으로 움직여야 하는지, 무엇을 읽고 무엇을 조심해야 하는지를 정리해 두는 중심 공간이다. 사람으로 치면 신입 기자에게 건네는 취재 수첩과 업무 지침서에 더 가깝다.

왜 다들 이 폴더에서 헷갈릴까

• 첫 오해: 그냥 프로그램이 쓰는 숨김 폴더라고 생각하기 쉬움
• 실제 역할: 규칙, 권한, 작업 절차, 개인 기억을 나눠 담는 공간
• 중요한 이유: 같은 모델을 써도 이 폴더를 정리한 팀과 아닌 팀의 결과 차이가 큼
• 현장 느낌: 설명을 자주 반복하는 팀일수록 이 폴더를 제대로 써야 함

개발팀에서 AI 코딩 도구가 자꾸 엉뚱한 방향으로 움직이는 이유는 성능 부족만이 아니다. 프로젝트 구조를 잘 모르고, 팀이 중요하게 여기는 규칙도 모른 채 일을 시작하기 때문이다.

예를 들어 어떤 팀은 테스트를 먼저 돌려야 하고, 어떤 팀은 고객 정보가 담긴 파일은 절대 읽으면 안 된다. 어떤 저장소는 에러 기록 방식을 엄격하게 맞춰야 하고, 어떤 저장소는 같은 이름의 폴더가 많아 길을 잃기 쉽다. 이런 정보를 말로만 전하면 매번 다시 설명해야 한다.

그래서 .claude 폴더는 AI를 더 똑똑하게 만드는 비밀 장치라기보다, 덜 헤매게 만드는 안내판이라고 보는 편이 맞다.

프로젝트 안 폴더와 내 폴더는 다르다

• 프로젝트 안 폴더: 팀이 같이 쓰는 규칙과 설정
• 내 폴더: 내 취향, 내 전역 설정, 내 컴퓨터에 쌓이는 기억
• 가장 쉬운 구분: 팀 문서함과 개인 노트북의 차이
• 흔한 실수: 개인 설정을 팀 저장소에 넣거나, 팀 규칙을 개인 폴더에만 적어 두는 일

클로드 코드에서 가장 먼저 알아야 할 사실은 .claude 폴더가 한 군데가 아니라는 점이다. 하나는 현재 프로젝트 안에 있고, 다른 하나는 내 컴퓨터의 홈 폴더 아래에 있다.

• 프로젝트 쪽: .claude 폴더와 CLAUDE.md
• 개인 쪽: ~/.claude 폴더

쉽게 말해 프로젝트 안에 있는 폴더는 반 전체가 같이 보는 학급 공지판이고, 홈 폴더 안쪽은 내 개인 공책이다. 팀 전체가 따라야 하는 테스트 절차나 파일 구조를 개인 공책에만 적어 놓으면 다른 사람은 못 본다. 반대로 내 취향까지 공지판에 붙이면 팀원이 불편해진다.

이 구분이 중요한 이유는 생각보다 단순하다. AI 도구를 혼자 쓸 때는 내 취향만 챙겨도 되지만, 팀 단위로 쓰기 시작하면 누구나 지켜야 할 기준과 각자 편한 방식을 나눠 두는 일이 먼저 필요해진다. 이 선이 흐리면 새 팀원이 들어올 때마다 설정 충돌이 생긴다.

가장 먼저 손봐야 할 파일, CLAUDE.md

• 한 줄 뜻: 프로젝트 설명서이자 작업 안내문
• 담아야 할 것: 실행 명령, 폴더 구조, 코딩 규칙, 자주 틀리는 함정
• 빼야 할 것: 긴 이론 설명, 이미 다른 문서에 있는 장문 복사, 추상적인 당위 문장
• 공식 권장: 너무 길게 쓰지 말고 짧고 또렷하게 유지

원문과 공식 문서가 한목소리로 강조하는 파일이 바로 CLAUDE.md다. 이 파일은 클로드 코드가 작업을 시작할 때 가장 먼저 보는 프로젝트 안내문이라고 생각하면 쉽다.

여기에는 “우리는 어떤 저장소인가”, “무슨 명령을 써야 하나”, “어떤 실수를 자주 하나” 같은 내용이 들어가면 된다. 개발자끼리 구두로 자주 말하던 내용을 짧게 적어 두는 곳이라고 보면 감이 빠르다.

예를 들어 이런 내용이 잘 맞는다.

• 실행 명령: 개발 서버 켜기, 테스트 돌리기, 배포 전 확인하기
• 구조 설명: 핵심 폴더가 어디에 있는지, 공용 타입이나 공용 함수가 어디에 있는지
• 작업 규칙: 에러는 어떻게 기록하는지, 응답 형식은 어떻게 맞추는지
• 주의 사항: 실제 데이터베이스를 건드리는 테스트인지, 엄격한 타입 검사를 쓰는지

반대로 이런 내용은 길기만 하고 도움은 적다.

• 이미 자동으로 강제되는 들여쓰기 규칙
• 위키 문서 한 편을 통째로 복사한 설명
• “코드를 예쁘게 써라”처럼 기준이 흐린 문장

공식 문서는 CLAUDE.md를 너무 길게 늘리지 말라고 권한다. 이유도 단순하다. 문장이 길고 많을수록 사람이 읽기 힘들고, 도구도 중요도를 가려 읽기 어려워진다. 결국 짧고 분명한 문장이 오래 남는다.

규칙 파일, 작업 꾸러미, 하위 에이전트는 무엇이 다를까

• 규칙 파일: 늘 적용되는 생활 수칙
• 작업 꾸러미: 특정 일을 만났을 때 불러오는 절차 묶음
• 하위 에이전트: 코드 리뷰나 보안 점검처럼 따로 맡기는 전문가 역할
• 최신 변화: 예전 사용자 정의 명령은 이제 작업 꾸러미 체계와 거의 같은 흐름으로 봐도 됨

이 부분은 처음 보면 가장 헷갈린다. 이름도 비슷하고 다 비슷한 보조 기능처럼 보이기 때문이다. 하지만 실제 역할은 꽤 다르다.

• 규칙 보관함 .claude/rules: 항상 지켜야 하는 기준을 적는 곳
• 작업 꾸러미 폴더 .claude/skills: 특정 작업을 할 때 불러오는 절차 묶음
• 하위 에이전트 폴더 .claude/agents: 따로 떼어 맡기는 전문 역할

쉽게 비교하면 이렇다.

• 규칙 파일: “이 학교에서는 실내화로 갈아 신고 들어온다” 같은 상시 규칙
• 작업 꾸러미: “체육대회 날은 이런 순서로 움직인다” 같은 일감별 절차
• 하위 에이전트: “이 문제는 보건 선생님에게, 저 문제는 상담 선생님에게 맡긴다” 같은 역할 분리

특히 2026년 기준으로는 예전 사용자 정의 명령을 따로 외우기보다, 작업 꾸러미 중심으로 이해하는 편이 덜 헷갈린다. 공식 문서도 예전 명령 방식을 별도 기능이라기보다 작업 절차 확장선에서 설명하고 있기 때문이다. 새로 정리할 때는 작업 꾸러미 폴더 .claude/skills를 중심에 두는 편이 더 깔끔하다.

권한 설정 파일은 왜 중요할까

• 핵심 역할: 무엇을 바로 실행하고, 무엇은 물어보고, 무엇은 막을지 정함
• 안전장치: 테스트 실행은 열어 두고 민감 파일 읽기는 막는 식의 선 긋기
• 팀 운영 포인트: 빠른 자동화와 안전 사이의 균형
• 국내 현실: 회사 저장소일수록 이 선을 더 또렷하게 정해야 함

권한 설정 파일 .claude/settings.json은 말 그대로 권한과 행동 범위를 정하는 파일이다. 여기서 중요한 질문은 하나다. “클로드 코드가 어디까지 혼자 움직여도 되나”다.

어떤 팀은 테스트 실행 정도는 바로 허용하고 싶어 한다. 반면 환경 변수 파일, 비밀값, 파괴적인 삭제 명령은 쉽게 열어 두면 불안하다. 이 경계를 글로 써 두는 곳이 바로 이 파일이다.

공식 문서 흐름을 아주 쉽게 줄이면 세 가지다.

• 바로 허용할 것
• 반드시 막을 것
• 그 사이에서 한 번 확인받을 것

AI 코딩 도구가 편리한 이유는 빠르기 때문이다. 하지만 회사 저장소에서는 빠른 것만으로 충분하지 않다. 승인 없이 무엇이 실행되는지, 민감한 정보는 어디까지 읽을 수 있는지, 팀 전체가 같은 기준을 쓰는지가 더 중요해진다. 그래서 개인 장난감처럼 쓸 때와 회사 도구처럼 쓸 때의 차이가 가장 크게 드러나는 파일도 바로 권한 설정 파일 .claude/settings.json이다.

내 컴퓨터 안에는 개인 기억도 쌓인다

• 개인 안내문 파일: ~/.claude/CLAUDE.md
• 개인 권한 파일: ~/.claude/settings.json
• 개인 기억: 이전 작업에서 쌓인 자동 메모
• 읽는 법: 팀 규칙이 아니라 내 작업 습관과 발견 사항이 모이는 공간

원문이 흥미로운 이유 가운데 하나는 홈 폴더 아래 ~/.claude도 함께 짚는다는 점이다. 이곳은 팀 공용 문서함이 아니라, 내 컴퓨터에서만 쓰는 개인 작업 공간이다.

여기에는 내 전역 안내문도 들어갈 수 있고, 개인 설정도 들어간다. 또 공식 문서 기준으로는 클로드 코드가 작업을 하면서 쌓은 자동 기억도 이 범주에 들어간다. 쉽게 말해 “이 저장소에서는 이런 명령이 잘 통하더라”, “지난번에 이런 방식이 먹혔다” 같은 메모가 쌓이는 셈이다.

다만 이 자동 기억을 너무 마법처럼 볼 필요는 없다. 어디까지나 도움이 되는 메모이지, 절대 법칙은 아니다. 규칙이 서로 충돌하거나 문장이 흐리면 사람도 헷갈리듯 도구도 흔들릴 수 있다. 그래서 기억을 많이 쌓는 것보다, 충돌 없는 기준을 먼저 정리하는 일이 더 중요하다.

처음 세팅할 때는 이렇게 시작하면 된다

• 첫걸음: 초기 설정 명령 /init으로 초안을 만들고 시작
• 다음 단계: CLAUDE.md를 짧게 다듬기
• 안전선: 권한 설정 파일 .claude/settings.json으로 범위 정리
• 확장 순서: 반복 작업 하나를 작업 꾸러미로 묶기
• 마지막 단계: 정말 복잡한 일에만 하위 에이전트 추가

원문이 좋은 이유는 처음부터 거창한 구조를 요구하지 않는다는 점이다. 실제로는 한 번에 다 만들 필요가 없다. 오히려 너무 많이 켜 두면 더 복잡해진다.

시작 순서는 소박할수록 좋다.

• 먼저 CLAUDE.md 한 장으로 프로젝트 설명을 정리한다
• 그다음 권한 설정 파일로 안전한 범위를 잡는다
• 자주 반복하는 일 하나를 작업 꾸러미로 묶는다
• 그래도 설명 흐름이 자꾸 길어질 때만 하위 에이전트를 붙인다

이 정도만 해도 체감 차이는 꽤 크다. 사람도 새 반에 들어가면 교실 안내도와 시간표만 있어도 덜 헤맨다. 클로드 코드도 비슷하다. 시작부터 모든 기능을 켜는 것보다, 꼭 필요한 안내부터 분명히 써 두는 편이 훨씬 낫다.

한국 개발팀이 이 구조에서 얻는 것은 무엇일까

• 빠른 적응: 새 팀원이 프로젝트 규칙을 빨리 따라옴
• 생산성: 말로 반복하던 설명이 문서와 작업 절차로 바뀜
• 보안: 개인 취향과 팀 공용 기준을 나눌 수 있음
• 운영: AI 코딩 도구를 개인 비서가 아니라 팀 공용 도구로 보게 됨

한국 개발팀에서는 아직 AI 코딩 도구를 개인 생산성 도구처럼 받아들이는 경우가 많다. 하지만 실제로 팀 단위 도입이 시작되면 질문이 달라진다. 누가 어떤 명령을 열어 둘지, 팀 공통 규칙은 어디에 적을지, 새 팀원은 무엇부터 읽어야 할지가 더 중요해진다.

이때 .claude 폴더 구조를 이해하고 있으면 도입이 훨씬 부드러워진다. 스타트업은 새 팀원의 적응 속도를 높일 수 있고, 규모가 큰 조직은 권한과 절차를 더 또렷하게 나눌 수 있다. 결국 차이는 모델 이름이 아니라, 우리 팀의 기준을 파일로 남겨 두었는가에서 먼저 벌어진다.

결론

클로드 코드의 .claude 폴더는 어렵고 복잡한 기술 용어 묶음처럼 보일 수 있다. 하지만 핵심만 남기면 뜻은 분명하다. 이 폴더는 클로드 코드에게 “우리 팀은 이렇게 일한다”라고 알려 주는 공간이다.

가장 먼저 볼 것은 CLAUDE.md다. 그다음은 권한 설정 파일이다. 그리고 반복 업무가 생기면 작업 꾸러미를 만들고, 정말 복잡한 검토가 필요할 때만 하위 에이전트를 붙이면 된다. 이 순서만 잡아도 클로드 코드는 훨씬 덜 헤매고, 팀도 같은 설명을 덜 반복하게 된다.

원문이 던지는 메시지도 결국 여기에 가깝다. AI 코딩 도구를 잘 쓰는 길은 화려한 기능을 다 켜는 데 있지 않다. 안내문을 짧고 분명하게 쓰고, 권한과 역할을 나눠 두는 것에서 시작한다.

참고 자료

• .claude 폴더 구조를 설명한 원문 글 - 데일리 도스 오브 데이터 사이언스, 2026년 3월 23일
• 클로드가 프로젝트를 기억하는 방식 - 클로드 코드 공식 문서, 2026년 3월 28일 확인
• 클로드 코드 권한 설정 - 클로드 코드 공식 문서, 2026년 3월 28일 확인
• 작업 꾸러미로 기능 넓히기 - 클로드 코드 공식 문서, 2026년 3월 28일 확인
• 맞춤형 하위 에이전트 만들기 - 클로드 코드 공식 문서, 2026년 3월 28일 확인