MD Reader

CLAUDE.md 파일이란? 하는 일과 적어야 할 내용

수정일:

CLAUDE.md는 Anthropic의 코딩 에이전트 Claude Code에게 주는 지시문을 적어 두는 텍스트 파일입니다. Claude Code가 세션을 시작할 때마다 읽기 때문에, 테스트 명령이나 프로젝트 규칙을 매번 다시 말하지 않아도 됩니다.

마크다운으로 쓴 문서이고 파일 자체가 무언가를 실행하지는 않으니, 열어서 읽는 것은 안전합니다. 고칠 때는 조심하세요. 에이전트가 바뀐 내용대로 움직입니다.

무엇을 적나요

정해진 형식은 없습니다. 가장 쓸모 있는 내용은 코드만 읽어서는 에이전트가 알 수 없는 것입니다.

작게 쓰면 이런 모습입니다.

# CLAUDE.md

## 명령어
- 테스트: npm test (끝내기 전에 꼭 실행)

## 규칙
- /generated 폴더의 파일은 고치지 않기
- 화면에 보이는 문구는 src/i18n에 두기

Anthropic 공식 문서는 200줄 아래로 유지하라고 권합니다. 길어질수록 맥락을 많이 차지하고 지시를 덜 따르기 때문입니다.

어디에 두나요

파일 용도
프로젝트 맨 위 폴더의 CLAUDE.md 프로젝트 지시문. 보통 git으로 함께 공유
하위 폴더의 CLAUDE.md 그 폴더에서 작업할 때 읽는 지시문
~/.claude/CLAUDE.md 모든 프로젝트에 적용할 내 취향
CLAUDE.local.md 한 프로젝트에만 쓰는 개인 메모. git에는 넣지 않음

Claude Code를 실행한 폴더보다 위에 있는 파일도 함께 읽습니다. 서로 덮어쓰지 않고 합쳐지므로, 내용이 어긋나면 에이전트가 헷갈릴 수 있습니다.

어떻게 만드나요

Claude Code에서 /init을 실행하세요. 프로젝트를 살펴보고 찾아낸 빌드 명령과 규칙으로 초안을 만들어 줍니다. 그다음 에이전트가 알아낼 수 없었던 내용을 직접 더하면 됩니다.

처음부터 있어야 하는 것은 아닙니다. 같은 실수를 두 번 바로잡았을 때가 시작하기 좋은 때입니다. 한 줄만 적어 두면 다음 세션은 그 내용을 알고 시작합니다.

할 수 없는 일

Claude Code는 이 파일을 강제 규칙이 아니라 지침으로 받아들입니다. 대체로 따르지만 반드시 따르는 것은 아닙니다. 절대 일어나면 안 되는 일이 있다면 Anthropic은 도구가 매번 강제하는 훅(hook)을 쓰라고 안내합니다. 문장에 "IMPORTANT"를 붙이는 것으로는 잘 해결되지 않습니다.

비밀번호나 API 키는 적지 마세요. 프로젝트 파일은 보통 코드와 함께 커밋되므로, 프로젝트를 볼 수 있는 사람이면 누구나 읽을 수 있습니다.

AGENTS.md와의 관계

AGENTS.md는 Codex 같은 다른 도구에서 비슷한 역할을 하는 파일이고, Claude Code도 프로젝트에 이미 있는 것을 읽을 수 있습니다. 함께 보이는 다른 파일은 코딩 에이전트가 만드는 .md 파일 안내에서 볼 수 있습니다.

휴대폰에서 읽으려면

일반 텍스트 앱으로 열면 #과 ** 기호가 그대로 보입니다. Android에서 서식대로 읽는 방법은 이렇습니다.

  1. 파일을 휴대폰으로 보냅니다. Claude Code는 보통 컴퓨터에서 돌아가므로 Google Drive, 이메일 첨부, USB 케이블을 쓰면 됩니다.
  2. 파일을 눌러 MD 리더를 고르거나, 앱에서 파일 열기를 누릅니다.

Google Play에서 받기

제목, 표, 코드 블록이 서식대로 보이고, 목차로 원하는 부분으로 바로 갈 수 있습니다. 지시문 파일에 자주 나오는 <example> 같은 태그도 사라지지 않고 적힌 그대로 보입니다. Google Drive에서 여는 방법은 Google Drive에서 .md 파일 열기를 참고하세요.

MD 리더는 Claude Code와 연결되지 않고 컴퓨터와 동기화하지도 않으므로, 지금 보는 것은 복사본입니다. 파일이 바뀌면 다시 보내세요. 편집으로 복사본을 고칠 수는 있지만, 컴퓨터로 다시 보내기 전에는 Claude Code가 바뀐 내용을 볼 수 없습니다.

함께 보면 좋은 가이드