클로드 코드 폴더 구조: 지침·설정·작업 자료를 배치하는 프로젝트 설계도

클로드 코드 폴더 구조는 프로젝트의 CLAUDE.md에 작업·검증 방법을 적고, 필요한 설정을 .claude/에 두는 데서 시작하면 됩니다. 여러 프로젝트에 두루 쓸 개인 공통 설정과 지침은 홈 디렉터리의 ~/.claude/에 둬요. 컴퓨터의 모든 폴더를 새로 정리할 필요는 없습니다.

제가 권하는 순서는 지금 실제로 작업할 프로젝트 하나에 공통 지침과 설정 파일부터 갖추는 것입니다. CLAUDE.md에는 코드를 수정하는 방식과 결과를 확인할 명령을 적고, .claude/에는 설정과 필요한 확장 기능을 두세요. 규칙·스킬·에이전트 폴더까지 처음부터 다 만들어 둘 이유는 없어요.

폴더가 몇 개인지보다 작업 방법을 쉽게 찾을 수 있는지가 먼저입니다.

어디에 두느냐가 범위와 읽히는 시점을 정합니다

~/.claude/는 개인의 여러 프로젝트에 걸친 영역이고, 프로젝트 안의 .claude/는 그 프로젝트의 설정 영역입니다. 작업 지침 파일인 CLAUDE.md는 프로젝트 루트에 둬도 되고 .claude/ 안에 둬도 돼요. 개인 공통 지침이라면 ~/.claude/CLAUDE.md에 쓰면 됩니다.

흔히 놓치는 부분은 지침이 읽히는 시점이에요. 시작 위치와 상위 디렉터리의 지침은 세션이 시작될 때 읽히고, 하위 디렉터리의 지침은 그 안의 파일을 읽거나 작성·수정할 때 불러옵니다. 하위 지침이 상위 지침을 통째로 대체하지는 않아요. 그러니 서로 충돌하는 내용을 양쪽에 중복해서 적지 않는 편이 낫습니다.

.claude/rules/의 규칙에 paths 조건을 붙이면, 관련 경로의 파일을 다룰 때 불러오도록 범위를 좁힐 수 있어요. 프로젝트 전체의 작업 방식은 공통 지침에, 특정 경로에서만 필요한 관례는 조건부 규칙에 나눠 두세요.

일반 자료 폴더는 따로 생각해야 합니다. docs/에 문서를 모아 두었다고 해서 그 내용이 모두 자동으로 제공되지는 않아요. 필요한 파일은 프롬프트에서 @로 지정하거나 읽어 달라고 요청하세요. 자료를 어디에 보관하느냐와 Claude가 언제 읽느냐는 서로 다른 문제이고, 저는 이 구분이 가장 헷갈리기 쉬운 지점이라고 봅니다.

최소 구조에서 시작해 검증 명령을 붙이세요

작은 프로젝트라면 아래 구조로 시작해도 충분합니다. src/, docs/, tests/는 설명을 위한 일반 폴더명이니 기존 프로젝트 구조에 맞춰 바꾸면 돼요.

project/
├── CLAUDE.md             # 프로젝트 작업·검증 지침
├── .claude/
│   └── settings.json     # 팀 공유 설정
├── src/                 # 소스 코드
├── docs/                # 필요할 때 읽을 작업 자료
└── tests/               # 테스트 코드

이 구조에서 가장 먼저 들여다볼 곳은 CLAUDE.md에 검증 방법이 들어 있는지입니다. 테스트 폴더 위치만 적지 말고, 실제로 실행할 테스트·빌드 명령과 실행 위치까지 기록하세요. 코드만 읽어도 알 수 있는 설명보다는 프로젝트 고유의 실행 방법과 예외 규칙이 더 쓸모 있어요.

초기 지침은 이 순서로 만들고 확인합니다.

1. 프로젝트에서 /init을 실행해 초기 CLAUDE.md를 만듭니다.
2. 생성된 지침을 검토하고, 작업·테스트 명령이 프로젝트의 실제 사용 방식과 맞는지 확인합니다.
3. /context에서 지침의 로드 여부를 확인합니다.

생성된 파일은 완성본이 아니라 검토를 시작하는 초안으로 보세요. 특히 검증 명령이 빠져 있으면 작업이 끝난 뒤 무엇을 확인해야 할지가 모호해집니다. 지침에 무엇을 담을지는 공식 Claude Code 권장 사용법을 기준으로 점검할 수 있어요.

같은 절차를 되풀이하게 되면 그때 .claude/skills/<이름>/SKILL.md를 추가하면 됩니다. 공통 지침에 모든 절차를 늘어놓기보다, 반복 작업이 분명해진 시점에 스킬로 떼어 내는 순서가 낫다고 봐요.

팀과 나눌 것, 나만 쓸 것, 그리고 읽을 분량

팀이 함께 쓸 설정은 .claude/settings.json에, 한 프로젝트에서 나만 쓸 설정은 .claude/settings.local.json에 둡니다. 개인의 프로젝트별 작업 지침은 CLAUDE.local.md에 쓰세요. 홈 디렉터리의 개인 설정은 팀원에게 그대로 전달되지 않아요. 그래서 공유할 프로젝트 지침과 설정은 버전 관리에 커밋해야 합니다.

개인 파일은 Git에서 제외됐는지까지 확인해 두세요. Claude Code가 로컬 설정 파일을 생성하면 제외 처리를 해 주지만, 직접 만든 .claude/settings.local.json은 .gitignore에 따로 추가해야 합니다. CLAUDE.local.md도 직접 제외하도록 안내되어 있어요.

파일을 나누는 것과 읽을 분량을 줄이는 것은 별개의 이야기입니다.

공식 문서에 나오는 CLAUDE.md 파일당 200줄 미만은 간결하게 쓰기 위한 권장치예요. @path로 다른 문서를 가져오면 그 내용도 함께 읽히기 때문에, 파일을 쪼갰다는 이유만으로 문맥 사용량이 줄어들지는 않습니다. 긴 지침을 정리할 때는 그 내용이 항상 필요한지부터 따져 보세요. 관련 작업에만 필요한 규칙이라면 paths 같은 로드 조건을 검토하는 편이 효과적입니다. 구체적인 적용 방식은 공식 지침과 기억 문서에서 확인할 수 있어요.