WEEK 1 / 8

CLAUDE.md
프로젝트 메모리

AI에게 "이 프로젝트는 이런 거야"를 한 번에 알려주는 법

이번 주 배우는 것

  • CLAUDE.md가 무엇이고 왜 게임 체인저인지
  • 좋은 CLAUDE.md의 4가지 섹션 (프로젝트 / 구조 / 규칙 / 금기)
  • Claude에게 스스로 작성시키는 법
  • 핸즈온: 내 폴더에 CLAUDE.md 1개 만들기

→ 끝나면: 같은 작업을 시킬 때 매번 같은 설명을 반복하던 시간이 사라집니다.

CLAUDE.md = "이 폴더의 사용설명서"

내 프로젝트 폴더 안에 두는 마크다운 파일 1개.
Claude Code가 그 폴더에서 실행될 때 맨 처음 자동으로 읽어들임.

비유

새 직원이 처음 출근했을 때 책상 위에 둔 "이 회사는 이런 곳" 안내문.

매일 새 직원이 출근한다고 생각하면 — 안내문 없이는 매일 처음부터 설명해야 함.

위치

내프로젝트/
├── CLAUDE.md   ← 여기
├── src/
└── docs/

파일명 정확히 CLAUDE.md (대문자). 한 폴더에 1개.

없을 때 vs 있을 때 — 같은 질문, 다른 결과

없을 때

나: 이 프로젝트 회의록 정리해줘.
claude: 어떤 형식으로요? 폴더는 어디에?
나: docs/에 마크다운으로...
(다음 날, 새 대화)
나: 이 프로젝트 회의록 정리해줘.
claude: 어떤 형식으로요? 폴더는 어디에?
나: ...어제 말했잖아...

있을 때

나: 이 프로젝트 회의록 정리해줘.
claude: docs/meetings/에
        YYYY-MM-DD.md로 저장하고
        결정사항·액션·다음안건
        3섹션으로 정리하겠습니다.

(매번 똑같이 작동)

Claude Code는 대화가 끝나면 다 잊어버립니다. CLAUDE.md만 영구 기억됨.

좋은 CLAUDE.md의 4가지 섹션

1

프로젝트는 뭐냐

한 줄 — "이 폴더는 ○○를 하는 프로젝트". 목적·대상·왜 만들었는지.

2

폴더 구조 (지도)

"data/=원본, output/=결과, scripts/=자동화" — AI가 어디를 봐야 할지 안내.

3

작업 규칙

"파일명 한국어 OK", "결과 보고는 표로", "함수 짧게" — 나만의 스타일.

4

금기사항

"backup/ 절대 건드리지 마", "원본 수정 금지, 복사본만" — 사고 예방.

BAD vs GOOD — 진짜 파일 비교

BAD

# 내 프로젝트

음악 만드는 폴더입니다.
잘 부탁드려요.

→ 구체적인 게 하나도 없음. AI는 결국 매번 묻게 됨.

GOOD

# Music Factory

Suno로 곡 만들고 YouTube 업로드.

## 폴더
- songs/ : 완성 MP3 + 가사
- covers/: 썸네일
- sop.md : 작업 절차

## 규칙
- 가사 한국어, [Verse]/[Chorus] 영문
- 결과 보고는 표로
- songs/ 삭제 금지 (백업 후만)

작성하는 두 가지 방법

1

직접 쓰기

메모장 / VS Code로 CLAUDE.md 새 파일 만들고 4섹션 채우기.

장점: 내가 100% 통제

단점: 처음엔 뭘 적어야 할지 막막함

2

Claude한테 시키기 (추천)

이 폴더에 CLAUDE.md를 만들어줘.
- 폴더 구조는 자동으로 스캔
- 작업 규칙은 내가 3개 적어줌
- 금기사항 1개

먼저 초안만 보여줘.

가장 빠른 시작. Claude가 폴더 보고 알아서 초안.

HANDS-ON · 15분

지금, 내 폴더에 CLAUDE.md 만들기

  1. (2') 어떤 폴더에 만들지 정하기 — 취미·업무·학습 어느 거든 1개
  2. (2') 터미널 열고 cd 그폴더 → claude
  3. (8') Claude에게 시키기: 
    이 폴더에 CLAUDE.md를 만들어줘.
- 이 프로젝트는 [한 줄 설명]
- 폴더 구조는 스캔해서 적기
- 작업 규칙 3개 (내가 적어줌): ...
- 금기사항 1개: ...

먼저 초안만 보여줘. 내가 확인 후 저장.
  4. (2') 초안 검토 → 수정 요청 → 저장
  5. (1') 새 대화로 claude 다시 띄워서 — "이 프로젝트 뭐 하는 거야?" 물어보기. 한 번에 정답 나오면 성공.

자주 하는 실수 3가지

  1. 너무 길게 쓴다 — A4 5장짜리는 핵심이 흐려짐. 한 화면에 들어오는 분량이 적정.
  2. "잘 해줘" 같은 추상적 요구 — "성실하게" 대신 "결과 보고는 표로", "한 번에 1개 파일만" 같은 측정 가능한 규칙.
  3. 처음에 완벽하게 쓰려 함 — 1주차 CLAUDE.md는 3줄짜리도 OK. 일주일 굴려보고 막힌 지점이 다음 항목.

원칙: 완벽보다 작동. 짧게 시작 → 일주일 후 실수했던 것 한 줄씩 추가.

실전 팁 4가지

① 폴더마다 1개

큰 프로젝트(메인)와 하위 폴더 각각에 둘 수 있음. 하위가 메인을 덮어씀.

② Claude한테 적어달라

"내 폴더 보고 CLAUDE.md 초안 만들어줘" — 가장 빠른 시작.

③ 일주일 후 보강

막혔던 순간 = 추가할 항목. "이거 매번 묻네" 싶으면 CLAUDE.md에.

④ 비밀번호·API 키 금지

CLAUDE.md는 공유될 수 있음. 민감 정보는 .env로.

오늘은 여기까지.

이번 주 동안 — 오늘 만든 CLAUDE.md를 자기 폴더에서 굴려보세요.
좋았던 점·막혔던 점 한 줄씩만 메모해 오시면 다음주에 나눠봐요.

수고하셨습니다 :)

다음주 — W2 · 파일·웹 도구 마스터
CLAUDE CODE DEEP DIVE · W1 · 2026