Ch4. 파일·프로젝트로 맥락 누적
이 장을 끝내면 할 수 있는 것: 자기 폴더에 CLAUDE.md를 작성해 Claude에게 "이 폴더 안에서 일해줘"라고 시킬 수 있다.
1. Claude의 메모리는 짧다 — 외장 SSD가 필요하다
Claude의 가장 큰 약점은 한 가지다. 대화창을 닫으면 다 잊어버린다. 어제 두 시간 들여 가르친 우리 회사 톤·고객 페르소나·금기어를 오늘 다시 처음부터 가르쳐야 한다. 매일.
해결책은 폴더 안에 메모를 적어두는 것이다. 이 메모를 Claude가 스스로 읽도록 약속된 두 가지 방법이 있다.
- CLAUDE.md — 폴더 단위 메모. Claude가 그 폴더에서 일을 시작할 때 가장 먼저 읽는다. "이 프로젝트는 무엇이고, 어떤 규칙을 지키며, 결과물은 어떤 형태로 내야 하는지" 적는다.
- Projects — Claude 웹의 작업공간. CLAUDE.md와 비슷한 역할이지만 웹 한정이고 클릭 인터페이스로 관리한다.
이 두 가지가 곧 Claude의 외장 SSD다. 폴더와 파일이 그의 짧은 메모리를 보완한다. 이 장이 책에서 다뤄질 가치는 한 가지다 — CLAUDE.md 한 번 적어두면 그 폴더에서 시작하는 모든 대화에 그 컨텍스트가 자동 적용된다. 매일 가르치는 시간이 0이 된다.
2. 무엇과 어떻게 다른가
2-1. 일회 첨부 vs CLAUDE.md vs Projects
| 축 | 일회 첨부 | CLAUDE.md | Projects (Claude 웹) |
|---|---|---|---|
| 위치 | 채팅 메시지 | 폴더 루트 파일 | Claude 웹의 작업공간 |
| 지속성 | 한 메시지만 | 그 폴더 안 모든 대화 | 그 Project 안 모든 대화 |
| 용량 | 첨부 한도 | 마크다운 텍스트 (수천 줄 가능) | Project 자료 한도 |
| 자동성 | 매번 첨부 | 자동 로드 | 자동 로드 |
| 협업 | 본인만 | 폴더 공유 시 모두 | Project 멤버 |
| 적합한 일 | 한 번만 쓸 자료 | 장기 프로젝트 | Claude 웹 한정 작업 |
핵심: 장기로 가는 일은 CLAUDE.md, 한 번만 보면 되는 자료는 첨부.
2-2. Claude가 읽는 일반 폴더 구조
비개발자가 Claude 작업용 폴더를 처음 만든다면 이 모양을 가정한다.
my-work-2026/
├── CLAUDE.md ← Claude가 가장 먼저 읽음
├── README.md ← 사람이 처음 보는 안내문
├── data/ ← 입력 자료 (회의록·영수증 등)
│ ├── meeting-2026-05-03.md
│ └── meeting-2026-05-10.md
├── output/ ← Claude가 만든 결과물
│ ├── summary-2026-05-03.md
│ └── summary-2026-05-10.md
├── .claude/ ← Claude 설정·스킬·에이전트 (자동 생성)
│ ├── skills/
│ └── agents/
└── .env ← 비밀 (API 키 등) — .gitignore 필수
5가지만 외운다.
| 위치 | 역할 |
|---|---|
CLAUDE.md | 이 폴더의 규칙 메모 (Claude 자동 로드) |
README.md | 사람을 위한 첫 안내문 |
data/ | 입력 자료. 회의록·영수증·메모 |
output/ | Claude의 결과물 |
.env | 비밀 — 절대 공개 폴더에 안 둠 |
이 한 장의 폴더 구조를 머리에 담으면 다음 챕터들의 예시가 모두 같은 모양으로 읽힌다.
2-3. CLAUDE.md의 단골 3 섹션
| 섹션 | 무엇을 적나 | 예 |
|---|---|---|
| 이 프로젝트는 | 한 줄 정체성 | "주간 회의록 자동 정리 폴더" |
| 규칙 | 지킬 것·금기 | "톤은 존댓말. 영문 약어는 풀어쓰기. 참석자 실명은 결과에 노출하지 않기" |
| 출력 형식 | 결과물 모양 | "결과물은 마크다운. 5줄 요약 + 액션 표 (담당자/액션/기한)" |
3 섹션 각각 1~3줄이면 충분하다. 5줄짜리 CLAUDE.md 한 장이 매일 4공식 4줄 적기를 대신한다.
3. ⚠️ 처음 사람들이 자주 막히는 곳
함정 1. 너무 큰 파일을 첨부 → 컨텍스트 윈도우 초과
Claude가 한 번에 기억할 수 있는 분량(컨텍스트 윈도우)에는 한계가 있다. 100MB짜리 PDF를 통째로 첨부하면 앞부분이 잘려나간다.
대처:
- 큰 파일은 요약해서 첨부 (Claude에게 먼저 요약을 시킨 뒤 그 요약을 CLAUDE.md에)
- CLAUDE.md는 마크다운 텍스트만 넣기 — PDF·이미지는 별도
함정 2. 비밀(API 키·개인정보)을 CLAUDE.md에 적는다
CLAUDE.md는 폴더에 들어가는 텍스트 파일이라 GitHub에 올리면 모두에게 공개된다. API 키, 비밀번호, 개인 식별정보를 CLAUDE.md에 적으면 평생 검색된 다.
대처: 비밀은 .env 파일에 따로 두고, CLAUDE.md에는 "API 키는 .env에 있음" 한 줄만 적는다. .gitignore에 .env 추가는 필수.
함정 3. 일회성 일을 매번 영구 메모리에 넣는다
"오늘 점심 메뉴 추천해줘" 같은 일회성 질문에 CLAUDE.md를 만들 필요는 없다. 일회성은 일회성으로. CLAUDE.md는 3번 이상 반복될 일 일 때 만든다.
기준: "이 일을 다음 주에 또 할 것 같다" — YES면 CLAUDE.md, NO면 첨부.
4. 5분 미니 실습 — 첫 CLAUDE.md 작성
전제
- 데스크톱에 작업 폴더 1개를 정한다 (회의록·일정·가계부 등 매주 반복할 만한 것)
- 텍스트 에디터 1개 (메모장 / VS Code / TextEdit 무엇이든)
단계
-
그 폴더로 이동한다 (Finder/탐색기 또는 터미널
cd). -
텍스트 에디터로 새 파일
CLAUDE.md를 만든다.- macOS: 터미널에서
touch CLAUDE.md후open CLAUDE.md - Windows: 메모장에서 빈 파일을
CLAUDE.md로 저장 (확장자.md주의 — 아래 트러블슈팅 참고)
- macOS: 터미널에서
-
다음 3 섹션을 채운다 (각 1~3줄).
# [내 프로젝트 이름]## 이 프로젝트는___ 를 자동 정리하는 폴더다.## 규칙- 톤은 ___- ___ 정보는 결과에 포함하지 않는다## 출력 형식- ___ 형태로- 분량은 ___ -
저장한다.
-
그 폴더 안에서 Claude Code를 켜고(또는 폴더를 첨부해) 짧은 질문을 던진다.
이 폴더에서 시작하자. CLAUDE.md를 읽고 한 줄로 요약해줘.✓ 체크포인트: Claude가 위에 적은 3 섹션을 한 줄로 요약해 답한다.
결과 인증
이 실습을 끝냈다면:
- 자기 폴더에 CLAUDE.md 한 장이 있다
- Claude가 그 파일을 자동으로 읽었다
- 같은 폴더 안에서 던지는 모든 질문이 그 컨텍스트를 자동 적용한다
⚠️ 트러블슈팅
문제 1: 메모장에서 저장하니 파일이 CLAUDE.md.txt가 됩니다.
→ "다른 이름으로 저장" 다이얼로그에서 파일 형식을 "모든 파일 (.)"로 바꾸고 이름은 CLAUDE.md. 또는 VS Code 같은 에디터를 사용한다.
문제 2: Claude가 CLAUDE.md를 안 읽은 것 같습니다. → 메시지에 "이 폴더의 CLAUDE.md 먼저 읽어줘" 명시. 또는 Claude Code 데스크톱·터미널 사용 (웹은 폴더 인식이 제한적).
문제 3: CLAUDE.md를 어디에 둬야 할지 모르겠습니다. → 프로젝트 폴더 루트(가장 위). 하위 폴더가 아니라 프로젝트 폴더의 첫 자식.
다음 장으로: Ch5에서는 Claude Code가 일하는 3가지 방식 — 로컬·원격·디스패치를 한눈에 본다. 책상 앞에 있을 때, 책상 떠나 있을 때, 자고 있을 때 Claude가 어떻게 다르게 도는지.
© 2026 COMMME · Built with Claude Code