CLAUDE.md

CLAUDE.md

프로젝트에 대한 맞춤형 지침, 즉 가이드라인 프로젝트의 컨텍스트를 더 잘 파악하도록 돕고, 생산성을 압도적으로 높여줌

• 클코가 이 파일을 읽어 프로젝트의 아키텍처, 코딩 규칙, 작업 절차 등을 깊이있게 파악함

• 파일을 파악한 후, 요구사항에 맞춰 더 정확하고 관련성 높은 답변을 제공

• LLM은 컨텍스트 윈도우 사이즈의 제약이 있어 매 요청이 Stateless

  • CLAUDE.md 를 통해 매 요청을 반복해서 설명할 필요가 없어지게되는 것

작성법

• 별도 포맷을 따로 없지만, 최소한 지켜야하는 포맷은 있음

• # 로 제목을 구분해서 제목별로 적당한 지시하기

  • 제목만 잘 구분한다면 이후 내용은 자연어로 명확한 지시 정도만 해두면 됨

• 특별한 구조가 없더라도 클코는 CLAUDE.md 문맥을 이해할 수 있음

// 예시
# CLAUDE.md
이 파일은 이 저장소의 코드 작업을 할 때 Claude Code(claude.ai/code)에 대한 지침을 제공합니다.
# 프로젝트 개요
이 프로젝트는 Next.js 15.2.4 와 React 19로 구축된 암호화폐 순위 대시보드입니다. 가격, 시가 총액,
거래량 및 24시간 변동을 포함하여 상위 암호화폐에 대한 실시간 정보를 표시합니다.

어떤 정보를 포함해야할까?

너무 많은 내용을 CLAUDE.md 에 입력하면 클코가 실질적인 문제 해결에 쓸 콘텍스트 윈도우를 손해볼 수 있음 꼭 입력해야 할 내용만 입력하는 것이 좋다.

• 자주 사용하는 bash 명령어

• 핵심 파일 및 유틸리티 함수

• 코드 스타일 가이드라인

• 테스트 지침

• 저장소 에티켓

  • ex: 브랜치 이름 지정, 병합(merge), 리베이스(rebase) 등

• 개발자 환경 설정

  • pyenv 사용, 작동하는 컴파일러 등

• 프로젝트에 특정한 예상치 못한 동작이나 경고

• 클코가 기억했으면 하는 기타 정보

• 일괄적으로 사용하고 싶은 라이브러리에 대한 정보

• 또는 아키텍처에 대한 정보

# 사용할 기술 정리
- **테이블 제작할 떄** 꼭 tanstack table 사용
- **폼 제작할 때** 꼭 tanstack form 사용

# 프로젝트 아키텍처
(대충 구조 트리 복붙)

CLAUDE.md 파일 종류 3가지

세부 목적에 따라 3가지로 분류하여 사용 가능

프로젝트 메모리 (./CLAUDE.md)

• 프로젝트 루트에 위치

• 팀 전체에 적용할 규칙과 정보를 담음

  • 프로젝트 아키텍처: 프로젝트 구조와 핵심 구성 요소에 대한 상위 수준의 설명

  • 코딩 표준: 특정 스타일 가이드, 명명 규칙, 서식 규칙

  • 일반적인 워크플로: 애플리케이션 빌드, 테스트, 배포 지침

로컬 프로젝트 메모리 (./claude.local.md)

• 개인적인 프로젝트 관련 설정을 위한 파일

• 팀과 공유하지 않음

• 개인 설정이 원격 저장소에 커밋되는것을 방지하기 위해 .gitignore 에 추가

  • 샌드박스 URL

  • 개인 API 키 또는 테스트 데이터

  • 자신에게 유용한 맞춤형 명령어

사용자 메모리 (~/.claude/CLAUDE.md)

• 홈 디렉토리에 위치

• 모든 프로젝트에 적용되는 전역 설정

  • 일반적인 코드 스타일 선호도 (2칸 들여쓰기 등)

  • 개인 도구를 위한 단축키

CLAUDE.md 파일 관리 노하우

늘 다듬고 주기적으로 관리해야함

클로드 코드를 쓰면서 바로 수정하기

• # 키를 눌러 클로드 코드에 지시를 내리게 되면, 해당 내용이 CLAUDE.md 에 자동으로 통합됨

• IMPORTANT 또는 YOU MUST 등 강조 표현을 사용하면 클코가 지시사항을 더 잘지켜줌

• /compact 콘텍스트 내용을 압축할 때, 강조 키워드를 적은 내용은 다음 콘텍스트에도 살아남을 가능성이 높아짐

클로드 코드에게 주기적으로 관리하라고 하기

• 하나의 대화가 끝날 때마다 클로드 코드에 현재까지 대화 내용을 기반으로 CLAUDE.md 파일에 추가할만한 내용을 추천해달라 하고, 내용을 확인한 다음 추가해달라고 하는 방식

// Prompt
지금까지 대화를 기반으로 CLAUDE.md에 추가할 만한 내용을 추천해줘

클로드 코드에게 파일을 정리하라 하기

• 클로드가 CLAUDE.md 파일에 추가할 내용을 작업할 때는 현재 콘텍스트의 내용을 기준으로 작성하기 때문에 프로젝트 전반적인 관점에서 필요하지 않은 내용이 과도하게 추가될 때가 있음

  • 이런 작업이 반복되면 파일이 과하게 커지고, 콘텍스트를 낭비하게 됨

• 가끔은 클로드코드에 CLAUDE.md 파일을 정리해달라 요청

// Prompt
CLAUDE.md 파일이 너무 커지고 있는것 같아. 프로젝트 전반적으로 다시 이해하고 CLAUDE.md에 
필요없는 내용은 삭제하고 과도한 내용은 축소하고 싶어, 수정된 내용을 추천해줘 

클로드 코드는 CLAUDE.md를 어떻게 읽을까?

• 클코는 현재 프로젝트 위치에서 시작해 루트 디렉토리까지 거슬러 올라가며 발견하는 모든 CLAUDE.md 파일을 읽음 (재귀적)

• 프로젝트의 메인 CLAUDE.md 에 과도하게 많은 내용을 정리할 필요 없이 하위 폴더별로 상세 스펙을 각각의 CLAUDE.md 파일로 정리 가능

• 클코가 실행될 때 모든 하위 폴더의 CLAUDE.md 를 즉시 읽어들이지 않고 필요할때만 읽기 때문에 컨텍스트 낭비 방지 가능