Claude Code

Claude Code의 CLAUDE.md 작성 가이드

Claude Code에서 CLAUDE.md의 역할, 포함할 내용, 피할 내용 및 hooks와 MCP의 차이를 알아보세요.

빠른 답변

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을 빠르게 하고 싶음

주요 개념

개념	의미
Project `CLAUDE.md`	보통 repository와 함께 commit하는 shared project instructions
Personal rules	항상 commit할 필요가 없는 user-specific preferences
Local rules	machine-specific notes 또는 temporary preferences
Hooks	tool use 전후로 triggered되는 commands로 enforced behavior에 더 적합함
MCP	external tools 및 data sources이며 project rule file이 아님

권장 내용

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

긴 tutorials, temporary plans 및 one-off task notes는 피하세요. rule이 한 영역에만 적용된다면 범위를 더 좁히세요. behavior를 enforced해야 한다면 hooks를 사용하세요.

일반적인 실수

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://bettertoken.ai을 사용하고 Codex 및 external tools에는 OpenAI-compatible https://bettertoken.ai/v1을 사용한다고 안내할 수 있습니다.

실제 API Keys를 CLAUDE.md에 넣지 마세요. local environment variables, local config files 또는 protected secret system에 저장하세요.