ClOr

ClOr

백엔드 실무 트러블슈팅과 AI 에이전트 구조 분석을 기록합니다.

Claude Code 해부학 (완결)

51만 줄 소스코드를 19편에 걸쳐 분석한 완결 시리즈

전체 시리즈 보기 →

백엔드 트러블슈팅

실무에서 겪은 장애와 해결 과정 기록

전체 시리즈 보기 →

최신 글

article thumbnail

Claude Code를 매일 쓰면서도 Escape 하나 모르고, Shift+Tab이 뭔지 모르고, 슬래시 커맨드 절반을 안 써본 사람이 대부분이다. 공식 문서에 흩어져 있는 단축키, 커맨드, CLI 플래그, 환경변수를 한 페이지에 전부 모았다. 북마크 걸어두고 필요할 때 꺼내 보면 된다.

모르면 마우스를 잡고, 같은 명령을 반복 입력하고, 삽질하는 Claude를 멍하니 지켜본다. 알면 키 하나로 끝난다.

목차

  • 핵심 키보드 단축키
    • 몰랐을 수도 있는 것들
  • 슬래시 커맨드 완전 정리
    • 세션 관리
    • 모델 / 성능
    • 도구 / 설정
    • 작업 흐름
  • CLI 플래그 — 시작할 때 거는 옵션들
    • -p 플래그의 핵심
    • --max-turns를 습관화해라
  • 파워유저 워크플로우 5가지
      1. 파이프라인으로 Claude 쓰기
      1. 원샷 스크립트 실행
      1. 모델 전환 워크플로우
      1. 세션 관리 워크플로우
      1. 키바인딩 커스터마이징
  • 환경변수 치트시트
    • 환경변수 활용 팁
  • 요약 — 이것만 외워라

핵심 키보드 단축키

가장 자주 쓰는 것부터 정리했다. 이 테이블 하나만 외워도 체감 속도가 확 달라진다.

단축키 기능 언제 쓰나
Escape 현재 응답 중단 Claude가 삽질하고 있을 때. 방향이 틀렸으면 즉시 끊어라
Ctrl+C 실행 중인 도구 취소 Bash 도구가 무한 루프 돌 때, 테스트가 안 끝날 때
Tab 자동완성 (파일 경로 등) 파일명이나 경로 입력할 때. 쉘처럼 동작한다
Shift+Tab AI 자동완성 프롬프트 작성 중 Claude가 다음 문장을 제안. ghost text가 뜨면 눌러서 수락
Up / Down 이전 메시지 탐색 이전 프롬프트 재사용. 쉘의 history처럼 동작
Ctrl+L 화면 클리어 (대화 유지) 화면만 정리하고 싶을 때. 대화 컨텍스트는 그대로
Ctrl+J 또는 Enter 줄바꿈 (multi-line mode) 긴 프롬프트를 여러 줄로 작성할 때
Option+Enter (Mac) / Ctrl+Enter 메시지 전송 (multi-line mode) multi-line 모드에서 실제로 보내기

몰랐을 수도 있는 것들

  • Escape는 응답 중단이지, 도구 실행 취소가 아니다. 도구가 돌고 있으면 Ctrl+C를 써야 한다. 이 둘을 헷갈리면 의미 없이 기다리게 된다.
  • Shift+Tab은 의외로 강력하다. Claude가 프롬프트를 예측해서 ghost text를 보여주는데, 반복적인 지시를 내릴 때 입력량이 절반으로 줄어든다.
  • Up 키로 이전 프롬프트를 불러온 뒤 수정해서 보내면, 비슷한 작업을 반복할 때 타이핑을 거의 안 해도 된다.
  • multi-line 모드는 기본 설정에서 Enter가 줄바꿈이다. 전송은 Option+Enter (Mac) 또는 Ctrl+Enter. 한 줄 모드에서는 Enter가 전송이다. 설정으로 바꿀 수 있다.

슬래시 커맨드 완전 정리

슬래시 커맨드는 Claude Code 내부에서 /로 시작하는 빌트인 명령이다. 프롬프트처럼 Claude에게 보내는 게 아니라, Claude Code 앱 자체가 처리하는 시스템 명령이다.

세션 관리

커맨드 기능
/clear 대화 초기화 작업 전환 시 필수. 오래된 컨텍스트가 매 메시지마다 토큰을 낭비한다
/compact [focus] 대화 요약 압축 뒤에 키워드를 붙이면 요약 시 보존할 내용을 지정할 수 있다. /compact code changes 이런 식
/resume 이전 세션 이어하기 세션 목록이 뜨고 선택할 수 있다. 어제 하던 작업 이어가기
/rename [name] 세션 이름 변경 /resume할 때 찾기 쉽게. 프로젝트명이나 작업 내용으로 지어둬라

/clear/compact는 비용에 직접적인 영향을 준다. 컨텍스트가 커지면 매 턴마다 입력 토큰이 불어나기 때문이다. 작업이 바뀌면 /clear, 같은 작업이 길어지면 /compact. 이 패턴만 잡아도 토큰 낭비가 확 줄어든다.

모델 / 성능

커맨드 기능
/model [name] 모델 전환 opus, sonnet, haiku, opusplan 사용 가능
/effort [level] 추론 깊이 조절 low / medium / high. 단순 작업에 low 쓰면 빠르고 싸다
/fast 빠른 모드 토글 같은 모델, 더 빠른 출력. thinking 토큰을 줄이는 방식

/model opusplan이 핵심이다. Plan 단계에서만 Opus를 쓰고, 실행은 Sonnet으로 자동 전환한다. 설계 품질은 Opus급, 비용은 Sonnet급. 복잡한 리팩토링을 시킬 때 이것부터 켜라.

/effort low는 단순 질문이나 포맷 변환 같은 작업에 딱이다. Claude가 깊이 생각할 필요 없는 작업에 high를 쓰면 시간과 토큰만 낭비된다.

도구 / 설정

커맨드 기능
/cost 현재 세션 비용 확인 API 사용자용. 구독이면 /stats 참고
/stats 사용 통계 구독자용. 남은 용량 확인
/permissions 권한 설정 도구별로 자동 허용/거부를 설정할 수 있다
/memory 메모리 관리 CLAUDE.md를 직접 편집하는 인터페이스
/buddy 다마고치 버디 보기 자세한 건 이전 글 참고
/statusline 상태바 설정 자연어로 설명하면 Claude가 스크립트를 만들어준다

/permissions는 한 번 세팅해두면 매번 뜨는 허용 팝업을 없앨 수 있다. Bash(git *), Read, Write 정도는 자동 허용으로 걸어두면 워크플로우가 훨씬 매끄러워진다.

작업 흐름

커맨드 기능
/plan 계획 모드 진입 구현 전에 설계를 먼저 검토. 큰 작업일수록 필수
/review PR 리뷰 현재 diff 기반으로 코드 리뷰를 해준다
/commit 커밋 생성 변경 사항을 분석해서 커밋 메시지를 자동 작성

/plan은 과소평가되는 커맨드다. 바로 "구현해줘"라고 시키는 것보다 /plan으로 설계를 먼저 잡고, 검토한 뒤에 실행시키면 삽질이 크게 줄어든다. 특히 파일 10개 이상 건드리는 작업에서 효과가 뚜렷하다.

CLI 플래그 — 시작할 때 거는 옵션들

Claude Code를 실행할 때 붙이는 플래그다. 원샷 실행, 모델 지정, 자동화 파이프라인에서 특히 유용하다.

플래그 기능 예시
-p "prompt" 원샷 실행 (비대화형) claude -p "fix lint errors"
--model 모델 지정 claude --model sonnet
--allowedTools 자동 허용 도구 claude --allowedTools "Bash,Read,Write"
--dangerouslySkipPermissions 모든 권한 스킵 CI/CD에서만 쓸 것. 로컬에서 쓰면 위험
--output-format json JSON 출력 다른 스크립트와 파이프라인 연동
--verbose 상세 로그 디버깅할 때 Claude의 내부 동작이 보인다
--max-turns N 최대 턴 수 제한 비용 제어. 원샷 실행 시 꼭 걸어둬라
--resume 세션 이어하기 claude --resume — 세션 목록에서 선택
--continue 마지막 세션 이어하기 claude --continue — 가장 최근 세션 바로 이어감

-p 플래그의 핵심

-p는 Claude Code를 비대화형 도구로 바꾸는 플래그다. stdin을 받고, stdout으로 결과를 내보내고, 끝난다. 이게 파이프라인의 기본이다.

-p 없이 실행하면 대화형 REPL이 뜨고, -p를 붙이면 한 번 실행하고 종료한다. 스크립트에서 Claude를 호출할 때는 무조건 -p를 써야 한다.

--max-turns를 습관화해라

원샷 실행(-p)에서 --max-turns를 안 걸면, Claude가 끝없이 도구를 호출하면서 토큰을 태울 수 있다. 간단한 작업이면 --max-turns 5, 좀 복잡하면 --max-turns 15 정도가 적당하다. 보험이라고 생각하면 된다.

파워유저 워크플로우 5가지

단축키와 커맨드를 아는 것에서 한 발 더 나가서, 실전에서 쓰는 조합을 정리했다.

1. 파이프라인으로 Claude 쓰기

Claude Code의 -p 플래그 + stdin 파이프는 자동화의 핵심이다.

# git diff를 Claude에게 리뷰 시키기
git diff | claude -p "review this diff for bugs"

# 로그 분석
cat error.log | claude -p "summarize the errors and suggest fixes"

# 여러 파일을 한번에 분석
find . -name "*.test.ts" | claude -p "are there any tests missing edge cases?"

--output-format json을 붙이면 결과를 jq로 파싱해서 다음 스크립트에 넘길 수 있다. CI/CD 파이프라인에서 자동 리뷰, 자동 수정, 자동 커밋까지 체인을 만들 수 있다는 뜻이다.

2. 원샷 스크립트 실행

대화형으로 들어가지 않고, 한 줄로 끝내는 패턴이다.

# lint 에러 자동 수정
claude -p "fix all lint errors in src/" --allowedTools "Bash,Edit,Read"

# 타입 추가
claude -p "add TypeScript types to all functions in utils.ts" --max-turns 10

# 테스트 생성
claude -p "write unit tests for src/auth/login.ts" --allowedTools "Bash,Read,Write" --max-turns 15

--allowedTools로 필요한 도구만 열어주면 허가 팝업 없이 자동 실행된다. --max-turns로 비용도 제어하고. 이 조합이면 cron이나 git hook에 Claude를 걸 수 있다.

3. 모델 전환 워크플로우

상황에 따라 모델을 바꿔가며 쓰는 게 비용 대비 효율이 가장 높다.

# 세션 시작: 일반 코딩은 Sonnet으로
claude --model sonnet

# 아키텍처 결정이 필요한 순간
/model opus

# 단순 반복 (파일 이름 변경, 포맷팅 등)
/model haiku

# 설계는 Opus, 실행은 Sonnet — 가장 추천
/model opusplan

실전에서의 패턴: Sonnet으로 시작 → 복잡한 판단이 필요하면 /model opus로 전환 → 판단이 끝나면 다시 /model sonnet으로 복귀. 이걸 한 세션 안에서 수시로 해라. Opus를 상시 켜두는 것보다 60~80% 비용 절감이 가능하다.

4. 세션 관리 워크플로우

여러 작업을 병렬로 할 때 세션 관리가 핵심이다.

# 작업 시작 전 세션 이름을 먼저 지정
/rename auth-refactoring

# 중간에 급한 버그 수정 요청이 오면
/clear
/rename hotfix-login-crash

# 버그 수정 후, 원래 작업으로 복귀
/clear
/resume  →  auth-refactoring 선택

세션 이름은 구체적으로 짓는 게 핵심이다. "작업1" 같은 이름은 나중에 아무것도 기억 안 난다. "auth-refactoring-jwt-migration" 이 정도로 지어둬야 /resume 목록에서 바로 찾는다.

터미널을 여러 개 띄워서 병렬 세션을 돌릴 수도 있다. 각 터미널에서 별도의 Claude Code 인스턴스를 실행하면 된다.

5. 키바인딩 커스터마이징

~/.claude/keybindings.json으로 단축키를 직접 바꿀 수 있다.

[
  {
    "key": "ctrl+s",
    "command": "commit",
    "description": "Quick commit"
  },
  {
    "key": "ctrl+k ctrl+r",
    "command": "review",
    "description": "Code review (chord)"
  }
]

Chord 바인딩(두 키 연속)도 지원한다. ctrl+k ctrl+r은 Ctrl+K를 누르고, 이어서 Ctrl+R을 누르는 방식이다. VS Code 사용자라면 익숙한 패턴일 것이다.

자주 쓰는 슬래시 커맨드를 단축키로 바인딩해두면, /를 누르고 타이핑할 필요 없이 키 조합 하나로 실행할 수 있다. /commit을 하루에 20번 치는 사람이라면 ctrl+s에 바인딩하는 게 맞다.

환경변수 치트시트

Claude Code 실행 전에 셸에서 export로 걸어두는 변수들이다. 시작 옵션을 매번 플래그로 안 줘도 되게 만드는 방법이다.

변수 용도 예시
ANTHROPIC_MODEL 기본 모델 지정 export ANTHROPIC_MODEL=sonnet
CLAUDE_CODE_USE_BEDROCK AWS Bedrock 사용 export CLAUDE_CODE_USE_BEDROCK=1
CLAUDE_CODE_USE_VERTEX GCP Vertex AI 사용 export CLAUDE_CODE_USE_VERTEX=1
MAX_THINKING_TOKENS thinking 토큰 제한 export MAX_THINKING_TOKENS=8000
CLAUDE_CODE_MAX_OUTPUT_TOKENS 출력 토큰 제한 export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

환경변수 활용 팁

.bashrc.zshrc에 넣어두면 매번 입력할 필요 없다.

# ~/.bashrc 또는 ~/.zshrc
export ANTHROPIC_MODEL=sonnet
export MAX_THINKING_TOKENS=10000
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000

프로젝트별로 다른 설정을 쓰고 싶으면 direnv를 쓰면 된다. 프로젝트 폴더에 .envrc 파일을 만들어두면 해당 디렉토리에 들어갈 때 자동으로 환경변수가 설정된다.

# ~/projects/my-app/.envrc
export ANTHROPIC_MODEL=opus
export MAX_THINKING_TOKENS=16000

CLAUDE_CODE_USE_BEDROCK이나 CLAUDE_CODE_USE_VERTEX는 회사에서 자체 클라우드를 통해 API를 라우팅할 때 쓴다. 개인 사용자가 설정할 일은 거의 없다.

요약 — 이것만 외워라

전부 외울 필요 없다. 아래 7가지만 기억하면 된다. 나머지는 이 글을 북마크해두고 필요할 때 찾아 쓰면 된다.

  • Escape — 삽질하는 Claude 즉시 멈추기
  • Shift+Tab — AI가 프롬프트를 대신 완성해준다
  • /compact — 컨텍스트가 커지면 바로 요약. 토큰 비용 직결
  • /clear — 작업 전환 시 무조건. 오래된 컨텍스트는 독이다
  • /model opusplan — 설계는 Opus, 실행은 Sonnet. 가성비 끝판왕
  • claude -p + --max-turns — 원샷 자동화의 기본 조합
  • ~/.claude/keybindings.json — 자주 쓰는 커맨드는 단축키로 만들어라

Claude Code는 겉보기엔 단순한 CLI지만, 파고 들어가면 IDE 수준의 커스터마이징이 가능하다. 단축키 하나, 커맨드 하나가 쌓이면 하루에 수십 분이 절약된다. 생산성 차이는 결국 이런 디테일에서 갈린다.


관련글:

profile

ClOr

@ClOr

포스팅이 좋았다면 "좋아요❤️" 또는 "구독👍🏻" 해주세요!

ClOr · 백엔드 트러블슈팅과 AI 에이전트 구조 분석을 기록합니다.