Claude Code 핵심 개념 정리

Claude Code의 메모리, 컨텍스트, 에이전트, 원격접속 핵심 개념 정리

Posted Jun 22, 2026

By jmhwang-dev

17 min read

참조 문서

공식 문서: https://code.claude.com/docs/en
메모리 관리: https://code.claude.com/docs/en/memory
컨텍스트 윈도우: https://code.claude.com/docs/en/context-window
서브에이전트: https://code.claude.com/docs/en/sub-agents
스킬: https://code.claude.com/docs/en/skills
훅: https://code.claude.com/docs/en/hooks-guide
퍼미션 모드: https://code.claude.com/docs/en/permission-modes
원격 제어: https://code.claude.com/docs/en/remote-control
채널: https://code.claude.com/docs/en/channels

메모리, 지속성 시스템

CLAUDE.md

매 세션 시작 시 자동으로 컨텍스트에 로드되는 프로젝트 지침 파일

코딩 컨벤션, 빌드 명령어, 아키텍처 설명 등 “Claude가 이 코드베이스에서 알아야 할 모든 것”을 담음
세션 단위가 아닌 프로젝트/디렉토리 단위로 작동 (세션이 바뀌어도 유지)
내용은 user 메시지로 주입됨 — 시스템 프롬프트의 일부가 아니므로 100% 강제는 아님
중요한 지침은 “IMPORTANT”, “YOU MUST” 등으로 강조하면 준수율 향상

위치 계층 (로드 우선순위 낮은 것 → 높은 것)

위치	용도	공유 범위
`/Library/Application Support/ClaudeCode/CLAUDE.md`	조직 전체 정책 (IT 관리)	머신의 모든 사용자
`~/.claude/CLAUDE.md`	개인 전역 선호	내 모든 프로젝트
`./CLAUDE.md` 또는 `./.claude/CLAUDE.md`	팀 공유 프로젝트 지침	git으로 팀 공유
`./CLAUDE.local.md`	개인 프로젝트 설정	나만 (gitignore 권장)

@경로/파일 구문으로 다른 파일을 import 가능. 하위 디렉토리의 CLAUDE.md는 해당 디렉토리 파일을 읽을 때 자동 로드.

메모리 시스템 (Auto Memory)

세션, 프로젝트를 넘나드는 사용자 단위 영속 메모리

MEMORY.md = 색인(index). 매 세션 첫 200줄 또는 25KB가 자동 로드됨
개별 토픽 파일 (debugging.md, patterns.md 등) = 실제 내용. 필요할 때만 로드
저장 위치: ~/.claude/projects/<프로젝트>/memory/
Claude가 세션 중 학습한 내용을 자동으로 기록 (“Writing memory” 메시지로 확인 가능)
/memory 명령으로 현재 로드된 메모리 파일 목록 확인 및 편집 가능

Hooks

settings.json에 정의된 셸 명령어. 특정 이벤트 발생 시 하네스(실행 환경)가 결정론적으로 실행

Claude 모델이 “할지 말지” 판단하는 것이 아님 — 모델이 무시 불가능
CLAUDE.md, 메모리가 “유도”라면 Hooks는 “강제”

종료 코드별 동작

종료 코드	동작
`0`	성공. JSON 출력이 있으면 처리
`2`	Blocking error — 해당 액션 차단
그 외	Non-blocking error — 실행 계속

주요 이벤트

이벤트	발생 시점
`PreToolUse`	도구 실행 직전
`PostToolUse`	도구 실행 직후
`Stop`	Claude 응답 완료 시
`Notification`	입력 대기, 권한 요청 등 알림 발생 시
`SessionEnd`	세션 종료 시

세 메커니즘 비교

메커니즘	정의 위치	강제력	적용 범위
CLAUDE.md	`./CLAUDE.md` 등	유도 (비결정론적)	프로젝트 단위
메모리	`~/.claude/memory/`	유도 (관련 시 로드)	사용자 전역
Hooks	`settings.json`	강제 (결정론적)	이벤트 기반

컨텍스트 관리

컨텍스트 증가 시점

세션 시작 시 고정 로드 (타이핑 전에 이미 소비)

항목	설명
System prompt	Claude Code 핵심 동작 지시문. 항상 최우선 로드
Auto memory (MEMORY.md)	이전 세션 메모. 첫 200줄 또는 25KB
Environment info	작업 디렉토리, OS, shell, git 상태 등
MCP tool 스텁	도구 이름 목록 (스키마는 사용 시 로드)
스킬 설명 목록	호출 가능한 스킬 이름, 설명
CLAUDE.md	프로젝트 지침 전체

대화 중 이벤트 발생 시마다 증가

내 메시지, Claude 응답 — 매 턴마다 누적
파일 읽기 (Read) — 파일 크기만큼 즉시 추가
Bash/grep 결과 — 출력 크기만큼 추가
Path-scoped rules — 해당 경로 파일 읽을 때 자동 로드
Hook additionalContext — JSON으로 전달된 내용만 추가
스킬 호출 — 본문 전체 추가

/compact

대화 기록 전체를 구조화된 요약문 하나로 교체하여 컨텍스트를 확보

/compact                        # 기본 요약
/compact focus on the auth bug  # 특정 내용 중심으로 요약

compact 후 생존 여부

항목	/compact 후
System prompt	자동 재로드
CLAUDE.md (프로젝트 루트)	디스크에서 재로드
Auto memory (MEMORY.md)	자동 재로드
MCP tools	자동 재로드
호출했던 스킬 본문	재주입 (용량 초과 시 오래된 것부터 제거)
스킬 설명 목록(index)	재로드 안 됨 — 호출했던 스킬만 복원
대화 내용	구조화된 요약 1개로 대체
중첩 CLAUDE.md, path-scoped rules	재로드 안 됨 — 해당 파일 재접근 시 로드

/context 명령으로 현재 컨텍스트 사용량을 카테고리별로 확인 가능. Autocompact buffer(33k, 16.5%)는 자동 압축을 위해 예약된 공간.

실행 모드, 에이전트

Permission Modes

Shift+Tab으로 순환. 파일 수정, 셸 명령 실행 전 승인 요청 빈도를 제어

모드	자동 승인 범위	적합한 상황
`default`	읽기만	민감한 작업, 처음 시작
`acceptEdits`	읽기, 파일 편집, mkdir/mv 등	코드 리뷰하며 반복 작업
`plan`	읽기만 (파일 수정 금지)	구현 전 코드베이스 탐색
`auto`	백그라운드 안전 검사 후 대부분	긴 작업, 승인 피로 감소
`dontAsk`	사전 승인된 도구만	CI/CD, 스크립트
`bypassPermissions`	모든 것	격리된 컨테이너, VM 전용

Plan Mode vs Plan Subagent

이 둘은 서로 다른 레이어이며, 함께 작동한다.

Plan mode (Shift+Tab) = 퍼미션 모드. 파일 수정을 막는 실행 환경 설정
Plan subagent = Plan mode에서 코드베이스 탐색이 필요할 때 자동으로 위임되는 전문 서브에이전트

Plan mode 진입 (Shift+Tab)
    ↓
Claude: "코드베이스를 이해해야 한다"
    ↓ 탐색 필요 시 자동 위임
Plan subagent: 파일 읽기, grep, 분석 (별도 context)
    ↓ 요약만 반환
main context: 요약 수신 → 계획 작성 (main context에 남음)

핵심: 탐색 결과는 Plan subagent의 별도 컨텍스트에 격리되어 main context에 쌓이지 않는다. 계획 텍스트 자체는 main context에 남는다.

Built-in Subagents

세션 내부에서 side task를 처리하는 전문 보조. 별도 컨텍스트 윈도우에서 독립 실행

타입	역할	CLAUDE.md 로드	자동 위임 조건
Explore	코드베이스 탐색 전용 (수정 불가)	❌	탐색, 코드 이해 필요 시
Plan	Plan mode에서 탐색, 계획	❌	Plan mode + 코드 이해 필요 시
general-purpose	탐색 + 수정 + 복잡한 추론	✅	그 외 복합 작업

Explore, Plan이 CLAUDE.md를 로드하지 않는 이유: 빠르고 저렴하게 탐색하기 위함. main context가 CLAUDE.md를 갖고 있으므로 subagent까지 로드할 필요가 없다.

Agent View (Background Agents)

여러 Claude Code 세션을 하나의 화면에서 관리하는 TUI

  
claude agents                           # Agent View 열기
claude --bg "인증 버그 조사하고 수정해줘"  # 처음부터 백그라운드로 시작
/bg                                     # 진행 중인 세션을 백그라운드로 전환

세션 상태: Working, Needs input, Completed
→ 로 세션 attach, ← 로 detach (세션은 계속 실행)
각 백그라운드 세션은 별도 git worktree에서 파일 편집 → 병렬 실행 시 충돌 없음
서브에이전트는 별도 행으로 표시되지 않음 — 세션 내부에서 처리

스킬, 명령어, 설정

Skill 구조

/스킬명 으로 호출하는 재사용 가능한 지시문 번들

.claude/
  skills/
    deploy/
      SKILL.md    ← /deploy 로 호출됨

CLAUDE.md vs Skill 토큰 비교

항목	로드 시점	비용
CLAUDE.md 내용	매 세션 항상	항상 발생
스킬 설명(메타데이터)	매 세션 항상	소량 고정
스킬 본문(SKILL.md)	호출 시만	호출할 때만 발생

자주 쓰지 않는 긴 절차는 CLAUDE.md 대신 스킬로 분리하면 토큰 효율이 높아진다.

Built-in Skills

매 세션 자동으로 사용 가능한 내장 스킬 ([Skill]로 표시)

스킬	기능
`/code-review [effort] [--fix] [--comment]`	diff 버그, 정리 리뷰. `ultra`로 클라우드 심층 리뷰
`/simplify [target]`	코드 정리만 (버그 탐색 없음). 4개 에이전트 병렬 실행
`/verify`	앱 실제 실행해서 변경 동작 확인
`/run`	프로젝트 앱 실행, 동작 관찰
`/debug [description]`	디버그 로그 활성화, 세션 로그 분석
`/loop [interval] [prompt]`	프롬프트 반복 실행 (self-paced 가능)
`/batch <instruction>`	대규모 변경을 5~30개 단위로 분해, 병렬 subagent 실행
`/claude-api`	Claude API 레퍼런스 로드
`/fewer-permission-prompts`	허용 목록 자동 추가로 승인 요청 감소

Built-in Workflow (내부적으로 subagent를 팬아웃)

워크플로우	기능
`/deep-research <question>`	웹 검색 팬아웃 → 출처 교차 검증 → 인용 포함 리포트

Effort 레벨

/effort 명령으로 설정. 추론 깊이를 조절 (Fable 5, Opus 4.7+ 기준)

레벨	성격	권장 상황
`low`	최소 추론	단순 기계적 작업, 빠른 응답 필요
`medium`	중간 추론	일반적인 코딩 작업
`high`	깊은 추론	복잡한 버그, 아키텍처
`xhigh`	high보다 깊음, max 바로 아래	난이도 높은 설계 문제
`max`	최대 추론	가장 복잡한 추론 필요 시

개념 학습, Q&A 용도라면 medium 또는 high 정도로 충분. xhigh, max는 복잡한 수학 증명, 까다로운 디버깅에서 의미 있는 차이가 남.

Output Styles

/config → Output style 에서 설정. 시스템 프롬프트를 수정하므로 변경 후 /clear 또는 새 세션 필요

스타일	특징	적합한 상황
Default	기본 소프트웨어 엔지니어링 모드	일반 코딩 작업
Explanatory	작업 중간에 “Insights”로 개념, 패턴 설명	코딩하며 학습
Learning	Insights + `TODO(human)` 마커 삽입, 직접 구현 유도	코딩 실습 학습
Proactive	즉시 실행, 질문 최소화, 가정 후 진행	긴 자율 작업

원격 접속

Remote Control

로컬 머신에서 실행 중인 Claude Code 세션을 다른 디바이스에서 제어

  
claude remote-control          # 서버 모드 (터미널 점유, QR 코드 표시)
claude --remote-control        # 인터랙티브 세션 + 원격 제어 동시
/remote-control                # 진행 중인 세션에 원격 제어 추가

브라우저(claude.ai/code) 또는 Claude 모바일 앱으로 접속
세션은 로컬 머신에서 실행 — MCP, 파일시스템, 도구 모두 유지
여러 디바이스가 동시에 같은 세션에 접속 가능 (실시간 동기화)
/model, /effort 변경 등 세션 관리도 모바일에서 가능

모바일 푸시 알림 설정

Claude 모바일 앱 설치, Claude Code와 동일한 계정으로 로그인
알림 권한 허용
터미널에서 /config → Push when Claude decides 활성화
claude remote-control 또는 /remote-control 로 세션 시작

Channels

이미 실행 중인 Claude Code 세션에 외부 메시지를 밀어넣는 기능. Claude 앱 로그인 불필요

  
# Telegram 연결 예시
/plugin install telegram@claude-plugins-official
/telegram:configure <봇토큰>
claude --channels plugin:telegram@claude-plugins-official
# → 텔레그램에서 봇에게 메시지 전송 → 페어링 → Claude가 로컬에서 작업 후 텔레그램으로 응답

채널	설정 난이도	특징
iMessage	★☆☆	봇 불필요, 자신에게 문자. macOS 전용
Telegram	★★☆	BotFather로 봇 생성. 범용적
Discord	★★☆	개발자 포털에서 봇 생성, 서버 초대 필요

Pro, Max 플랜은 enterprise 설정 없이 바로 사용 가능.

Slack 통합 한계

Claude Code in Slack은 DM에서 작동하지 않음 — 채널(공개, 비공개)에서만 사용 가능
세션이 로컬이 아닌 Anthropic 클라우드에서 실행 — 로컬 파일, MCP 서버 접근 불가
Team, Enterprise 계정에서는 세션이 조직에 자동 공개
GitHub 연결 필수

원격 접속 방법 비교

방법	실행 위치	Claude 앱 필요	세션 전환(폰)	특징
Remote Control	내 로컬 머신	✅ (또는 브라우저)	✅	멀티 디바이스 동시 접속, 완전한 세션 제어
iMessage Channels	내 로컬 머신	❌	❌	가장 쉬운 설정, macOS 전용
Telegram Channels	내 로컬 머신	❌	❌	Claude 앱 없이 폰에서 메시지, 응답 수신
Slack	Anthropic 클라우드	❌	❌	DM 불가, 조직 공개, GitHub 필수

study

claude-code claude

This post is licensed under CC BY 4.0 by the author.