CLAUDE.md의 역할

Claude Code에서 CLAUDE.md가 어떤 역할을 하는지, 프로젝트 메모리로 무엇을 적어야 하는지, import와 계층 구조를 어떻게 운영하는지 설명한다.
Tags:

개요

CLAUDE.md는 Claude Code가 프로젝트 작업을 시작할 때 참고하는 메모리 파일이다. 저장소의 목적, 주요 명령어, 코딩 규칙, 테스트 절차, 수정하면 안 되는 영역처럼 매번 프롬프트에 반복해서 적기 어려운 정보를 문서로 남겨 둔다.

Claude Code는 코드베이스를 읽고 현재 상태를 파악할 수 있지만, 팀의 암묵적인 규칙이나 운영상 제약까지 자동으로 알지는 못한다. CLAUDE.md는 이런 배경 지식을 명시적으로 제공하여 답변과 작업 방식의 일관성을 높이는 역할을 한다.

CLAUDE.md가 필요한 경우

다음과 같은 규칙이 있는 프로젝트라면 CLAUDE.md를 두는 것이 좋다.

  • 빌드, 린트, 테스트, 로컬 실행 명령이 정해져 있다.
  • 특정 디렉토리나 파일은 승인 없이 수정하면 안 된다.
  • 신규 패키지 추가, DB 마이그레이션, API 스키마 변경에 별도 절차가 있다.
  • 프론트엔드, 백엔드, 테스트 코드 작성 방식에 팀 규칙이 있다.
  • 코드 변경 후 반드시 실행해야 하는 검증 명령이 있다.
  • 민감 정보, 고객 데이터, .env 파일 처리 규칙이 있다.

특히 여러 사람이 같은 저장소에서 Claude Code를 사용한다면, 팀 공통 규칙은 개인 프롬프트가 아니라 저장소의 CLAUDE.md에 남기는 편이 안전하다.

메모리 파일의 종류

Claude Code는 용도에 따라 여러 위치의 메모리 파일을 사용할 수 있다.

종류 위치 주요 용도 공유 범위
조직 메모리 macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux: /etc/claude-code/CLAUDE.md
Windows: C:\ProgramData\ClaudeCode\CLAUDE.md		 회사 표준, 보안 정책, 컴플라이언스 규칙 조직 사용자
프로젝트 메모리 ./CLAUDE.md 저장소의 구조, 명령어, 팀 코딩 규칙 저장소를 공유하는 팀
사용자 메모리 ~/.claude/CLAUDE.md 개인 선호, 자주 쓰는 도구, 응답 스타일 본인
프로젝트 로컬 메모리 ./CLAUDE.local.md 개인별 프로젝트 설정 본인

실무에서는 팀 규칙은 ./CLAUDE.md에 두고, 개인 취향은 ~/.claude/CLAUDE.md나 별도 개인 파일 import로 분리하는 방식이 적합하다. 개인 설정을 프로젝트 메모리에 섞으면 팀 전체에 불필요한 지시가 적용될 수 있다.

로드 방식과 우선순위

Claude Code는 시작 시점에 메모리 파일을 컨텍스트로 읽어 들인다. 현재 작업 디렉토리에서 시작해 상위 디렉토리로 올라가며 발견한 CLAUDE.md 파일도 참고한다.

대형 모노레포에서는 루트에 공통 규칙을 두고, 하위 서비스 디렉토리에 더 구체적인 CLAUDE.md를 둘 수 있다. 예를 들어 다음 구조에서는 루트 규칙과 API 서비스 규칙을 분리할 수 있다.

repo/
  CLAUDE.md
  services/
    api/
      CLAUDE.md
    web/
      CLAUDE.md

services/api에서 작업하면 루트의 공통 규칙과 API 디렉토리의 세부 규칙을 함께 활용할 수 있다. 다만 하위 디렉토리마다 규칙을 과도하게 만들면 어떤 지시가 적용되는지 추적하기 어려워지므로, 공통 규칙과 예외 규칙을 명확히 나누어야 한다.

생성 방법

Claude Code에서는 /init 명령으로 프로젝트용 CLAUDE.md 초안을 만들 수 있다.

/init

초안을 만든 뒤에는 반드시 실제 프로젝트 기준으로 수정해야 한다. README, 패키지 설정, 빌드 설정, 테스트 설정을 확인하지 않고 만든 명령어는 잘못된 자동화로 이어질 수 있다.

다음 순서로 다듬는 것이 좋다.

  1. 프로젝트 목적과 주요 기술 스택을 적는다.
  2. 실제로 동작하는 설치, 실행, 테스트, 빌드 명령을 적는다.
  3. 수정 금지 영역과 승인 필요 작업을 적는다.
  4. 코드 스타일과 아키텍처 규칙을 구체적인 파일 경로와 함께 적는다.
  5. 보안상 읽거나 출력하면 안 되는 파일 패턴을 적는다.
  6. 오래된 규칙이나 현재와 맞지 않는 명령을 제거한다.

기본 템플릿

아래 예시는 프로젝트 루트의 CLAUDE.md에 넣을 수 있는 기본 구조이다. 대괄호 부분은 실제 프로젝트 정보로 바꾸어야 한다.

# Project Instructions

## Project Overview

- This repository is a [service/library/site] for [target users].
- Main stack: [language/framework/runtime].
- Application code lives in `[path]`.
- Tests live in `[path]`.

## Common Commands

- Install dependencies: `[command]`
- Run locally: `[command]`
- Lint: `[command]`
- Type check: `[command]`
- Unit test: `[command]`
- Build: `[command]`

## Working Rules

- Keep changes scoped to the requested task.
- Do not modify `[path]` without explicit approval.
- Do not add dependencies unless the task requires it.
- After code changes, run the smallest relevant verification command first.
- If a command cannot be run, explain the reason and provide a manual check.

## Code Style

- Follow existing patterns before adding new abstractions.
- Place shared components in `[path]`.
- Keep public API compatibility unless the task explicitly requests a breaking change.

## Security

- Do not read or print `.env`, `.env.*`, private keys, tokens, or customer data.
- Ask before running commands that access external services.
- Do not commit generated secrets or local credentials.

좋은 규칙과 나쁜 규칙

CLAUDE.md의 품질은 문장 수보다 구체성에 좌우된다. Claude Code가 실제 행동으로 옮길 수 있는 기준을 적어야 한다.

나쁜 예시는 다음과 같다.

- 코드를 깔끔하게 작성한다.
- 테스트를 잘 한다.
- 보안을 조심한다.

이 규칙들은 방향은 맞지만 실행 기준이 없다. 다음처럼 명령, 경로, 조건을 함께 적어야 한다.

- React 공용 컴포넌트는 `src/components`에 두고, 페이지 전용 컴포넌트는 `src/pages/*/_components`에 둔다.
- API 라우터를 변경한 뒤에는 `npm run test:api`를 실행한다.
- `.env`, `.env.*`, `secrets/`, `credentials/` 아래 파일은 읽거나 출력하지 않는다.
- DB 마이그레이션 파일을 추가할 때는 `npm run migrate:dry-run` 결과를 먼저 확인한다.

import 활용

CLAUDE.md는 @path/to/file 형식으로 다른 파일을 가져올 수 있다. 긴 설명을 모두 메모리 파일에 붙여 넣기보다, 필요한 문서를 참조하도록 나누면 컨텍스트를 관리하기 쉽다.

# Project Instructions

See @README.md for project overview.
See @docs/architecture.md for architecture decisions.
See @package.json for available npm scripts.

## Team Rules

- Follow @docs/git-workflow.md for branch and pull request conventions.
- Follow @docs/testing.md before changing test strategy.

상대 경로와 절대 경로를 사용할 수 있으며, 개인 설정은 홈 디렉토리의 별도 파일로 분리할 수 있다.

## Personal Preferences

- @~/.claude/my-project-preferences.md

import를 사용할 때는 다음 점을 주의한다.

  • Markdown 코드 블록과 인라인 코드 안의 @path는 import로 처리되지 않는다.
  • import된 파일이 다시 다른 파일을 import할 수 있지만, 과도한 재귀 구조는 피한다.
  • 자주 필요한 핵심 규칙은 CLAUDE.md에 직접 적고, 긴 배경 문서는 링크로 분리한다.
  • 실제로 어떤 메모리가 로드되었는지는 Claude Code의 /memory 명령으로 확인한다.

팀 운영 방식

팀에서 CLAUDE.md를 사용할 때는 문서를 코드처럼 관리해야 한다. 프로젝트 구조나 명령어가 바뀌었는데 메모리 파일이 그대로 남아 있으면 Claude Code가 오래된 지시를 따를 수 있다.

운영 기준은 다음과 같이 정할 수 있다.

  • 빌드, 테스트, 배포 명령이 바뀌면 같은 pull request에서 CLAUDE.md도 수정한다.
  • 팀 전체에 적용되지 않는 개인 취향은 프로젝트 메모리에 넣지 않는다.
  • 금지 규칙은 이유와 범위를 함께 적는다.
  • public/, dist/, build/처럼 생성 산출물은 수정 대상인지 배포 대상인지 명확히 적는다.
  • 민감 정보 파일 패턴은 구체적으로 적고, 출력 금지까지 포함한다.

예를 들어 정적 사이트 프로젝트라면 다음처럼 쓸 수 있다.

## Repository Rules

- Do not edit generated files in `public/` unless the task is deployment-related.
- Prefer local Hugo overrides in `layouts/` or `assets/` instead of modifying `themes/docsy`.
- Validate content changes with `hugo -t docsy` before publishing.
- Keep Korean content under `content/` and preserve existing numbered directory prefixes.

자주 발생하는 문제

실제 명령과 문서가 맞지 않음

가장 흔한 문제는 존재하지 않는 테스트 명령이나 오래된 빌드 명령을 적어 두는 것이다. Claude Code는 메모리의 명령을 신뢰하고 실행하려고 할 수 있으므로, package.json, Makefile, README, CI 설정과 맞는지 확인해야 한다.

너무 많은 내용을 넣음

CLAUDE.md에 설계 문서, 회의록, 전체 README를 모두 붙여 넣으면 시작 컨텍스트가 무거워진다. 항상 필요한 규칙만 직접 적고, 긴 문서는 import나 일반 문서 링크로 분리하는 편이 낫다.

개인 취향을 팀 규칙으로 저장함

개인의 에디터, 별칭, 선호 출력 형식은 팀원이 공유할 필요가 없을 수 있다. 이런 내용은 사용자 메모리나 개인 import 파일로 분리한다.

금지 규칙만 있고 대안이 없음

절대 수정하지 말 것만 적으면 작업이 막힐 수 있다. 가능하면 승인 조건이나 대체 경로를 함께 적는다.

- Do not modify `legacy/payment/` without explicit approval.
- For payment-related changes, add new adapters under `src/payment/adapters/` and keep legacy API compatibility.

점검 체크리스트

CLAUDE.md를 작성한 뒤에는 다음 항목을 확인한다.

  • 프로젝트 목적과 주요 폴더 구조가 적혀 있는가.
  • 설치, 실행, 테스트, 빌드 명령이 실제로 존재하는가.
  • 수정 금지 파일과 승인 필요 작업이 구체적인가.
  • 민감 파일을 읽거나 출력하지 말라는 규칙이 있는가.
  • 팀 공통 규칙과 개인 취향이 분리되어 있는가.
  • 추상적인 표현보다 명령, 경로, 조건이 많은가.
  • import가 너무 깊거나 넓게 연결되어 있지 않은가.
  • 프로젝트 변경에 맞춰 주기적으로 갱신할 담당 기준이 있는가.

정리

CLAUDE.md는 Claude Code에게 프로젝트의 작업 규칙을 알려 주는 운영 문서이다. 좋은 CLAUDE.md는 길고 자세한 설명서가 아니라, Claude Code가 바로 적용할 수 있는 구체적인 명령과 제약의 모음에 가깝다.

팀 공통 규칙은 프로젝트 루트에 두고, 개인 취향은 사용자 메모리나 개인 import로 분리하는 방식이 가장 관리하기 쉽다. 프로젝트가 바뀔 때 CLAUDE.md도 함께 갱신하면, 매 세션마다 같은 설명을 반복하지 않고도 일관된 개발 워크플로를 유지할 수 있다.