Claude Code는 기본 설정으로도 잘 작동하지만, 프로젝트의 규칙을 알고 몇 가지 프롬프팅 습관을 채택하면 눈에 띄게 더 효과적입니다. 이 가이드는 둘 다를 다룹니다.
1부 — CLAUDE.md: 프로젝트의 메모리
개요
CLAUDE.md는 Claude가 해당 디렉토리의 모든 세션 시작 시 자동으로 읽는 일반 마크다운 파일입니다. 이는 능력 있는 새 팀원이 첫 아침에 받을 브리핑과 같다고 생각하면 됩니다: 팀이 일하는 방식, 피해야 할 것, 중요한 부분이 어디에 있는지.
프롬프트에서 이를 참조하거나 수동으로 첨부할 필요가 없습니다. 파일이 존재하면 Claude는 이미 읽었습니다.
위치
Claude는 여러 위치를 확인하고 광범위에서 구체적으로 병합합니다:
위치 | 범위 | 용도 |
| 컴퓨터의 모든 프로젝트 | 개인 설정 (예: "npm이 아닌 pnpm을 사용합니다" 또는 "항상 테스트를 제안합니다"). |
| 이 프로젝트 | 아키텍처, 규칙, 명령어. 이것이 주요 파일입니다. |
| 해당 하위 디렉토리 (세션 시작 시가 아닌 Claude가 해당 디렉토리의 파일을 읽을 때 필요에 따라 로드됨) | 모듈별 규칙 (예: |
대부분의 팀은 프로젝트 루트 파일만 필요합니다. git에 커밋하여 전체 팀이 이점을 얻도록 하세요.
로드 방식 (및 비용)
작업 디렉토리의 파일과 그 위의 파일은 세션 시작 시 읽혀지고 시스템 프롬프트 직후 사용자 메시지로 Claude에 전달됩니다 (시스템 프롬프트 내에 포함되지 않음). 하위 디렉토리 CLAUDE.md 파일은 나중에 필요에 따라 로드되며, Claude가 해당 하위 디렉토리의 파일을 읽을 때입니다. 요약이나 자르기가 없으며, 각 턴마다 디스크에서 다시 읽지 않습니다. 세션 중에 파일을 편집하면 /compact를 실행하거나 /memory를 통해 열 때 변경 사항이 적용되며, 그렇지 않으면 다음 세션에 적용됩니다.
Claude for Enterprise 고객의 경우, 비용 구조는 "모든 요청에 로드됨"보다 낫습니다. Claude Code는 Anthropic의 프롬프트 캐싱을 CLAUDE.md에 적용합니다. 세션의 첫 요청은 파일의 전체 입력 토큰 가격을 지불합니다. 약 5분 이내의 후속 요청은 캐시에 도달하여 훨씬 낮은 캐시 읽기 요금으로 청구됩니다. 캐시는 콘텐츠 주소 지정되므로 CLAUDE.md의 모든 변경은 캐시를 무효화하고 다음 요청은 전체 가격을 지불합니다.
실제로 이는 상당한 크기의 CLAUDE.md가 세션당 한 번, 그리고 캐시가 만료될 만큼 긴 유휴 시간 후 한 번 전체 토큰을 소비한다는 의미입니다 (메시지당 한 번이 아님). 컨텍스트 윈도우 공간과 신호 대 잡음 비율을 위해 파일을 간결하게 유지하는 것이 여전히 가치가 있지만, 메시지당 지출을 제어하기 위해 순수하게 라인을 제한할 필요는 없습니다. Enterprise 사용 대시보드에서 파일의 풋프린트는 표준 입력 토큰이 아닌 캐시 읽기 토큰으로 거의 전부 표시됩니다.
시작하기: /init 실행
모든 프로젝트에서 /init을 입력하세요. Claude는 코드베이스를 탐색하고 CLAUDE.md를 작성합니다. 빌드 명령어, 테스트 명령어, 구조 개요, 감지된 규칙을 포함합니다. 초안을 검토하고, 부정확한 부분을 제거하고, 커밋하세요. 약 5분이 소요되며 영구적으로 보상됩니다.
실제로 포함해야 할 내용
짧고 신호가 밀집된 파일을 목표로 하세요 — 대략 200줄 미만. 모든 라인은 모든 요청에서 컨텍스트에 로드되므로 각 라인은 비용을 들일 가치가 있어야 합니다.
포함할 가치가 있는 것:
명령어 — 빌드, 테스트, 린트, 로컬 실행 방법. Claude가 이를 실행하므로 정확성이 중요합니다.
규칙 — 명명, 오류 처리, 파일 레이아웃, "X를 사용하고 Y는 사용하지 않습니다" 결정.
3문장으로 된 아키텍처 — 주요 부분이 무엇이고 어떻게 통신하는지.
하드 제약 — 예: "테스트에서 프로덕션 데이터베이스에 절대 쓰지 마세요", "모든 API 경로에 인증 미들웨어가 필요합니다", "
generated/를 편집하지 마세요".알려진 함정 — 모든 새 엔지니어가 걸려드는 문제.
포함할 가치가 없는 것:
전체 API 문서 (Claude는 코드를 직접 읽을 수 있습니다).
변경 로그 또는 히스토리.
파일 트리에서 이미 명백한 모든 것.
팀이 실제로 따르지 않는 열망적인 규칙.
업데이트 빈도
이를 사양이 아닌 살아있는 온보딩 문서로 취급하세요.
/init후 — 생성된 초안을 정리하기 위해 한 번 검토하세요.Claude가 두 번 뭔가 잘못할 때 — 이는 규칙이 누락되었다는 신호입니다. 이를 해결하기 위해 한 줄을 추가하세요.
규칙이 변경될 때 — 예: 새 프레임워크, 테스트 러너, 또는 린트 규칙 세트.
분기별 검토 — 오래된 지침은 없는 것보다 나쁘므로 오래된 항목을 삭제하세요.
세션 중에도 추가할 수 있습니다: /memory를 열어 파일을 직접 편집하거나, Claude에게 규칙을 "기억"하도록 요청하면 올바른 CLAUDE.md에 추가됩니다.
2부 — Claude Code에서 효과적인 프롬프팅 습관
이는 일반적인 프롬프트 엔지니어링 팁이 아닙니다. Claude가 실제 코드베이스를 읽고 편집할 때 가장 중요한 습관입니다.
1. 단계가 아닌 결과를 명시하세요
Claude는 코드베이스 자체를 탐색할 수 있습니다. 무엇을 원하고 왜인지 말하고, 어디인지는 Claude가 파악하도록 하세요.
❌ "userService.ts를 열고, validate 함수를 찾고, 42번 줄에 null 체크를 추가하세요."
✅ "이메일이 없는 사용자가 검증 단계에서 충돌을 일으키고 있습니다. 이를 우아하게 처리하고 테스트를 추가하세요."
2. 오류를 그대로 제공하세요
요약하지 말고 전체 스택 트레이스를 붙여넣으세요. 정확한 파일명, 줄 번호, 메시지가 Claude가 올바른 위치를 빠르게 찾을 수 있게 합니다.
3. Plan Mode로 큰 작업의 범위를 정하세요
2개 이상의 파일을 건드리는 모든 작업의 경우, Shift+Tab을 두 번 눌러 plan mode로 전환하고 (첫 번째 누름은 acceptEdits로 진입) 다음을 요청하세요:
"공개 API에 속도 제한을 추가하는 방법을 계획하세요. 아직 아무것도 변경하지 마세요."
계획을 검토하고, 대화에서 조정한 후, 모드를 전환하고 "1단계를 수행하세요"라고 말하세요. 이는 오해가 12개 파일 diff로 변하기 전에 포착합니다.
4. 이미 알고 있는 파일을 지적하세요
Claude는 코드베이스를 자체적으로 검색할 수 있지만, 이미 관련 파일을 알고 있다면 말하세요 — 더 빠르고 토큰을 적게 사용합니다. @를 사용하여 경로를 참조하세요. 예: @src/auth/login.ts.
5. "완료"가 무엇인지 말하세요
예: "테스트 통과", "다른 핸들러의 스타일과 일치", "새 종속성 없음". 수용 기준을 미리 명시하는 것이 여러 번의 수정 라운드보다 효율적입니다.
6. 대화당 한 작업; 그 사이에 /clear 실행
긴 세션은 잡음을 축적합니다. "로그인 버그 수정"에서 "청구 모듈 리팩토링"으로 전환할 때, /clear를 실행하고 새로 시작하세요. CLAUDE.md가 지속적인 컨텍스트를 전달하므로 채팅 히스토리는 필요하지 않습니다.
7. 검색 엔진이 아닌 동료처럼 수정하세요
첫 번째 답변이 틀렸다면, 전체 요청을 다시 표현할 필요가 없습니다. 단순히 무엇이 잘못되었는지 말하세요 — 예: "이는 공개 API를 변경합니다. 서명을 동일하게 유지하세요." Claude는 나머지는 모두 유지하고 해당 지점만 조정합니다.
빠른 참조
원하는 것… | 이렇게 하세요 |
시작 |
|
Claude가 사용 중인 메모리 확인 |
|
세션 중에 규칙 추가 |
|
프로젝트 메모리는 유지하면서 새로 시작 |
|
프롬프트에서 특정 파일 참조 |
|