CLAUDE.md와 필수 명령어

 

1. 프로젝트 루트 실행의 중요성

클로드 코드를 실행할 때 가장 먼저 기억해야 할 것은 프로젝트의 루트 디렉토리에서 실행해야 한다는 점입니다.

클로드는 현재 디렉토리를 기준으로 파일을 탐색하고 프로젝트 구조를 파악하기 때문입니다.

만약 하위 디렉토리에서 실행하면, 클로드는 해당 디렉토리의 구조만 인식하게 되어 전체 프로젝트를 제대로 이해하지 못하고 효율적인 플랜 수립이나 코드 생성이 어려워집니다.

 

2. CLAUDE.md: 핵심 컨텍스트 관리 파일

클로드 코드의 성능은 컨텍스트 관리 능력에 크게 좌우됩니다.

여기서 핵심적인 역할을 하는 것이 바로 CLAUDE.md 파일입니다.

프로젝트가 클수록 모든 파일을 읽는 것은 비효율적이므로, CLAUDE.md에 프로젝트 구조를 정리하여 효율성을 높입니다.

 

1) 생성

프로젝트 루트 디렉토리에서 /init 명령어를 실행하면 자동으로 생성됩니다.

• ~/.claude/claude.md 는 모든 프로젝트 공통으로 글로벌하게 적용할 때 사용, (글로벌하게 공통 규칙을 적용)
• projectroot/claude.md 는 해당 프로젝트만 적용할 때 사용 (해당 프로젝트의 아키텍처, 컨벤션)

 

2) 넣어야할 내용

이 파일은 프로젝트의 전반적인 컨텍스트를 넣어야합니다.

• 즉 절대 규칙 (하면 안 되는 것, 꼭 해야 하는 것)
• 아키텍처 개요 (폴더 구조, 기술 스택)
• 빌드 및 테스트 명령어 (개발 서버, 테스트, 배포 명령어)
• 코딩 컨벤션 (네이밍, 규칙 등)
• 도메인 컨텍스트 (비즈니스 용어, 데이터 흐름)

 

3) 구조

절대 규칙, 아키텍처, 빌드/테스트 명령어, 도메인 컨텍스트, 코딩 컨벤션, 핵심 패턴 등을 포함할 수 있습니다.

파일 구조를 트리 형식으로 표현하면 클로드가 이해하기 더 쉽고, 클로드는 이 파일을 읽고 프로젝트의 맥락을 파악하여 작업을 수행합니다.

 

4) 최적화

CLAUDE.md 파일이 너무 커지면 토큰 소모량이 증가하여 비효율적입니다.

따라서 300자 이내로 유지하는 것이 권장되고, 프로젝트 규모가 커진다면, 폴더별로 별도의 CLAUDE.md 파일을 생성하여 관리하는 것이 좋습니다. (ex: API 폴더에는 API 관련 CLAUDE.md, Web 폴더에는 Web 관련 CLAUDE.md)

 

5) 관리

CLAUDE.md는 직접 수정할 수도 있지만, 클로드 코드에게 특정 규칙이나 패턴을 추가해 달라고 요청하면 자동으로 업데이트되도록 할 수도 있습니다. 팀 전체가 동일한 CLAUDE.md를 공유하면 일관된 개발 문화를 유지하는 데 큰 도움이 됩니다.

 

3. 필수 단축키 및 명령어

1) Shift + Tab (플랜 모드 vs. 엑셉트 모드)

• 플랜 모드 (Plan Mode)
  • 클로드가 코드를 직접 실행하거나 파일을 수정하지 않고, 작업 계획을 세우는 모드입니다. 토큰 소모를 줄이고 불필요한 코드 생성을 방지하며, 컨텍스트 윈도우를 효율적으로 관리하는 데 필수적입니다.
• 엑셉트 모드 (Accept Mode)
  • 클로드가 실제로 코드를 작성하고 파일을 수정하는 모드입니다.

토큰 최적화

Plan Mode(/plan)는 코드를 바로 생성하지 않고 계획만 세우는 모드입니다. 

 

불필요한 코드 생성 방지

바로 코딩에 들어가면 방향이 틀렸을 때 생성된 코드 전체가 낭비 토큰이 됩니다.

Plan Mode에서 방향을 먼저 확인하면 "잘못된 코드 생성 → 수정 요청 → 재생성"의 악순환을 끊을 수 있습니다. 실무에서 이 사이클이 2~3번만 반복돼도 토큰 소모가 3배 이상 뻥튀기됩니다.

 

컨텍스트 윈도우 보존

Claude Code는 대화가 길어질수록 이전 컨텍스트를 압축하거나 날리게 됩니다. Plan Mode로 짧은 텍스트 기반 계획을 먼저 세우면, 실제 코딩 단계에서 컨텍스트 윈도우를 코드 생성에 온전히 쓸 수 있습니다.

 

실행 정확도 향상

복잡한 태스크 분해

"이 기능 만들어줘"라고 바로 던지면 Claude가 한 번에 모든 걸 해결하려다 중간에 길을 잃습니다.

Plan Mode에서 Step 1, 2, 3으로 나누고 각 단계를 승인하면서 진행하면 실패율이 크게 줄어듭니다.

 

파일 수정 범위 통제

Plan 없이 실행하면 의도치 않은 파일까지 건드리는 경우가 많습니다.

계획 단계에서 "어떤 파일을 어떻게 수정할 건지" 미리 확인하면 사이드 이펙트를 줄일 수 있습니다.

 

비용 관리 (API 사용 시)

Opus 기준 input/output 토큰 단가가 상당합니다.

Plan Mode에서 계획을 세울 때는 output이 주로 텍스트 계획이라 토큰 소모가 적고, 잘못된 방향으로 수천 줄 코드를 생성하는 것보다 비용 효율이 훨씬 좋습니다.

체감상 Plan → Execute 패턴이 바로 Execute 대비 30~50% 토큰 절감 효과가 있다는 커뮤니티 리포트들이 있습니다.

 

2) ESC (작업 중단 및 되돌리기)

• ESC키 한번 클릭 → 작업 중단
  • 현재 진행 중인 작업을 즉시 중단하고 싶을 때 누릅니다.
• ESC키 두번 클릭 → 되돌리기 (Rewind)
  • 텍스트가 있을 때는 입력 내용 삭제
  • 입력창이 비어있을 때는 이전 입력 복원

 

3) 이미지 드래그 앤 드롭

UI 목업, 아키텍처 다이어그램 등 시각 자료를 직접 드래그하여 컨텍스트로 제공할 수 있습니다.

이때, 이미지만 드래그 하지말고, "무엇인지 + 어떻게 할 것인지"를 같이 작성하여 효율성을 극대화 시킵니다.

 

4) Bash 명령어 실행 (!)

터미널을 별도로 열지 않고도 클로드 코드 내에서 ! 접두사를 붙여 bash 명령어를 실행할 수 있습니다.

(예: !git status, !npm run build)

 

5) 필수 명령어

• /clear
  • 현재 대화 기록을 모두 지우고 컨텍스트를 초기화합니다.
  • 새 작업을 시작할 때 반드시 사용하여 토큰 사용량을 줄입니다.
  • 이전 대화가 쌇이면 200K 토큰 공간이 줄어들고, 응답 품질도 떨어집니다.
• /compact
  • 대화 기록은 지우되, 요약된 컨텍스트는 유지합니다.
• /context
  • 현재 사용 중인 토큰 양을 확인합니다.
  • 현재 사용량이 80% 이상이면 /clear나 /compact로 컨텍스트를 줄입니다.
• /models
  
  • 모델 전환시 사용합니다.
  • Opus: 가장 똑똑하고 토큰을 많이 사용하며 복잡한 작업에 적합.
  • Sonnet: Opus와 Haiku의 중간 모델로, 일상적인 작업에 적합.
    • 병렬 작업 시에는 토큰 소모를 줄이기 위해 Sonnet 모델을 사용하는 것이 효율적입니다.
  • Haiku: 가장 빠르고 토큰을 적게 사용.
• /memory: 클로드가 학습한 내용을 자동으로 memory.md 파일에 저장하고 관리합니다.
• /resume: 이전 세션 복구, 터미널을 실수로 닫았을 때 또는 다시 실행 후 /resume으로 이전 대화를 복원할 수 있습니다.
• /mcp: 연결된 MCP(Multi-Tool Calling Protocol) 서버 목록을 확인합니다. MCP는 외부 도구를 연동하는 데 사용되지만, 많은 MCP 서버는 상당한 컨텍스트를 차지하므로 주의가 필요합니다.
• /help: 클로드 코드의 전반적인 도움말을 볼 수 있습니다.
• /config: 클로드 코드의 설정을 확인하고 변경할 수 있습니다.
• /export: 채팅 내보내기 (커너나 제미나이 등 다른 AI로 옮길때 사용)
• /output_style: 클로드의 응답 스타일을 조절할 수 있습니다 (예: 설명적, 경고적).