빠른 답변
CLAUDE.md는 Claude Code가 context로 load할 수 있는 project instruction file입니다. project structure, commands, coding conventions, testing expectations, security boundaries 및 collaboration rules를 두기에 좋습니다.
이는 enforcement mechanism이 아닙니다. Claude Code는 이를 guidance로 읽습니다. rule이 특정 time에 실행되어야 한다면 CLAUDE.md에만 의존하지 말고 hooks 또는 tool configuration을 사용하세요.
유용한 CLAUDE.md는 짧고 구체적이며 유지 관리됩니다. 매 session마다 반복할 project facts를 여기에 작성하세요.
이 내용이 필요한 경우
- Claude Code가 같은 project structure 또는 commands를 반복해서 질문함
- team에 shared testing, style 또는 safety rules가 필요함
- 반복 context와 token usage를 줄이고 싶음
- Claude Code가 repository-specific conventions를 계속 놓침
- 다른 agents 또는 teammates의 onboarding을 빠르게 하고 싶음
주요 개념
권장 내용
CLAUDE.md를 간결한 project handbook으로 작성하세요.
- project의 용도와 중요한 directories의 위치
- 일반적인 build, test 및 formatting commands
- editing 전에 지켜야 할 architecture boundaries
- finishing 전에 실행할 가장 빠른 checks
- 노출해서는 안 되는 secrets, logs 또는 private config
- documentation, test, naming 및 error-handling conventions
일반적인 실수
CLAUDE.md를 system prompt 또는 hard permission layer로 취급함- 너무 길게 작성하여 context cost를 늘리고 따르기 어렵게 만듦
- 오래된 deployment notes, temporary TODOs 및 outdated decisions를 계속 추가함
- file에 API Keys, tokens, cookies 또는 private config를 넣음
CLAUDE.md,AGENTS.md, Cursor Rules에 서로 충돌하는 instructions를 유지함
BetterToken 정보
project가 BetterToken을 사용한다면CLAUDE.md로 Claude Code에는 Anthropic-compatible https://www.bettertoken.ai을 사용하고 Codex 및 external tools에는 OpenAI-compatible https://www.bettertoken.ai/v1을 사용한다고 안내할 수 있습니다.
실제 API Keys를 CLAUDE.md에 넣지 마세요. local environment variables, local config files 또는 protected secret system에 저장하세요.
관련 문서
- Claude Code란 무엇이며 어떻게 작동하나요?
- Claude Code에서 API Key와 Base URL 구성
- Claude Code가 많은 tokens를 사용하는 이유와 cost 줄이기
- Claude Code 설정 가이드