들어가며

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을 설치해서 사용해 보겠습니다.