← 블로그

클로드 코드 CLAUDE.md 완전 가이드: 반복 설명 없애기

2026년 10월 8일

새 세션마다 프로젝트 규칙을 다시 설명하는 번거로움을 CLAUDE.md 하나로 끝낼 수 있습니다. 설정 방법부터 팀 공유까지 실전 가이드입니다.

CLAUDE.md는 클로드 코드(Claude Code)가 새 세션을 열 때 가장 먼저 읽는 프로젝트 지시 파일입니다. 이 파일 하나에 코딩 컨벤션, 금지 패턴, 팀 용어를 정의해 두면, 새 세션을 시작할 때마다 같은 맥락을 처음부터 설명하는 번거로움이 사라집니다. 개인 작업자에게도, 여러 명이 함께 쓰는 팀에서도 AI 세션의 일관성을 유지하는 가장 직접적인 방법입니다.

CLAUDE.md란 무엇이고 왜 필요한가?

클로드 코드는 세션을 새로 열 때마다 컨텍스트를 초기화합니다. 어제 설명한 린트 규칙, 커밋 메시지 형식, 팀에서 쓰지 않기로 한 패턴—모든 것이 사라집니다. 이를 매번 채팅창에 붙여넣는 방식은 느리고, 빠뜨리기 쉬우며, 팀원마다 설명이 미묘하게 달라집니다.

CLAUDE.md는 이 반복을 구조적으로 해결합니다. Claude Code는 작업을 시작하기 전 이 파일을 자동으로 읽어 시스템 컨텍스트에 포함합니다. 개발자가 별도로 지시하지 않아도, 파일이 프로젝트 루트에 있으면 자동으로 불러옵니다.

결과적으로 Claude Code는 채팅을 시작하는 순간부터 프로젝트 규칙을 알고 있습니다. "우리는 탭 들여쓰기를 씁니다"라고 매번 말할 필요가 없어집니다.

CLAUDE.md는 어디에 두어야 하는가?

클로드 코드는 세 위치에서 CLAUDE.md를 불러옵니다.

  • 글로벌 설정 (~/.claude/CLAUDE.md): 모든 프로젝트에 공통으로 적용되는 개인 선호사항입니다. 응답 언어 설정, 개인 코딩 스타일, 자주 쓰는 명령어 단축어 등을 적어두면 어느 프로젝트에서나 동일하게 적용됩니다.
  • 프로젝트 루트 (./CLAUDE.md): 저장소 전체에 적용되는 규칙입니다. 팀이 공유하는 코딩 컨벤션, 아키텍처 패턴, 주의사항 등을 담습니다. 가장 자주 활용되는 위치입니다.
  • 서브디렉터리 (예: ./frontend/CLAUDE.md): 특정 하위 디렉터리에만 적용됩니다. 프론트엔드와 백엔드가 혼재하는 모노레포에서 영역별 규칙을 별도로 관리할 때 유용합니다.

불러오는 순서는 글로벌 → 프로젝트 루트 → 서브디렉터리 순입니다. 나중에 읽힌 파일이 이전 설정을 덮어쓸 수 있으므로, 하위 파일에서 예외 규칙을 지정하는 방식으로 활용할 수 있습니다.

CLAUDE.md에 무엇을 적어야 하는가?

CLAUDE.md는 마크다운으로 작성합니다. Claude Code가 실제 행동을 바꾸도록 만드는 내용이 좋습니다. 추상적인 원칙보다 구체적인 지시가 효과적입니다.

실제로 효과가 높은 항목들:

  • 프로젝트 개요: 저장소의 목적, 주요 기술 스택, 핵심 진입점 파일
  • 코딩 컨벤션: 들여쓰기 방식(탭/스페이스), 네이밍 규칙, 선호 패턴
  • 금지 사항: 사용하지 않아야 할 패턴, 금지된 라이브러리, 피해야 할 접근법
  • 명령어 참조: 빌드, 테스트, 실행, 배포 명령어
  • 팀 맥락: 아직 문서화되지 않은 결정, 레거시 코드 주의사항, 팀 고유 용어

실제 파일은 아래와 같은 형태입니다.

# 프로젝트 개요
TypeScript REST API 서버. 진입점: src/index.ts.

## 기술 스택
Node.js 20 / TypeScript 5 / PostgreSQL / Vitest

## 코딩 컨벤션
들여쓰기 스페이스 2칸, any 타입 금지

## 주요 명령어
npm run dev / npm test / npm run build

## 금지 사항
moment.js 금지 → date-fns 사용

너무 길게 쓰면 중요한 내용이 묻힐 수 있습니다. 핵심만 간결하게 담고, 자세한 내용은 @import 문법으로 별도 파일에 분리하는 방식이 효과적입니다.

팀에서 CLAUDE.md를 어떻게 관리하는가?

CLAUDE.md는 일반 텍스트 파일이므로 git으로 버전을 관리합니다. 저장소에 커밋해 두면 팀 전원이 동일한 AI 컨텍스트를 공유합니다.

팀 운영 시 권장하는 방식:

  • 저장소에 커밋하기: CLAUDE.md를 .gitignore에 넣지 않습니다. 팀의 공통 컨벤션이므로 코드와 함께 관리합니다.
  • PR 리뷰 포함: CLAUDE.md 변경도 일반 코드 변경과 동일하게 리뷰를 거칩니다. AI에게 주는 지시가 바뀌는 것이므로 팀 합의가 필요합니다.
  • 개인 설정 분리: 개인 선호사항은 ~/.claude/CLAUDE.md에 따로 관리합니다. 저장소에는 팀 공통 내용만 담습니다.
  • 변경 이유 명시: 특정 패턴을 금지하는 이유를 간략히 적어두면 새 팀원이 맥락을 파악하는 데 도움이 됩니다.

모노레포라면 루트 CLAUDE.md에 전체 공통 규칙을, 각 패키지 디렉터리에는 해당 패키지 고유 규칙을 담아 계층적으로 관리할 수 있습니다.

@import로 파일을 어떻게 분리하는가?

CLAUDE.md가 길어지면 @파일명 문법으로 외부 파일을 불러올 수 있습니다. CLAUDE.md는 목차 역할을 하고, 세부 내용은 별도 파일로 관리하는 방식입니다.

예를 들어 CLAUDE.md에 아래와 같이 작성하면:

@docs/conventions.md
@docs/architecture.md
@docs/commands.md

Claude Code는 세션 시작 시 나열된 파일들을 함께 읽습니다. 규칙을 주제별로 나눠 관리할 수 있어, 팀 내에서 담당 영역별로 파일을 분리해 운영하는 방식도 가능합니다.

경로는 CLAUDE.md 파일 기준 상대 경로로 작성합니다. 불러오는 파일들도 저장소에 포함되어 있어야 합니다.

CLAUDE.md를 어떻게 시작하면 좋은가?

처음부터 완벽하게 만들 필요는 없습니다. 작게 시작해서 불편함을 느낄 때마다 추가하는 방식이 현실적입니다.

첫 번째 버전에 넣을 항목:

  1. 프로젝트 한 줄 설명
  2. 주요 기술 스택 (언어, 프레임워크, 런타임)
  3. 자주 쓰는 명령어 두세 가지
  4. 가장 최근에 Claude Code에 반복 설명한 규칙 한두 가지

그 이후는 사용하면서 보완합니다. Claude Code와 작업하다가 "또 이 내용을 설명했네"라는 생각이 드는 순간이 CLAUDE.md에 추가할 타이밍입니다.

글로벌 설정인 ~/.claude/CLAUDE.md부터 만들어도 좋습니다. 어떤 프로젝트에서도 공통으로 원하는 사항—예를 들어 응답 언어를 한국어로 유지하거나, 특정 코드 스타일을 기본값으로 잡는 것—을 먼저 정의하면 즉시 효과를 확인할 수 있습니다. 이후 프로젝트별 CLAUDE.md를 추가하면 글로벌 설정 위에 프로젝트 규칙이 쌓이는 방식으로 동작합니다.


PlinthPrep는 Anthropic과 무관한 독립 CCA-F 시험 준비 사이트입니다. 이 글은 공개 문서를 바탕으로 작성되었습니다. CCA-F 시험을 준비 중이라면 PlinthPrep에서 연습문제와 학습 자료를 확인해 보세요.

자주 묻는 질문

CLAUDE.md란 무엇인가?
CLAUDE.md는 Claude Code가 세션을 열 때 자동으로 읽는 프로젝트 지시 파일입니다. 코딩 컨벤션, 금지 패턴, 명령어 참조 등을 이 파일에 적어두면 매 세션마다 같은 내용을 반복 설명하지 않아도 됩니다. 프로젝트 루트에 파일을 두면 Claude Code가 세션 시작 시 자동으로 불러오므로 별도 설정이 필요하지 않습니다.
CLAUDE.md는 어디에 저장해야 하는가?
CLAUDE.md는 세 위치에 둘 수 있습니다. 모든 프로젝트에 적용할 개인 설정은 ~/.claude/CLAUDE.md에, 저장소 전체 팀 규칙은 프로젝트 루트(./CLAUDE.md)에, 특정 하위 디렉터리 규칙은 해당 폴더 안에 둡니다. 불러오는 순서는 글로벌 → 루트 → 서브디렉터리 순이며, 나중에 읽힌 파일이 이전 설정을 덮어씁니다.
팀에서 CLAUDE.md를 어떻게 공유하는가?
CLAUDE.md를 git 저장소에 커밋하면 팀 전원이 동일한 AI 컨텍스트를 공유할 수 있습니다. .gitignore에 넣지 않고 코드와 함께 관리하며, 변경 시 일반 PR과 동일하게 리뷰를 거치는 것이 좋습니다. 개인 선호사항은 ~/.claude/CLAUDE.md에 따로 두어 저장소에는 팀 공통 내용만 포함합니다.
CLAUDE.md의 @import 문법은 어떻게 사용하는가?
CLAUDE.md 안에 @docs/conventions.md 형식으로 작성하면 Claude Code가 세션 시작 시 해당 파일도 함께 읽습니다. 이 방식으로 CLAUDE.md는 목차 역할을 하고 세부 내용은 별도 파일로 분리해 관리할 수 있습니다. 경로는 CLAUDE.md 기준 상대 경로로 작성하며, 불러오는 파일도 저장소에 포함되어 있어야 합니다.

이 글 공유하기

Plinth Prep는 독립적인 학습 자료이며 Anthropic과 제휴, 보증, 후원 관계가 없습니다. 연습 문제는 Plinth Prep가 직접 제작한 것이며 실제 시험 문제를 옮긴 것이 아닙니다.