[Claude Code] 2편 - CLAUDE.md와 컨텍스트 관리
들어가며
1편에서는 구체적으로 요청할수록 결과가 좋아진다는 것을 확인했습니다. 그런데 매번 “Unity 6 프로젝트고, 새 Input System을 쓰고, 물리는 FixedUpdate에서 처리하고…“라고 설명하기는 번거롭습니다.
Claude Code는 세션을 시작할 때마다 이전 대화를 기억하지 못합니다. 새 세션의 Claude는 우리 프로젝트를 처음 보는 신입 개발자와 같습니다. 그래서 신입에게 온보딩 문서를 건네주듯, Claude에게도 프로젝트 설명서를 건네줘야 합니다. 그 역할을 하는 파일이 CLAUDE.md입니다.
이번 글에서는 다음 내용을 다룹니다.
- CLAUDE.md가 무엇이고 어디에 두는지
- CLAUDE.md에 넣을 것과 빼야 할 것
- CLAUDE.md가 있을 때와 없을 때의 결과 비교
- Memory 기능
- 컨텍스트 관리 (
/context,/compact,/clear)
1. CLAUDE.md란?
CLAUDE.md는 세션을 시작할 때 자동으로 읽히는 마크다운 파일입니다. 여기에 적어둔 내용은 따로 말하지 않아도 Claude가 항상 알고 있는 상태가 됩니다.
파일을 두는 위치에 따라 적용 범위가 달라집니다.
| 위치 | 적용 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md |
내 모든 프로젝트 | 개인 선호 (예: “답변은 한국어로”) |
프로젝트 루트/CLAUDE.md |
이 프로젝트 | 팀 공유용. git에 올립니다 |
프로젝트 루트/CLAUDE.local.md |
이 프로젝트, 나만 | 개인 설정. git에 올리지 않습니다 |
하위 폴더/CLAUDE.md |
그 폴더 | Claude가 그 폴더의 파일을 읽을 때 함께 읽힘 |
~는 사용자 폴더입니다. Windows라면C:\Users\<사용자명>입니다.
가장 많이 쓰는 것은 프로젝트 루트의 CLAUDE.md입니다. git에 함께 올려두면 팀원 모두가 같은 설명서를 쓰게 됩니다.
2. 실습 1 - CLAUDE.md 없이 요청하기
비교를 위해 먼저 CLAUDE.md가 없는 상태에서 요청해 보겠습니다. 프로젝트 루트에 이미 CLAUDE.md가 있다면 잠시 다른 곳으로 옮겨둡니다.
새 세션을 열고 아래처럼 요청합니다.
적 캐릭터 스크립트 만들어줘. 플레이어를 따라오는 적.
만들어진 코드를 저장해 두고(복사해서 메모장에 붙여두면 됩니다), 다음 항목을 체크해 둡니다.
- 파일이 어느 폴더에 만들어졌는지
-
Inspector 노출 필드를
public으로 했는지,[SerializeField] private로 했는지 -
GetComponent를 어디서 호출하는지 -
이동을
Update에서 하는지,FixedUpdate에서 하는지 -
플레이어를 어떻게 찾는지 (
GameObject.Find를 매 프레임 호출하지는 않는지)
확인이 끝나면 /clear로 대화를 비우고, 만들어진 스크립트 파일도 지워줍니다.
3. 실습 2 - /init으로 CLAUDE.md 만들기
/init 실행
입력창에 다음을 입력합니다.
/init
Claude가 프로젝트 폴더를 둘러보고 CLAUDE.md 초안을 만들어 줍니다. Unity 버전, 설치된 패키지, 렌더 파이프라인 같은 정보를 알아서 찾아 적습니다.
/init은 초안일 뿐입니다. 코드에서 읽어낼 수 있는 정보만 적혀 있고, 팀의 규칙이나 “이건 하지 마” 같은 내용은 Claude가 알 수 없습니다. 이 부분은 직접 채워 넣어야 합니다.
내용 채우기
만들어진 CLAUDE.md에 아래 내용을 추가합니다.
# 프로젝트 개요
3D 액션 게임 수업용 프로젝트. Unity 6, URP.
# 폴더 구조
- Assets/Scripts/Player/ : 플레이어 관련
- Assets/Scripts/Enemy/ : 적 관련
- Assets/Scripts/UI/ : UI 관련
# 코딩 컨벤션
- Inspector에 노출할 필드는 public 대신 [SerializeField] private 사용
- GetComponent는 Awake에서 한 번만 호출하고 캐싱
- Update에서 Find, GetComponent 호출 금지
- 물리 이동은 FixedUpdate에서 Rigidbody로 처리 (Unity 6이므로 linearVelocity 사용)
- 입력은 새 Input System 사용. 레거시 Input.GetAxis 사용 금지
- 클래스 하나당 파일 하나, 파일명과 클래스명 일치
# 금지
- Library/, Temp/, ProjectSettings/ 폴더는 수정하지 말 것
- 씬 파일(.unity), 프리팹(.prefab)을 텍스트로 직접 편집하지 말 것
직접 편집하기 귀찮다면 Claude에게 “CLAUDE.md에 아래 내용 추가해줘”라고 붙여넣어도 됩니다.
4. CLAUDE.md에 넣을 것과 뺄 것
CLAUDE.md는 세션마다 항상 읽힙니다. 길게 쓸수록 매번 그만큼 컨텍스트를 차지하고, 중요한 내용이 묻힙니다. 짧고 핵심만 적는 것이 좋습니다.
넣을 것
- 코드만 봐서는 알 수 없는 것: 팀 컨벤션, 폴더 구조의 의도, 이유가 있는 규칙
- 하면 안 되는 것: 건드리면 안 되는 폴더, 쓰면 안 되는 API
- 자주 쓰는 명령: 빌드, 테스트 실행 방법
- 실수하기 쉬운 것: “이 프로젝트는 새 Input System만 켜져 있음” 같은 함정
뺄 것
- 코드를 보면 바로 알 수 있는 내용 (모든 파일 목록, 클래스 설명)
- 너무 당연한 말 (“깔끔한 코드를 작성할 것”, “버그 없이 만들 것”)
- 자주 바뀌는 내용 (현재 진행 중인 작업 목록)
판단 기준은 간단합니다. “이 내용이 없으면 Claude가 실수할까?” 실수하지 않을 내용이라면 빼도 됩니다.
5. 실습 3 - 같은 요청 다시 하기
CLAUDE.md를 저장했다면 새 세션을 열고 (또는 /clear 후) 처음과 똑같이 요청합니다.
적 캐릭터 스크립트 만들어줘. 플레이어를 따라오는 적.
실습 1에서 만든 체크리스트로 다시 확인해 봅니다.
| 항목 | CLAUDE.md 없음 | CLAUDE.md 있음 |
|---|---|---|
| 파일 위치 | Assets/Scripts/Enemy/ |
|
| 필드 선언 | [SerializeField] private |
|
| GetComponent 위치 | Awake |
|
| 이동 처리 |
FixedUpdate + linearVelocity
|
요청은 똑같은데 결과가 팀 규칙에 맞게 바뀐 것을 확인할 수 있습니다.
6. Memory - 대화 중에 배운 것 기억하기
CLAUDE.md는 내가 직접 쓰는 설명서입니다. 반면 Memory는 Claude가 대화하면서 알게 된 것을 스스로 저장해 두는 기능입니다.
예를 들어 대화 중에 이렇게 말하면,
앞으로 주석은 한국어로 달아줘. 기억해둬.
Claude가 이 내용을 메모리 파일로 저장하고, 다음 세션에서도 기억합니다.
저장된 메모리는 다음 명령으로 확인하고 편집할 수 있습니다.
/memory
| CLAUDE.md | Memory | |
|---|---|---|
| 누가 쓰나 | 사람이 직접 | Claude가 대화 중에 |
| 공유 | git으로 팀과 공유 | 내 컴퓨터에만 |
| 용도 | 프로젝트 규칙 | 개인 선호, 피드백 |
메모리가 쌓이다 보면 오래되거나 틀린 내용이 남을 수 있습니다. 가끔
/memory로 열어서 정리해 주는 것이 좋습니다.
7. 컨텍스트 관리
컨텍스트란?
컨텍스트는 Claude가 한 번에 볼 수 있는 대화의 양입니다. 내가 쓴 메시지, Claude의 답변, 읽은 파일 내용, 명령 실행 결과, CLAUDE.md까지 모두 컨텍스트에 쌓입니다.
컨텍스트가 길어지면 다음 문제가 생깁니다.
- 앞쪽 내용을 덜 정확하게 기억합니다.
- 관련 없는 이전 작업 내용이 섞여서 판단이 흐려집니다.
- 매 요청마다 처리할 양이 많아져 느려지고 비용도 늘어납니다.
/context - 사용량 확인
/context
지금 컨텍스트를 얼마나 쓰고 있는지, 무엇이 얼마나 차지하는지(시스템, CLAUDE.md, 대화, 도구 등) 보여줍니다.
CLAUDE.md가 차지하는 양도 여기서 확인할 수 있습니다. CLAUDE.md를 너무 길게 쓰면 안 되는 이유를 직접 눈으로 볼 수 있습니다.
/compact - 요약하고 이어가기
/compact
지금까지의 대화를 요약해서 컨텍스트를 줄입니다. 작업은 이어가면서 공간만 확보하고 싶을 때 씁니다.
요약할 때 무엇을 남길지 지정할 수도 있습니다.
/compact 적 AI 작업 내용 위주로 남겨줘
/compact 전후로 /context를 실행해 보면 사용량이 줄어든 것을 확인할 수 있습니다.
컨텍스트가 거의 다 차면 Claude Code가 자동으로 요약하기도 합니다. 하지만 자동 요약은 무엇이 중요한지 모르기 때문에, 작업 단위가 끝났을 때 직접 정리하는 것이 더 좋습니다.
/clear - 완전히 새로 시작
/clear
대화를 모두 비우고 새로 시작합니다. CLAUDE.md는 다시 읽히니 프로젝트 규칙은 그대로 유지됩니다.
언제 무엇을 쓰나
| 상황 | 명령 |
|---|---|
| 같은 작업을 계속하는데 대화가 길어짐 | /compact |
| 작업 주제가 바뀜 (적 AI → UI 작업) | /clear |
| Claude가 계속 같은 실수를 반복함 |
/clear 후 더 구체적으로 다시 요청 |
특히 마지막 경우가 중요합니다. 대화 중에 잘못된 방향이 한 번 잡히면, 그 내용이 컨텍스트에 남아 계속 영향을 줍니다. 이럴 때는 고쳐달라고 계속 말하는 것보다, 새로 시작하는 것이 훨씬 빠릅니다.
마치며
이번 글에서는 Claude에게 프로젝트를 설명하는 방법과 대화를 관리하는 방법을 다뤘습니다.
- CLAUDE.md: 매 세션 읽히는 프로젝트 설명서. 짧고 핵심만, “없으면 실수할 내용”만 적기
- Memory: Claude가 대화 중에 배운 것을 기억하는 기능
-
컨텍스트: 길어지면
/compact, 주제가 바뀌면/clear
그런데 CLAUDE.md는 항상 읽힌다는 단점이 있습니다. “적 캐릭터를 만들 때만 필요한 규칙”까지 전부 CLAUDE.md에 넣으면 금방 길어집니다. 다음 글에서는 필요할 때만 꺼내 쓰는 지침서인 Skill을 설치해서 사용해 보겠습니다.