Claude에 컨텍스트 제공: CLAUDE.md 및 더 나은 프롬프트

Claude Code는 기본 설정으로도 잘 작동하지만, 프로젝트의 규칙을 알고 몇 가지 프롬프팅 습관을 채택하면 눈에 띄게 더 효과적입니다. 이 가이드는 둘 다를 다룹니다.

1부 — CLAUDE.md: 프로젝트의 메모리

개요

CLAUDE.md는 Claude가 해당 디렉토리의 모든 세션 시작 시 자동으로 읽는 일반 마크다운 파일입니다. 첫 날 아침 유능한 새 팀원에게 줄 브리핑이라고 생각하면 됩니다: 팀이 일하는 방식, 피해야 할 것, 중요한 부분이 어디에 있는지.

프롬프트에서 이를 참조하거나 수동으로 첨부할 필요가 없습니다. 파일이 존재하면 Claude가 이미 읽었습니다.

위치

Claude는 여러 위치를 확인하고 광범위에서 구체적으로 찾은 내용을 병합합니다:

위치	범위	용도
`~/.claude/CLAUDE.md`	머신의 모든 프로젝트	개인 설정 (예: "pnpm을 사용하고 npm은 사용하지 않음" 또는 "항상 테스트 제안")
`<repo-root>/CLAUDE.md`	이 프로젝트	아키텍처, 규칙, 명령어. 이것이 주요 파일입니다.
`<subdir>/CLAUDE.md`	해당 하위 디렉토리	모듈별 규칙 (예: `frontend/` vs `api/`의 다른 규칙)

대부분의 팀은 프로젝트 루트 파일만 필요합니다. git에 커밋하여 전체 팀이 이점을 얻도록 하세요.

로드 방식 (및 비용)

CLAUDE.md는 세션 시작 시 한 번 읽혀 Claude의 시스템 프롬프트에 그대로 배치됩니다. 요약이나 잘림이 없으며, 각 턴마다 디스크에서 다시 읽지 않습니다. 같은 내용이 전체 대화 동안 컨텍스트에 유지됩니다. 세션 중에 파일을 편집하면 새 세션을 시작할 때까지 변경 사항이 적용되지 않습니다.

Claude for Enterprise 고객의 경우, 비용 구조가 "모든 요청에서 로드"보다 낫습니다. Claude Code는 Anthropic의 프롬프트 캐싱을 시스템 프롬프트(CLAUDE.md 포함)에 적용합니다. 세션의 첫 요청은 파일의 전체 입력 토큰 가격을 지불합니다. 약 5분 이내의 후속 요청은 캐시에 히트하여 훨씬 낮은 캐시 읽기 요금으로 청구됩니다. 캐시는 콘텐츠 주소 지정이므로 CLAUDE.md의 모든 변경은 캐시를 무효화하고 다음 요청은 전체 가격을 지불합니다.

실제로 이는 상당한 크기의 CLAUDE.md가 세션당 한 번, 그리고 캐시 만료에 충분한 유휴 시간 후 한 번씩 전체 토큰을 소비한다는 의미입니다. 메시지당 한 번이 아닙니다. 컨텍스트 윈도우 공간과 신호 대 잡음 비율을 위해 파일을 간결하게 유지하는 것이 좋지만, 메시지당 지출을 제어하기 위해 줄을 제한할 필요는 없습니다. Enterprise 사용 대시보드에서 파일의 풋프린트는 표준 입력 토큰보다는 캐시 읽기 토큰으로 거의 전부 표시됩니다.

시작하기: `/init` 실행

모든 프로젝트에서 /init을 입력하세요. Claude가 코드베이스를 탐색하고 CLAUDE.md를 작성합니다. 빌드 명령어, 테스트 명령어, 구조 개요, 감지된 규칙을 포함합니다. 초안을 검토하고, 부정확한 부분을 제거하고, 커밋하세요. 약 5분이 소요되며 영구적으로 보상됩니다.

실제로 포함할 내용

짧고 신호가 밀집된 파일을 목표로 하세요. 최대 수백 줄 정도입니다. 모든 줄이 모든 요청에서 컨텍스트에 로드되므로 각 줄은 비용을 들일 가치가 있어야 합니다.

포함할 가치가 있는 것:

명령어 — 빌드, 테스트, 린트, 로컬 실행 방법. Claude가 이를 실행하므로 정확성이 중요합니다.
규칙 — 명명, 오류 처리, 파일 레이아웃, "X를 사용하고 Y는 사용하지 않음" 결정.
3문장으로 된 아키텍처 — 주요 부분이 무엇이고 어떻게 통신하는지.
하드 제약 — 예: "테스트에서 프로덕션 데이터베이스에 쓰지 마세요", "모든 API 경로에 인증 미들웨어 필요", "generated/를 편집하지 마세요".
알려진 함정 — 모든 새 엔지니어가 걸려드는 문제.

포함할 가치가 없는 것:

전체 API 문서 (Claude가 코드를 직접 읽을 수 있음).
변경 로그 또는 히스토리.
파일 트리에서 이미 명백한 모든 것.
팀이 실제로 따르지 않는 열망적인 규칙.

업데이트 빈도

사양이 아닌 살아있는 온보딩 문서처럼 취급하세요.

/init 후 — 생성된 초안을 정리하기 위해 한 번 검토하세요.
Claude가 두 번 뭔가 잘못할 때 — 규칙이 누락되었다는 신호입니다. 이를 해결하기 위해 한 줄을 추가하세요.
규칙이 변경될 때 — 예: 새 프레임워크, 테스트 러너, 또는 린트 규칙 세트.
분기별 검토 — 오래된 지침이 없는 것보다 나쁘므로 오래된 항목을 삭제하세요.

세션 중에도 추가할 수 있습니다: # 다음에 지침을 입력하세요 (예: # 항상 async/await를 사용하고 .then()은 사용하지 마세요). Claude가 올바른 CLAUDE.md에 추가하도록 제안합니다.

2부 — Claude Code에서 보상받는 프롬프팅 습관

이는 일반적인 프롬프트 엔지니어링 팁이 아닙니다. Claude가 실제 코드베이스를 읽고 편집할 때 가장 중요한 습관입니다.

1. 단계가 아닌 결과를 명시하세요

Claude는 코드베이스 자체를 탐색할 수 있습니다. 무엇을 원하고 왜인지 말하고, 어디서인지는 Claude가 파악하도록 하세요.

❌ "userService.ts를 열고, validate 함수를 찾고, 42번 줄에 null 체크를 추가하세요."

✅ "이메일이 없는 사용자가 검증 단계에서 충돌을 일으키고 있습니다. 이를 우아하게 처리하고 테스트를 추가하세요."

2. 오류를 그대로 제공하세요

요약하지 말고 전체 스택 트레이스를 붙여넣으세요. 정확한 파일명, 줄 번호, 메시지가 Claude가 올바른 위치를 빠르게 찾을 수 있게 합니다.

3. 계획 모드로 큰 작업의 범위를 정하세요

2개 이상의 파일을 건드리는 모든 것에 대해 Shift+Tab을 눌러 계획 모드로 들어가세요:

"공개 API에 속도 제한을 추가하는 방법을 계획하세요. 아직 아무것도 변경하지 마세요."

계획을 검토하고, 대화에서 조정한 다음, 모드를 전환하고 "1단계를 수행하세요"라고 말하세요. 이는 오해가 12개 파일 diff로 변하기 전에 포착합니다.

4. 이미 알고 있는 파일을 지적하세요

Claude는 코드베이스를 자체적으로 검색할 수 있지만, 이미 관련 파일을 알고 있다면 말하세요. 더 빠르고 토큰을 적게 사용합니다. @를 사용하여 경로를 참조하세요. 예: @src/auth/login.ts.

5. "완료"가 무엇처럼 보이는지 말하세요

예: "테스트 통과", "다른 핸들러의 스타일과 일치", "새 종속성 없음". 수용 기준을 미리 명시하는 것이 여러 번의 수정 라운드보다 효율적입니다.

6. 대화당 한 작업; 그 사이에 `/clear`

긴 세션은 잡음을 축적합니다. "로그인 버그 수정"에서 "청구 모듈 리팩토링"으로 전환할 때, /clear를 실행하고 새로 시작하세요. CLAUDE.md가 지속적인 컨텍스트를 전달하므로 채팅 히스토리는 필요하지 않습니다.

7. 검색 엔진이 아닌 동료처럼 수정하세요

첫 번째 답변이 벗어났다면, 전체 요청을 다시 표현할 필요가 없습니다. 무엇이 잘못되었는지 간단히 말하세요. 예: "이것은 공개 API를 변경합니다. 서명을 같게 유지하세요." Claude는 나머지는 유지하고 그 지점만 조정합니다.

빠른 참조

원하는 것…	이렇게 하세요
시작 `CLAUDE.md` 생성	`/init`
Claude가 사용 중인 메모리 확인	`/memory`
세션 중에 규칙 추가	`# <your rule>` 입력
프로젝트 메모리는 유지하고 새로 시작	`/clear`
프롬프트에서 특정 파일 참조	`@path/to/file`