Claude Code는 어떻게 동작하나

Claude Code는 어떻게 동작하나

Claude Code는 터미널에서 실행되는 에이전틱 어시스턴트입니다. 코딩에 특히 뛰어나지만, 셸에서 할 수 있는 것이라면 문서 작성, 빌드 실행, 파일 검색, 주제 조사 등 무엇이든 도와줍니다. 이 가이드는 핵심 아키텍처, 내장 기능, 효과적으로 작업하는 팁을 다룹니다.

출처: 공식문서

본문

단계별 워크스루는 Common workflows를, 스킬·MCP·훅 같은 확장 기능은 Extend Claude Code를 참고하세요.

에이전틱 루프

Claude에게 태스크를 주면 세 단계로 작업합니다: 컨텍스트 수집(gather context), 행동(take action), 결과 검증(verify results). 이 단계들은 겹쳐 있습니다. Claude는 코드를 이해하려 파일을 검색하고, 변경하려 편집하고, 작업을 확인하려 테스트를 실행하는 등 도처에서 도구를 사용합니다.

루프는 무엇을 묻느냐에 따라 달라집니다. 코드베이스에 대한 질문은 컨텍스트 수집만으로 충분할 수 있고, 버그 수정은 세 단계를 반복해서 순환하며, 리팩터링은 광범위한 검증을 수반할 수 있습니다. Claude는 이전 단계에서 배운 내용으로 각 단계가 무엇을 요구하는지 결정해 수십 개의 행동을 연결하고 그 과정에서 코스를 수정합니다.

당신도 이 루프의 일부입니다. 언제든 중단해 Claude를 다른 방향으로 이끌고, 추가 컨텍스트를 제공하거나 다른 접근을 요청할 수 있습니다. Claude는 자율적으로 작업하지만 입력에 반응합니다.

에이전틱 루프는 두 구성요소로 구동됩니다: 추론하는 모델과 행동하는 도구. Claude Code는 Claude 주변의 에이전틱 하네스(agentic harness) 역할을 합니다: 도구, 컨텍스트 관리, 실행 환경을 제공해 언어 모델을 유능한 코딩 에이전트로 만듭니다.

모델

Claude Code는 Claude 모델로 코드를 이해하고 태스크에 대해 추론합니다. Claude는 어떤 언어의 코드든 읽고, 컴포넌트가 어떻게 연결되는지 이해하며, 목표를 이루기 위해 무엇을 바꿔야 하는지 파악합니다. 복잡한 태스크는 작업을 단계로 나눠 실행하고 배운 내용에 따라 조정합니다.

여러 모델이 서로 다른 트레이드오프로 제공됩니다. Sonnet은 대부분의 코딩 태스크를 잘 처리하고, Opus는 복잡한 아키텍처 결정에 더 강한 추론을 제공합니다. 세션 중 /model로 바꾸거나 claude --model <name>으로 시작하세요. 이 가이드가 "Claude가 선택한다" 또는 "Claude가 결정한다"고 말하면 모델이 추론을 수행하는 것입니다.

도구

도구가 Claude Code를 에이전틱하게 만듭니다. 도구가 없으면 Claude는 텍스트로만 응답할 수 있습니다. 도구가 있으면 Claude는 행동할 수 있습니다: 코드 읽기, 파일 편집, 명령 실행, 웹 검색, 외부 서비스와 상호작용. 각 도구 사용은 루프에 다시 피드백되어 Claude의 다음 결정을 알리는 정보를 반환합니다.

내장 도구는 대체로 다섯 범주로 나뉘며, 각각 다른 종류의 에이전시를 나타냅니다.

범주 Claude가 할 수 있는 일
파일 연산 파일 읽기, 코드 편집, 새 파일 생성, 이름 바꾸기·재구성
검색 패턴으로 파일 찾기, 정규식으로 내용 검색, 코드베이스 탐색
실행 셸 명령 실행, 서버 시작, 테스트 실행, git 사용
웹 웹 검색, 문서 가져오기, 에러 메시지 조회
코드 인텔리전스 편집 후 타입 오류·경고 확인, 정의로 이동, 참조 찾기 (code intelligence 플러그인 필요)

클로드가 서브에이전트 생성, 질문, 기타 오케스트레이션 태스크를 위한 도구도 있습니다. 전체 목록은 Tools available to Claude 참고.

Claude는 프롬프트와 그 과정에서 배운 내용을 바탕으로 도구를 선택합니다. "fix the failing tests"라고 하면 Claude는:

  1. 테스트 스위트를 실행해 무엇이 실패하는지 확인
  2. 에러 출력을 읽음
  3. 관련 소스 파일 검색
  4. 파일을 읽어 코드 이해
  5. 파일을 편집해 이슈 수정
  6. 테스트를 다시 실행해 검증

기본 능력 확장: 내장 도구는 토대입니다. 스킬로 Claude의 지식을 확장하고, MCP로 외부 서비스에 연결하며, 훅으로 워크플로를 자동화하고, 서브에이전트로 태스크를 위임할 수 있습니다. 이런 확장은 핵심 에이전틱 루프 위의 레이어를 이룹니다. 올바른 확장 선택은 Extend Claude Code 참고.

Claude가 접근할 수 있는 것

디렉터리에서 claude를 실행하면 Claude Code는 다음에 접근합니다:

  • 프로젝트. 디렉터리와 하위 디렉터리의 파일, 그리고 허락된 경우 다른 곳의 파일.
  • 터미널. 빌드 도구, git, 패키지 매니저, 시스템 유틸리티, 스크립트 등 실행할 수 있는 모든 명령.
  • git 상태. 현재 브랜치, 커밋되지 않은 변경, 최근 커밋 기록.
  • CLAUDE.md. 매 세션 Claude가 알아야 할 프로젝트별 지침·관례·컨텍스트를 저장하는 마크다운 파일.
  • 자동 메모리. 작업하며 선호도처럼 Claude가 자동으로 저장하는 학습. MEMORY.md의 처음 200줄 또는 25KB 중 먼저 도달하는 쪽이 매 세션 시작 시 로드됩니다.
  • 구성한 확장. 외부 서비스용 MCP 서버, 워크플로용 스킬, 위임 작업용 서브에이전트, 브라우저 상호작용용 Claude in Chrome.

Claude가 전체 프로젝트를 보므로 프로젝트 전반에서 작업할 수 있습니다. "fix the authentication bug"라고 하면 관련 파일을 검색하고, 여러 파일을 읽어 컨텍스트를 이해하고, 걸쳐 조정된 편집을 하고, 테스트로 검증하며, 요청하면 변경을 커밋합니다. 이는 현재 파일만 보는 인라인 코드 어시스턴트와 다릅니다.

환경과 인터페이스

에이전틱 루프·도구·능력은 어디서 쓰든 동일합니다. 바뀌는 것은 코드가 어디서 실행되고 어떻게 상호작용하느냐입니다.

실행 환경

환경 코드가 실행되는 곳 사용 사례
로컬 내 머신 기본. 파일·도구·환경에 완전 접근
클라우드 Anthropic 관리 VM 또는 셀프호스팅 환경 태스크 오프로드, 로컬에 없는 레포 작업
Remote Control 내 머신(브라우저에서 제어) 실행·파일은 로컬로 유지하면서 웹 UI 사용

인터페이스 — 터미널, 데스크톱 앱, IDE 확장, claude.ai/code, Remote Control, Slack, CI/CD 파이프라인으로 접근할 수 있습니다. 인터페이스는 Claude를 보는 방식만 정하며, 밑바탕의 에이전틱 루프는 동일합니다.

세션 작업

Claude Code는 작업하며 대화를 로컬에 저장합니다. 각 메시지·도구 사용·결과는 ~/.claude/projects/ 아래의 평문 JSONL 파일에 기록되어 되감기, 재개·포크를 가능하게 합니다. 코드 변경 전에는 해당 파일을 스냅샷해 필요 시 되돌릴 수 있습니다. 경로·보존·삭제는 ~/.claude의 애플리케이션 데이터 참고.

세션은 독립적입니다. 각 새 세션은 이전 세션의 대화 기록 없이 새 컨텍스트 윈도우로 시작합니다. Claude는 자동 메모리로 세션 간 학습을 유지하고, CLAUDE.md에 영구 지침을 추가할 수 있습니다.

브랜치 간 작업

각 대화는 현재 디렉터리에 묶인 세션입니다. /resume 피커는 기본적으로 현재 워크트리의 세션을 보여주며, 단축키로 다른 워크트리·프로젝트로 목록을 넓힐 수 있습니다. 브랜치를 바꾸면 Claude는 새 브랜치의 파일을 보지만 대화 기록은 유지됩니다. 세션이 디렉터리에 묶이므로 git worktrees로 병렬 Claude 세션을 실행할 수 있습니다.

세션 재개 또는 포크

claude --continue 또는 claude --resume으로 세션을 재개하면 같은 세션 ID로 다시 열고 기존 대화에 새 메시지를 덧붙입니다. --fork-session 또는 /branch로 포크하면 기록을 새 세션 ID로 복사해 원본은 그대로 둡니다. 재개 플래그, /resume 피커, 명명, 같은 세션이 두 터미널에서 열릴 때는 Manage sessions 참고.

컨텍스트 윈도우

Claude의 컨텍스트 윈도우는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 스킬, 시스템 지침을 담습니다. 작업하며 컨텍스트가 차오릅니다. Claude는 자동 컴팩트하지만 대화 초반의 지침은 유실될 수 있습니다. 영구 규칙은 CLAUDE.md에 두고, /context로 무엇이 공간을 쓰는지 확인하세요. 대화형 워크스루는 Explore the context window 참고.

컨텍스트가 꽉 차면 — Claude Code는 한계에 접근하면서 자동으로 관리합니다. 먼저 오래된 도구 출력을 지우고, 필요하면 대화를 요약합니다. 요청과 핵심 코드 스니펫은 보존되지만 대화 초반의 상세 지침은 유실될 수 있습니다. 컴팩션 시 보존할 내용을 제어하려면 CLAUDE.md에 "Compact Instructions" 섹션을 추가하거나 /compact를 포커스와 함께 실행하세요(예: /compact focus on the API changes). 단일 파일·도구 출력이 너무 커 매 요약 후 컨텍스트가 즉시 다시 차면, Claude Code는 몇 번 시도 후 자동 컴팩트를 멈추고 루프 대신 에러를 표시합니다. 복구는 Auto-compaction stops with a thrashing error 참고. MCP 도구 정의는 기본적으로 지연되어 tool search로 온디맨드 로드되므로, Claude가 특정 도구를 쓰기 전까지는 도구 이름과 서버 지침만 컨텍스트를 소비합니다.

스킬·서브에이전트로 컨텍스트 관리 — 스킬은 온디맨드 로드됩니다. 세션 시작 시 Claude는 스킬 설명만 보고, 전체 내용은 사용될 때 로드됩니다. 수동으로 호출하는 스킬은 disable-model-invocation: true를 설정해 설명을 컨텍스트 밖에 두세요. 직접 작성하지 않은 스킬은 skillOverrides로 설정에서 동일하게 합니다. 서브에이전트는 자기 컨텍스트 윈도우에서 작업합니다. 포크가 아니라면 서브에이전트는 새로 시작하고, 포크는 지금까지의 대화 복사본으로 시작합니다. 어느 쪽이든 서브에이전트의 도구 호출은 내 컨텍스트 밖에 있고, 끝나면 요약을 돌려받습니다. 컨텍스트 비용은 context costs, 토큰 절감 팁은 reduce token usage 참고.

체크포인트·권한으로 안전하게

Claude에는 두 안전 메커니즘이 있습니다: 체크포인트는 파일 변경을 되돌리고, 권한은 Claude가 묻지 않고 할 수 있는 것을 제어합니다.

체크포인트로 변경 되돌리기

파일 편집은 되돌릴 수 있습니다. 파일 편집 전에 현재 내용을 스냅샷합니다. 문제가 생기면 Esc를 두 번 눌러 이전 상태로 되감거나 Claude에게 되돌리라고 합니다. 체크포인트는 git과 별개이며 대화 재개 시에도 유지됩니다. 파일 변경만 다루고, 복원은 심볼릭·하드링크 파일을 건너뜁니다. 데이터베이스·API·배포처럼 원격 시스템에 영향을 주는 동작은 체크포인트할 수 없습니다. 그런 것은 권한 모드와 권한 규칙으로 제어합니다.

Claude가 할 수 있는 것 제어

권한 모드를 선택해 Claude가 묻지 않고 할 수 있는 것을 정합니다. Shift+Tab으로 권한 모드를 순환합니다:

  • Auto: 분류기가 대부분의 작업을 백그라운드에서 검토하고 위험한 것은 묻는 대신 차단합니다. Pro·Max·Team 요금제에서 인터랙티브 터미널·VS Code 세션의 기본 시작 권한 모드.
  • Manual: Claude가 파일 편집과 셸 명령 전에 묻습니다.
  • Accept edits: Claude가 파일을 편집하고 mkdir, mv 같은 일반 파일시스템 명령은 묻지 않고 실행하며, 다른 명령은 여전히 묻습니다.
  • Plan: Claude가 소스 파일을 편집하지 않고 탐색하고 플랜을 제안합니다.

.claude/settings.json에서 특정 명령을 허용해 매번 묻지 않게 할 수도 있습니다. npm test, git status 같은 신뢰하는 명령에 유용합니다. 조직 전역 정책부터 개인 선호까지 범위를 조정할 수 있습니다. 자세한 내용은 Permissions 참고.

Claude Code와 효과적으로 작업하기

Claude Code는 Claude Code 사용법을 가르칠 수 있습니다. "how do I set up hooks?" 같은 질문을 하면 설명해 줍니다. 내장 명령도 도와줍니다: /init이 프로젝트용 CLAUDE.md 생성을 안내하고, /doctor가 설치·구성 문제를 진단하고 고칠 수 있습니다.

대화입니다. 완벽한 프롬프트는 필요 없습니다. 원하는 것으로 시작한 뒤 다듬으세요:

Fix the login bug

[Claude가 조사하고 뭔가 시도]

That's not quite right. The issue is in the session handling.

[Claude가 접근을 조정] 첫 시도가 틀려도 처음부터 다시 시작하지 않습니다. 반복합니다.

중단하고 방향 바꾸기 — 턴이 끝나기를 기다리거나 다시 시작하지 않고 언제든 리다이렉트할 수 있습니다:

  • Esc를 눌러 즉시 중단. 실행 중인 도구 호출이 취소되고 Claude가 다음 지침을 기다립니다. 대기 중인 메시지가 있으면 다음에 보냅니다.
  • 수정 사항을 입력하고 Enter 를 눌러 실행 중인 도구를 멈추지 않고 전송. Claude는 현재 작업이 끝나자마자 읽고 다음 단계를 결정하기 전에 조정합니다.

지시가 아니라 위임하기 — 유능한 동료에게 위임하듯이. 컨텍스트와 방향을 주고 Claude가 세부를 파악하도록 신뢰하세요:

The checkout flow is broken for users with expired cards.
The relevant code is in src/payments/. Can you investigate and fix it?

어떤 파일을 읽을지, 어떤 명령을 실행할지 지정할 필요가 없습니다. Claude가 알아서 파악합니다.

다음 단계

Extend with features로 스킬·MCP 연결을 추가하고, Common workflows로 일반 태스크 단계별 가이드를 보세요.

더 알아보기