Claude Code 반복작업으로 부터 토큰 낭비를 없애는 가장 확실한 방법 (CLAUDE.md)

새 세션을 시작할 때마다 이런 상황이 반복됩니다.

이 프로젝트는 SwiftUI + MVVM + Clean Architecture 기반이고,

비동기는 async/await 써줘. 로그는 OSLog 써줘.

외부 라이브러리는 추가하기 전에 먼저 물어봐.

Claude Code는 대화 단위로 동작합니다.

세션이 바뀌면 이전 맥락은 전부 사라집니다.

 

매번 같은 설명을 반복하는 것은 시간 낭비이자 토큰 낭비입니다.

이 문제를 해결하는 것이 CLAUDE.md 파일입니다.

 

CLAUDE.md란

프로젝트 루트에 두는 마크다운 파일입니다.

Claude Code는 실행될 때 이 파일을 자동으로 컨텍스트에 주입합니다.

세션이 바뀌어도, 컨텍스트를 초기화해도

CLAUDE.md는 항상 먼저 읽힙니다.

처음 만나는 Claude가 프로젝트를 이미 알고 있는 상태가 됩니다.

 

CLAUDE.md 만드는 방법

새 프로젝트를 시작할 때 — 직접 작성

프로젝트 초반에는 Claude가 분석할 코드가 많지 않습니다.

이때는 직접 작성합니다.

처음엔 간단하게 시작하는 게 좋습니다.

# MyApp — Project Guide for Claude

## 프로젝트 개요

AI 코칭 러닝 앱. SwiftUI + Clean Architecture. 포트폴리오 목적.

## 아키텍처

Clean Architecture 4계층: Domain / Data / Presentation / Infrastructure

ViewModel은 @MainActor. 비동기 처리는 async/await.

## 코딩 규칙

- print() 금지. 로그는 OSLog.Logger 사용
- try! 금지. do-catch + logger.error() 처리
- 외부 라이브러리 추가 전 반드시 확인

Claude Code와 작업하면서 규칙이 생길 때마다 추가합니다.

 

진행 중인 프로젝트에 추가할 때 — /init

코드가 이미 쌓인 프로젝트라면 /init을 사용합니다.

/init

Claude Code가 코드베이스를 분석해서 초안을 자동 생성합니다.

이후 팀 규칙과 금지 사항을 추가해서 다듬으면 됩니다.

 

/init이 생성한 결과물은 대략 이런 형태입니다.

 

 

효율적으로 활용하는 법

200줄 이내로 유지한다

CLAUDE.md는 매 세션마다 컨텍스트에 주입됩니다.

파일이 길수록 실제 작업에 쓸 수 있는 공간이 그만큼 줄어듭니다.

한글은 영어보다 같은 내용 기준 약 1.5~2배 토큰을 소모합니다.

규칙은 간결하게, 설명은 생략하는 게 유리합니다.

공식 권장 기준은 200줄 이내입니다.

 

코드에서 읽을 수 있는 건 넣지 않는다

• 넣어야 할 것:
  • Claude가 코드만 보고 알 수 없는 규칙
  • 프로젝트 고유 제약과 금지 사항
  • 반복적으로 설명하게 되는 맥락
• 넣지 말아야 할 것:
  • 폴더 구조, 클래스 설명 (코드에서 파악 가능)
  • 배경 설명, 개발 히스토리
  • 모호한 요청 ("깔끔하게 작성해줘")

 

## 헤더와 XML 태그를 함께 사용한다

## 헤더는 사람이 읽기 좋은 구조를 만들고,

XML 태그는 Claude가 섹션 경계를 더 정확하게 파싱합니다.

단독으로 써도 작동하지만,

규칙처럼 정확히 지켜야 하는 내용은 XML로 감싸면 실수가 줄어듭니다.

## 코딩 규칙

<rules>

- print() 금지. 로그는 OSLog.Logger 사용
- try! 금지. do-catch + logger.error() 처리
- 외부 라이브러리 추가 전 반드시 확인

</rules>

 

금지 규칙으로 작성한다

# 덜 효과적

- 로그를 남길 때는 OSLog를 사용해주세요

# 더 효과적

- print() 금지. OSLog만 사용

부드러운 요청보다 명확한 금지가 훨씬 잘 지켜집니다.

 

Claude가 실수할 때마다 업데이트한다

CLAUDE.md는 한 번 쓰고 끝내는 파일이 아닙니다.

Claude가 try!를 썼다          → "try! 금지" 추가

Claude가 Alamofire를 추가했다  → "외부 라이브러리 추가 전 확인" 추가

Claude가 print()를 썼다       → "print() 금지" 추가

실수가 쌓일수록 CLAUDE.md가 정교해집니다.

 

팀 협업에서의 활용

CLAUDE.md는 Git으로 관리합니다.

팀 전체가 같은 규칙으로 Claude를 사용하게 됩니다.

팀원 A가 규칙 발견 → CLAUDE.md 업데이트 → commit & push

팀원 B가 pull → 같은 CLAUDE.md → 같은 Claude 행동

Claude가 팀원마다 다른 스타일로 코드를 생성하면

PR 리뷰에서 불필요한 논의가 반복됩니다.

CLAUDE.md가 공유되면 코드 생성 기준이 통일됩니다.

 

신규 팀원 온보딩

새로운 팀원이 합류했을 때도 효과적입니다.

컨벤션, 금지 패턴, 아키텍처 원칙이 CLAUDE.md에 담겨있으면

Claude와 함께 코드를 작성하면서 자연스럽게 프로젝트를 파악할 수 있습니다.

 

한 명이 발견한 규칙이 팀 전체에 적용된다

Claude가 잘못된 패턴 생성

→ 규칙을 CLAUDE.md에 추가

→ commit & push

→ 팀 전체 적용

한 명의 발견이 팀 전체의 Claude 품질을 높입니다.

 

정리

CLAUDE.md는 문서가 아닙니다.

Claude의 행동 기준을 고정하는 장치입니다.

 

핵심 포인트:

• 새 프로젝트는 직접 작성, 기존 프로젝트는 /init 활용
• 200줄 이내, 금지 규칙 위주로 유지한다
• ## 헤더와 XML 태그를 함께 써서 구조화한다
• Claude가 실수할 때마다 업데이트하고, Git으로 팀과 공유한다

CLAUDE.md를 잘 관리하는 것은 AI와 협업하는 방식을 설계하는 일입니다.