[Claude Code] Reddit에 올라온 완전 정복 가이드 v4 (한국어 번역)

원문 내용 번역만 클로드로 해서 정리함.

85% 컨텍스트 절약, 커스텀 에이전트, 세션 텔레포트까지

2026년 1월, Claude Code 2.1.x가 한 달 동안 무려 1,096개 이상의 커밋을 쏟아냈음. 이건 단순 업데이트가 아니라 Claude Code가 컨텍스트를 관리하고, 작업을 위임하고, 확장하는 방식 자체가 바뀐 혁명적 변화임.

V4에서 뭐가 달라졌나

• MCP Tool Search: 레이지 로딩으로 컨텍스트 85% 절약
• 커스텀 에이전트: 전문가 에이전트에게 자동 위임
• 세션 텔레포트: 디바이스 간 세션 이동
• 백그라운드 태스크: 병렬 에이전트 실행
• 새 명령어들: /config 검색, /stats 필터링, 커스텀 단축키

---

Part 1: Global CLAUDE.md - 보안 게이트키퍼

메모리 계층 구조

Claude Code는 CLAUDE.md 파일을 순서대로 로드함:

레벨	위치	용도
엔터프라이즈	/etc/claude-code/CLAUDE.md	조직 전체 정책
글로벌	~/.claude/CLAUDE.md	모든 프로젝트 공통 설정
프로젝트	./CLAUDE.md	팀 공유 지침
프로젝트 로컬	./CLAUDE.local.md	개인 오버라이드

글로벌에 뭘 넣어야 하나

1. 계정 정보

## GitHub 계정
**항상** **YourUsername**으로 모든 프로젝트 작업할 것:
- SSH: `git@github.com:YourUsername/<repo>.git`

## Docker Hub
이미 인증됨. 사용자명은 `~/.env`의 `DOCKER_HUB_USER`에 있음

2. 절대 하면 안 되는 것들

## NEVER EVER DO
이 규칙은 절대적임:

### 민감한 데이터 퍼블리시 금지
- 절대로 비밀번호, API 키, 토큰을 git/npm/docker에 퍼블리시하지 말 것
- 모든 커밋 전: 시크릿 포함 여부 확인

### .env 파일 커밋 금지
- 절대로 `.env`를 git에 커밋하지 말 것
- 항상 `.env`가 `.gitignore`에 있는지 확인

왜 중요한가: Claude가 .env를 읽음

보안 연구자들이 발견한 사실: Claude Code가 명시적 허가 없이 자동으로 .env 파일을 읽음.

Backslash Security 경고: "제한하지 않으면 Claude가 .env, AWS 자격증명, secrets.json을 읽고 '도움이 되는 제안'을 통해 유출할 수 있음."

글로벌 CLAUDE.md가 행동 게이트키퍼 역할을 함 - Claude가 접근권이 있더라도 시크릿을 출력하지 않게 됨.

다중 방어 레이어

레이어	무엇	방법
1	행동 규칙	Global CLAUDE.md "NEVER" 규칙
2	접근 제어	settings.json의 거부 목록
3	Git 안전	.gitignore

---

Part 2: 새 프로젝트 스캐폴딩 규칙

글로벌 CLAUDE.md가 프로젝트 공장이 됨. 모든 새 프로젝트가 자동으로 표준을 상속받음.

## 새 프로젝트 설정
어떤 새 프로젝트든 만들 때:

### 필수 파일
- `.env` - 환경 변수 (절대 커밋 금지)
- `.env.example` - 플레이스홀더가 있는 템플릿
- `.gitignore` - 포함해야 함: .env, node_modules/, dist/
- `CLAUDE.md` - 프로젝트 개요

### 필수 구조
project/
├── src/
├── tests/
├── docs/
├── .claude/
│   ├── skills/
│   ├── agents/
│   └── commands/
└── scripts/

---

Part 3: MCP 서버 - Claude의 통합 기능

MCP(Model Context Protocol)를 통해 Claude가 외부 도구와 상호작용함.

MCP 서버 추가

claude mcp add <server-name> -- <command>
claude mcp list
claude mcp remove <server-name>

언제 MCP를 쓰면 안 되나

MCP 서버는 토큰과 컨텍스트를 소비함. 간단한 통합에는 대안을 고려할 것:

사용 케이스	MCP 오버헤드	대안
Trello 작업	높음	CLI 도구
간단한 HTTP 호출	과함	curl via Bash
일회성 쿼리	낭비	직접 명령어

경험 법칙: 세션당 MCP 도구를 한 번만 호출한다면, CLI가 더 효율적임. MCP는 대화 내에서 반복적인 도구 사용에 빛남.

개발자용 추천 MCP 서버

핵심 개발
| 서버 | 용도 | 설치 |
|------|------|------|
| Context7 | 모든 라이브러리의 라이브 문서 | claude mcp add context7 -- npx -y @upstash/context7-mcp@latest |
| GitHub | PR, 이슈, CI/CD | claude mcp add github -- npx -y @modelcontextprotocol/server-github |
| Sequential Thinking | 구조화된 문제 해결 | claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking |

데이터베이스
| 서버 | 용도 | 설치 |
|------|------|------|
| MongoDB | Atlas/Community | claude mcp add mongodb -- npx -y mongodb-mcp-server |
| PostgreSQL | 자연어로 Postgres 쿼리 | claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres |
| DBHub | 유니버설 (MySQL, SQLite 등) | claude mcp add db -- npx -y @bytebase/dbhub |

---

Part 4: Commands - 개인 단축키

커맨드는 프롬프트로 확장되는 개인 매크로임.

저장 위치:

• ~/.claude/commands/ - 어디서든 사용 가능
• .claude/commands/ - 프로젝트 전용

기본 커맨드

~/.claude/commands/review.md 생성:

---
description: 코드 이슈 리뷰
---
이 코드를 다음 관점에서 리뷰해줘:
1. 보안 취약점
2. 성능 이슈
3. 에러 핸들링 갭
4. 코드 스타일 위반

사용법: 아무 세션에서 /review 입력

인자가 있는 커맨드

---
description: 설명으로 티켓 생성
argument-hint: <ticket-description>
---
다음에 대한 상세 티켓 생성:
$ARGUMENTS

포함할 것:
- 유저 스토리
- 인수 조건
- 기술 노트

사용법: /ticket 다크 모드 지원 추가

고급: Bash 실행이 있는 커맨드

---
description: 컨텍스트가 있는 스마트 커밋
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
---
## 컨텍스트
- 현재 git 상태: !`git status`
- 현재 git diff: !`git diff HEAD`
- 현재 브랜치: !`git branch --show-current`
- 최근 커밋: !`git log --oneline -5`

## 작업
다음 메시지로 커밋 생성: $ARGUMENTS

! 백틱 문법은 프롬프트 처리 전에 bash 명령을 실행함.

---

Part 5: Skills - 재사용 가능한 전문성

스킬은 필요할 때만 로드되는 트리거 전문성임. CLAUDE.md(항상 로드)와 달리 스킬은 컨텍스트 절약을 위해 점진적 공개를 사용함.

스킬 생성

.claude/skills/code-review/SKILL.md 생성:

---
name: Code Review
description: 보안 중심의 종합 코드 리뷰
triggers:
  - review
  - audit
  - check code
---
# 코드 리뷰 스킬

코드 리뷰 시:
1. 보안 취약점 확인 (OWASP Top 10)
2. 성능 이슈 찾기 (N+1 쿼리, 메모리 누수)
3. 에러 핸들링 검증 (엣지 케이스, null 체크)
4. 테스트 커버리지 평가
5. 네이밍과 문서화 리뷰

점진적 공개

스킬은 토큰 효율을 위해 점진적 공개를 사용함:

• 시작 시: 이름/설명만 로드 (~50 토큰)
• 트리거 시: 전체 SKILL.md 내용 로드
• 필요 시: 추가 리소스 로드

경험 법칙: 지침이 대화의 20% 미만에 적용된다면, CLAUDE.md 대신 스킬로 만들 것.

---

Part 6: 단일 목적 채팅이 중요한 이유

연구에 따르면 주제를 섞으면 정확도가 망가짐.

멀티턴 대화 연구: "지침이 여러 턴에 걸쳐 전달될 때 평균 39% 성능 저하."

Chroma의 컨텍스트 부패 연구: "컨텍스트 윈도우의 토큰이 증가하면 모델의 정보 정확 회상 능력이 감소함."

황금 규칙: "하나의 작업, 하나의 채팅"

시나리오	행동
새 기능	새 채팅
버그 수정 (관련 없는)	/clear 후 새 작업
리서치 vs 구현	별도 채팅
20+ 턴 경과	새로 시작

/clear를 자유롭게 사용할 것

Anthropic 권장: "작업 간에 /clear를 자주 사용해서 컨텍스트 윈도우를 리셋하라."

---

Part 7: Hooks - 결정론적 강제

CLAUDE.md 규칙은 Claude가 컨텍스트 압박 하에서 무시할 수 있는 제안임. 훅은 결정론적 - 항상 실행됨.

핵심 차이

메커니즘	타입	신뢰성
CLAUDE.md 규칙	제안	무시될 수 있음
Hooks	강제	항상 실행

훅 이벤트

이벤트	언제	사용 케이스
PreToolUse	도구 실행 전	위험한 작업 차단
PostToolUse	도구 완료 후	린터 실행
Stop	Claude 턴 종료	품질 게이트
Setup	초기화/유지보수 시	레포 초기화 (V4)

예시: 시크릿 접근 차단

~/.claude/settings.json에 추가:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "python3 ~/.claude/hooks/block-secrets.py"
        }]
      }
    ]
  }
}

훅 스크립트:

#!/usr/bin/env python3
import json, sys
from pathlib import Path

SENSITIVE = {'.env', '.env.local', 'secrets.json', 'id_rsa'}

data = json.load(sys.stdin)
file_path = data.get('tool_input', {}).get('file_path', '')

if Path(file_path).name in SENSITIVE:
    print(f"BLOCKED: {file_path} 접근 거부됨.", file=sys.stderr)
    sys.exit(2)  # Exit 2 = 차단하고 stderr를 Claude에게 전달

sys.exit(0)

훅 종료 코드

코드	의미
0	작업 허용
1	에러 (사용자에게 표시)
2	작업 차단, Claude에게 이유 전달

---

Part 8: LSP - IDE 수준 코드 인텔리전스

2025년 12월 (v2.0.74)에 Claude Code가 네이티브 Language Server Protocol 지원을 얻었음.

LSP가 가능하게 하는 것

기능	하는 일
Go to Definition	심볼이 정의된 곳으로 점프
Find References	함수가 사용되는 모든 곳 확인
Hover	타입 시그니처와 문서 얻기
Diagnostics	실시간 에러 감지
Document Symbols	파일의 모든 심볼 나열

왜 중요한가

LSP 이전에 Claude는 텍스트 기반 검색(grep, ripgrep)을 사용해 코드를 이해했음. 느리고 부정확함.

LSP로 Claude는 시맨틱 이해를 갖게 됨 - 파일 A의 getUserById가 파일 B에 정의된 함수를 호출한다는 것을 알고, 단순히 텍스트가 일치한다고 보지 않음.

성능: 900배 빠름 (크로스 코드베이스 탐색에서 45초 → 50ms)

지원 언어: Python, TypeScript, Go, Rust, Java, C/C++, C#, PHP, Kotlin, Ruby, HTML/CSS

---

Part 9: MCP Tool Search - 85% 컨텍스트 혁명

V4의 가장 큰 변화임.

문제

연결하는 모든 MCP 서버가 도구 정의(설명, 파라미터, 스키마)를 가져옴. Tool Search 이전에는 시작 시 모두 로드했음:

이전:
73개 MCP 도구 로딩... [39.8k 토큰]
56개 에이전트 로딩... [9.7k 토큰]
시스템 도구 로딩... [22.6k 토큰]
92k 토큰 남음으로 준비 완료. ← 아무것도 입력하기 전에 컨텍스트 54% 사라짐

사용자들이 200K 컨텍스트의 50-70%가 프롬프트 하나 쓰기도 전에 소비된다고 보고했음.

해결책: 레이지 로딩

이후:
도구 레지스트리 로딩... [5k 토큰]
195k 토큰 사용 가능으로 준비 완료. ← 컨텍스트 95% 보존

사용자: "데이터베이스 쿼리해야 해"
> 자동 로딩: postgres-mcp [+1.2k 토큰]
> 193.8k 토큰 남음

작동 방식

1. 감지: MCP 도구 설명이 컨텍스트의 >10%를 사용할지 확인
2. 레지스트리 생성: 도구 이름과 설명의 경량 인덱스 구축
3. 온디맨드 로딩: Claude가 필요하다고 판단할 때만 도구 로드
4. 지능적 캐싱: 로드된 도구는 세션 동안 계속 사용 가능

수치

메트릭	이전	이후	개선
초기 컨텍스트 사용량	~77K 토큰	~8.7K 토큰	85% 감소
Opus 4 정확도	49%	74%	+25 포인트
Opus 4.5 정확도	79.5%	88.1%	+8.6 포인트

의미하는 것

• 더 많은 MCP 서버: 페널티 없이 수십 개 연결
• 더 나은 정확도: 노이즈 감소 = 더 나은 도구 선택
• 더 큰 작업: 실제 작업을 위한 더 많은 컨텍스트
• 워크플로우 변경 없음: 도구가 이전과 똑같이 작동

---

Part 10: 커스텀 에이전트 - 자동 위임

커스텀 에이전트는 Claude가 자동으로 호출하는 전문 어시스턴트임 - 도구를 자동 선택하는 것처럼.

왜 커스텀 에이전트인가

문제	해결책
다양한 작업으로 인한 컨텍스트 오염	각 에이전트가 격리된 컨텍스트 윈도우 보유
전문 작업에 대한 일반적 조언	에이전트가 집중된 시스템 프롬프트 보유
수동 오케스트레이션 오버헤드	작업 기반 자동 위임

커스텀 에이전트 생성

방법 1: 인터랙티브 (권장)

/agents
"새 에이전트 생성" 선택 -> 위치 선택 (User 또는 Project) -> Claude로 생성 또는 수동

방법 2: 수동

~/.claude/agents/code-reviewer.md 생성:

---
name: code-reviewer
description: 보안, 성능, 베스트 프랙티스를 위한 코드 리뷰
tools: Read, Grep, Glob
model: sonnet
---
당신은 다음을 전문으로 하는 시니어 코드 리뷰어임:
- 보안 취약점 (OWASP Top 10)
- 성능 안티패턴
- 에러 핸들링 갭
- 코드 유지보수성

리뷰할 때:
1. 보안 문제부터 시작
2. 그다음 성능 이슈
3. 그다음 스타일/유지보수성
4. 구체적인 라인 참조 제공
5. 구체적인 수정 제안

비판적이되 건설적으로. 왜 문제인지 설명할 것.

자동 위임 작동 방식

Claude가 다음을 기반으로 위임함:

1. 요청의 작업 설명
2. 에이전트 설정의 description 필드
3. 현재 컨텍스트
4. 사용 가능한 도구

빌트인 에이전트

에이전트	용도	언제 사용
Explore	읽기 전용 코드베이스 분석	검색, 코드 이해
Plan	계획을 위한 리서치	플랜 모드 컨텍스트 수집
General-purpose	복잡한 다단계 작업	탐색 + 수정 필요 시

베스트 프랙티스

• 에이전트를 집중시킬 것: 에이전트당 하나의 전문성
• 명확한 설명 작성: Claude가 위임 결정에 이걸 사용함
• 도구 제한: 읽기 전용 에이전트는 Write 접근 없어야 함
• 3-4개 에이전트로 시작: 옵션이 너무 많으면 라우팅이 혼란스러워질 수 있음

---

Part 11: 세션 텔레포트

터미널과 claude.ai/code 사이에서 작업을 원활하게 이동할 수 있음.

웹으로 텔레포트

/teleport

현재 세션을 claude.ai/code에서 열음. 다음에 완벽함:

• 터미널에서 비주얼 인터페이스로 전환
• 협업자와 세션 공유
• 다른 디바이스에서 계속

세션 재개

# 가장 최근 세션 계속
claude --continue  # 또는 claude -c

# ID로 특정 세션 재개
claude --resume abc123  # 또는 claude -r abc123

# 새 프롬프트로 재개
claude --resume abc123 "테스트 계속해줘"

---

Part 12: 백그라운드 태스크 & 병렬 실행

태스크 백그라운딩

Ctrl+B를 눌러 백그라운드로:

• 현재 실행 중인 에이전트
• 셸 명령
• 둘 다 동시에 (V4에서 통합된 동작)

백그라운드 태스크 관리

/tasks

모든 백그라운드 태스크 표시:

• 상태 표시기
• 에이전트의 최종 응답 인라인 표시
• 전체 트랜스크립트로의 클릭 가능한 링크

---

Part 13: 새 명령어, 단축키 & 삶의 질 향상

새 명령어

명령어	하는 일
/config	이제 검색 기능 있음 - 타이핑해서 설정 필터링
/stats	r 눌러서 순환: 최근 7일, 최근 30일, 전체 기간
/doctor	이제 자동 업데이트 채널과 사용 가능한 npm 버전 표시
/keybindings	커스텀 키보드 단축키 설정
/context	토큰이 어디로 가는지 정확히 확인

커스텀 키보드 단축키

~/.claude/keybindings.json 생성:

{
  "ctrl+shift+r": "/review",
  "ctrl+shift+d": "/deploy",
  "ctrl+shift+t": "/test",
  "ctrl+shift+c": "/commit"
}

필수 단축키 참조

단축키	동작
Ctrl+C	현재 작업 취소
Ctrl+D	Claude Code 종료
Ctrl+B	현재 태스크 백그라운드
Shift+Tab	플랜 모드에서: 편집 자동 수락
Esc Esc	이전 상태로 되돌리기 (더블탭)
Tab	명령어, 파일, 에이전트 자동완성
Shift+Enter	제출 없이 줄바꿈 삽입
↑/↓	명령어 히스토리 탐색
Ctrl+R	히스토리 역검색

---

빠른 참조

도구	용도	위치
Global CLAUDE.md	보안 + 스캐폴딩	~/.claude/CLAUDE.md
Project CLAUDE.md	아키텍처 + 팀 규칙	./CLAUDE.md
MCP 서버	외부 통합	claude mcp add
MCP Tool Search	레이지 로딩 (85% 절약)	컨텍스트 >10%일 때 자동
스킬	재사용 가능한 전문성	.claude/skills/<name>/SKILL.md
커스텀 에이전트	자동 위임	~/.claude/agents/<name>.md
커맨드	개인 단축키	~/.claude/commands/<name>.md
훅	결정론적 강제	~/.claude/settings.json
LSP	시맨틱 코드 인텔리전스	빌트인 (v2.0.74+)
키바인딩	커스텀 단축키	~/.claude/keybindings.json
/clear	컨텍스트 리셋	채팅에서 입력
/context	토큰 사용량 보기	채팅에서 입력
/teleport	claude.ai/code로 이동	채팅에서 입력
/tasks	백그라운드 태스크 관리	채팅에서 입력

---

마무리

V4의 핵심은 효율성임. MCP Tool Search로 컨텍스트 85% 절약, 커스텀 에이전트로 작업 자동 위임, 세션 텔레포트로 디바이스 간 이동까지. Claude Code가 단순 코딩 도구에서 진정한 AI 에이전트 프레임워크로 진화했음.

가장 중요한 건 이 모든 기능이 기존 워크플로우를 깨지 않는다는 점임. 이전처럼 쓰면서 자연스럽게 혜택을 받을 수 있음.

---

원문: The Complete Guide to Claude Code V4 — The Decipherist