클로드 코드 - 입문

1. CLAUDE.md — Claude에게 프로젝트를 가르치는 파일

Claude Code를 잘 쓰는 사람과 못 쓰는 사람의 가장 큰 차이가 이 파일이다. CLAUDE.md는 매 세션 시작 시 Claude가 자동으로 읽는 프로젝트 설명서로, 여기에 적힌 내용은 대화마다 반복해서 알려줄 필요가 없어지게 됨.

/init으로 자동 생성

/init

Claude가 프로젝트를 분석해 초안을 만들어 줍니다. 처음부터 직접 쓰지 말고 /init으로 뼈대를 만든 뒤 다듬는 것이 효율적입니다.

계층 구조: 글로벌 vs 프로젝트

위치	적용 범위	넣을 내용
~/.claude/CLAUDE.md	모든 프로젝트 공통	개인 공통 규칙 (예: "항상 한국어로 답변")
프로젝트루트/CLAUDE.md	해당 프로젝트만	아키텍처, 컨벤션, 빌드 명령어

글로벌에는 개인 취향을, 프로젝트에는 해당 프로젝트의 아키텍쳐/컨벤션을 넣는다. 두 파일은 함께 로드되어 합쳐진다.

무엇을 넣어야 하나

1. 절대 규칙 — 위반하면 안 되는 금지 사항. 규칙은 위에서 아래로 적용되므로 가장 중요한 것을 맨 위에 배치합니다.
2. 아키텍처 — 폴더 구조, 기술 스택, 주요 모듈의 역할.
3. 빌드/테스트 명령어 — 개발 서버, 테스트, 배포 커맨드. Claude가 매번 package.json을 뒤지지 않게 해줍니다.
4. 도메인 컨텍스트 — 비즈니스 용어, 데이터 흐름. "주문"과 "결제"가 우리 서비스에서 뭘 의미하는지.
5. 코딩 컨벤션 — 네이밍, 커밋 메시지, 선호하는 패턴.

운용 팁 4가지

• 300줄 이하로 유지. CLAUDE.md는 매 대화의 컨텍스트에 포함되므로, 길수록 토큰을 상시 낭비한다. 설명서가 아니라 치트시트라고 생각해야 합니다.

• 직접 수정하지 말고 Claude에게 시키기. "방금 우리가 정한 패턴, CLAUDE.md에 추가해줘"라고 하면 기존 내용과 자연스럽게 병합해줌.

• 트리거 키워드를 등록. 짧은 명령으로 정해진 플로우를 실행이 가능.

  # 트리거
  - "build the app" → npm run build 실행 후 결과 리포트
  - "deploy staging" → staging 환경에 배포

• 레포에 커밋해서 팀과 공유. 팀 전체가 같은 규칙으로 Claude를 쓰게 되고, 신규 입사자의 온보딩 문서 역할도 겸할 수 있게 된다.

---

2. 키보드 단축키 & 입력 테크닉

Shift+Tab — 권한 모드 전환(플랜 - 편집)

Claude Code의 핵심 개념인 권한 모드(permission mode)를 순환 전환합니다. 누를 때마다 다음 순서로 바뀌고, 현재 모드는 프롬프트 아래에 표시됩니다.

기본(Manual) → acceptEdits(수정 자동 수락) → plan(계획만) → 기본 ...

• Plan Mode — Claude가 계획만 세우고 파일은 건드리지 않습니다.
• acceptEdits — 파일 수정을 일일이 승인하지 않고 자동 수락합니다.
• 기본(Manual) — 수정·명령 실행마다 승인을 요구합니다.

새 작업은 항상 Plan Mode로 시작하세요. 계획을 확인한 뒤 실행 모드로 전환하면 엉뚱한 수정을 예방할 수 있다.

Plan Mode를 써야 하는 실무적 이유:

1. 토큰 최적화 — 방향이 틀린 채 코드부터 생성하면 "잘못된 코드 생성 → 수정 요청 → 재생성" 사이클이 반복되며 토큰 소모가 몇 배로 뛴다. 계획 단계의 출력은 짧은 텍스트라 훨씬 저렴하다. (커뮤니티에서는 Plan → Execute 패턴이 30~50% 토큰 절감 효과가 있었다는 체감 리포트들이 있다.)
2. 실행 정확도 — 복잡한 태스크를 Step으로 분해하고 단계별로 승인하면 실패율이 크게 줄어든다. "어떤 파일을 어떻게 수정할지"를 미리 보므로 의도치 않은 사이드 이펙트도 통제된다.
3. 컨텍스트 보존 — 계획을 텍스트로 먼저 확정해 두면, 실제 코딩 단계에서 컨텍스트 윈도우를 코드에 온전히 쓸 수 있다.

Esc — 즉시 중단

잘못된 방향으로 가고 있다 싶으면 망설이지 말고 Esc. 진행 중이던 응답/도구 실행이 그 자리에서 멈추고, 그때까지의 작업 결과는 유지된 채 방향을 다시 지시할 수 있습니다. 권한 승인 다이얼로그가 떠 있을 때는 다이얼로그만 닫습니다.

Esc × 2 — 입력 삭제 / 되감기(Rewind)

공식 문서 기준 정확한 동작은 다음과 같습니다.

• 입력창에 텍스트가 있을 때 → 입력을 지우되 히스토리에 저장합니다. 방향키 ↑로 다시 불러올 수 있습니다.
• 입력창이 비어 있을 때 → 되감기(rewind) 메뉴가 열립니다. 대화와 코드를 이전 시점(체크포인트)으로 되돌릴 수 있는, Claude Code의 강력한 안전장치입니다.

되감기 기능은 "Claude가 코드를 망쳤을 때의 보험"이다. 존재만 알아둬도 심리적 부담이 크게 줄어듬.

! 접두사 — 셸 모드

프롬프트 맨 앞에 !를 붙이면 대화를 끊지 않고 터미널 명령을 바로 실행합니다.

!npm run build
!git status
!ls -la src/

단순 실행이 아니라 명령과 출력이 대화 컨텍스트에 추가된다는 점이 핵심입니다. 최신 버전에서는 출력에 대해 Claude가 곧바로 반응까지 해주므로, !npm test 한 줄로 "테스트 돌리고 실패 원인 설명"까지 한 번에 됩니다.

이미지 활용 — 드래그 앤 드롭 & 붙여넣기

아키텍쳐, ERD, 프론트 - 디자인에 활용하면 효율적이다! 터미널에 스크린샷을 드래그하거나, 클립보드에서 붙여넣으면(Ctrl+V, iTerm2는 Cmd+V, Windows/WSL은 Alt+V) Claude가 이미지를 인식합니다. UI/UX 시안이나 아키텍처 다이어그램을 이미지로 관리하면 말로 설명하는 것보다 훨씬 효율적이다

이미지만 던지지 말고 "무엇인지" + "어떻게 할 것인지"를 함께 알려주자.
예: "이 스크린샷은 로그인 페이지야. 비밀번호 필드 아래에 '비밀번호 찾기' 링크를 추가해줘"

---

3. 필수 슬래시 명령어

컨텍스트 관리 — 품질을 지키는 3총사

컨텍스트 윈도우(약 200K 토큰)는 유한한 자원입니다. 대화가 쌓일수록 응답 품질이 떨어지므로, 아래 세 명령어는 몸에 배어야 합니다.

• /clear — 컨텍스트 완전 초기화. 새 작업을 시작할 때 반드시 사용하세요.
• /compact — 맥락은 유지하면서 압축. 같은 작업을 이어가는데 토큰이 부족할 때 사용합니다.
• /context — 현재 토큰 사용량을 바(bar)로 확인. 80%를 넘으면 /clear 또는 /compact 타이밍입니다.

기준은 간단합니다. 작업이 바뀌면 /clear, 작업이 이어지면 /compact.

모델 & 세션

• /model — 모델 전환. 작업 난이도에 따라 골라 쓰면 비용·속도를 최적화할 수 있습니다.
  • Opus — 가장 똑똑함. 복잡한 아키텍처 설계, 어려운 버그
  • Sonnet — 균형형. 일반적인 코딩 작업의 기본값
  • Haiku — 가장 빠름. 간단한 질문, 파일 탐색
• /resume — 이전 세션 복구. 터미널을 실수로 닫아도 대화를 복원할 수 있습니다.
  • CLI에서 바로 이어가려면: claude -c (직전 세션 이어가기), claude -r <세션ID> (특정 세션 복구)

MCP & 기타

• /mcp — MCP(외부 도구 연결) 관리. 안 쓰는 MCP는 비활성화하세요. 켜 두면 도구 정의만으로 토큰을 상시 낭비합니다.
• /config — 설정 변경 (To-Do 리스트 표시, 에디터 모드 등)
• /export — 대화 내보내기. 다른 도구로 옮기거나 기록을 남길 때 유용합니다.
• /output-style — 응답 스타일 변경 (학습 모드, 간결 모드 등)
• /help — 내장 도움말. /만 입력해도 전체 명령어 목록이 뜹니다.

나만의 슬래시 명령어 만들기

프로젝트 루트에 .claude/commands/ 폴더를 만들고 .md 파일을 넣으면, 파일 이름이 곧 슬래시 명령어가 됩니다.

.claude/
  commands/
    review_script.md    →  /review_script
    deploy_staging.md   →  /deploy_staging

파일 안에는 실행할 프롬프트를 적고, $ARGUMENTS 플레이스홀더를 쓰면 명령어 뒤에 붙인 인자를 받을 수 있습니다.

<!-- .claude/commands/fix_issue.md -->
GitHub 이슈 #$ARGUMENTS 를 분석하고 수정 계획을 세운 뒤 구현해줘.

→ /fix_issue 123 처럼 사용

CLAUDE.md의 트리거 키워드와 비슷하지만, 슬래시 명령어는 탭 자동완성이 되고 Claude Code가 구조적으로 인식하므로 더 안정적입니다. 참고로 최근 버전에서는 커스텀 명령어가 스킬(Skills, .claude/skills/) 체계로 통합되는 흐름입니다. 기존 .claude/commands/도 계속 동작하니 입문 단계에서는 commands로 시작해도 충분합니다.

---

📋 한눈에 보기

단축키 Quick Reference

단축키	동작
Shift+Tab	권한 모드 순환 (Manual → acceptEdits → Plan)
Esc	즉시 중단
Esc × 2	입력 삭제 (텍스트 有) / 되감기 메뉴 (텍스트 無)
!명령어	셸 모드 — bash 명령 바로 실행
Ctrl+R	프롬프트 히스토리 검색
Ctrl+B	실행 중 명령 백그라운드 전환
Ctrl+V	클립보드 이미지 붙여넣기 (iTerm2: Cmd+V)

명령어 Quick Reference

명령어	동작
/init	CLAUDE.md 자동 생성
/clear	컨텍스트 초기화 (새 작업 시작 시)
/compact	컨텍스트 압축 (맥락 유지)
/context	토큰 사용량 확인
/model	모델 전환 (Opus / Sonnet / Haiku)
/resume	이전 세션 복구
/mcp	MCP 관리
/export	대화 내보내기
/output-style	응답 스타일 설정