Claude Code 작동 방식

한 줄 요약: Claude Code 공식 문서 "How Claude Code works". Claude Code를 "추론하는 모델 + 행동하는 도구"로 도는 에이전트 루프(맥락 수집 → 행동 → 결과 확인)와 그 둘레의 하네스로 설명하고, Claude가 접근하는 것, 실행 환경 세 가지와 인터페이스, 세션(저장·재개·포크·브랜치), 컨텍스트 창이 찰 때의 동작, 두 안전장치(체크포인트·권한 모드), 잘 쓰는 요령(대화로 다듬기, 끼어들어 방향 잡기, 지시 대신 위임)을 다룬다.

원본 정보#

제목: How Claude Code works
발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
URL: https://code.claude.com/docs/en/how-claude-code-works (새 창)
수집(fetch)일: 2026-10-18. 본문의 명령, 단축키, 버전 조건(v2.1.283), 모델 이름은 이 날짜 기준이다.
성격: 입문 개요 문서다. 세부는 대부분 다른 문서(Common workflows, Extend Claude Code, Manage sessions, Checkpointing, Permissions, Best practices 등)로 넘긴다.

핵심 주장#

Claude Code는 에이전트 루프로 일한다. 작업을 받으면 맥락 수집(gather context), 행동(take action), 결과 확인(verify results) 세 단계를 거치고, 세 단계는 서로 섞인다. 루프는 요청에 맞춰 달라진다: 코드베이스 질문은 맥락 수집만, 버그 수정은 세 단계를 여러 번, 리팩터링은 확인을 많이 할 수 있다. Claude는 앞 단계에서 배운 것으로 다음 단계를 정하며 수십 개 동작을 이어 가고 도중에 방향을 고친다. 사용자도 루프의 일부라 언제든 끼어들 수 있다. → 에이전트 루프
루프를 움직이는 것은 모델과 도구, 그 둘레가 하네스다. 모델은 추론하고 도구는 행동한다. Claude Code는 모델 둘레에서 도구를 제공하고 모델이 보는 컨텍스트를 관리하는 층이며, 원본은 이 층을 "agentic harness"라고 부른다. 도구 없이는 텍스트로만 답할 수 있고, 도구를 쓸 때마다 돌아온 정보가 루프로 들어가 다음 결정을 이끈다. → 에이전트 루프, Claude Code
내장 도구는 크게 다섯 범주다. 파일 작업, 검색, 실행, 웹, 코드 인텔리전스(코드 인텔리전스 플러그인 필요). 이 밖에 서브에이전트 생성, 사용자에게 질문하기 같은 조율용 도구가 있다. 스킬·MCP·훅·서브에이전트는 이 기본 루프 위의 층이다. → Claude Code, Claude Code 확장 기능 고르기
세션은 독립적이고, 로컬에 기록되며, 파일 변경은 되돌릴 수 있다. 새 세션은 이전 대화 없이 빈 컨텍스트 창으로 시작하고, 세션을 넘는 지식은 자동 메모리와 CLAUDE.md가 잇는다. 대화는 ~/.claude/projects/ 아래 평문 JSONL로 저장돼 되감기·재개·포크가 가능하다. 파일을 편집하기 전에 스냅샷(체크포인트)을 남겨 Esc 두 번으로 되감을 수 있지만, 체크포인트는 파일 변경만 다루고 원격 시스템(데이터베이스, API, 배포)에 미친 동작은 되돌리지 못한다. 그쪽은 권한 모드와 권한 규칙으로 통제한다. → Claude Code 세션·체크포인트 다루기, 권한 모드
완벽한 프롬프트보다 대화와 위임이다. 원하는 것부터 말하고 고쳐 나가며, 첫 시도가 틀려도 처음부터 다시 하지 않는다. Esc로 멈추거나, 멈추지 않고 정정 메시지를 입력해 방향을 바꾼다. 유능한 동료에게 맡기듯 맥락과 방향을 주고, 어떤 파일을 읽고 어떤 명령을 돌릴지는 Claude가 정하게 한다. → Claude Code 세션·체크포인트 다루기

원본이 밝힌 세부 (2026-10-18 기준)#

도구 범주 (원본 표)

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

원본 예: "실패하는 테스트를 고쳐"라고 하면 Claude는 테스트를 돌리고, 오류 출력을 읽고, 관련 소스 파일을 찾아 읽고, 고치고, 테스트를 다시 돌려 확인할 수 있다("might"로 쓴 예시).

모델 (원본 당시 예시): 여러 모델을 쓸 수 있고 장단점이 다르다. 원본은 Sonnet이 대부분의 코딩 작업을 잘 다루고 Opus가 복잡한 아키텍처 결정에 더 강한 추론을 준다고 쓴다. 세션 중 /model로 바꾸거나 claude --model <name>으로 시작한다. 원본에서 "Claude가 고른다·정한다"는 모델이 추론한다는 뜻이다.

Claude가 접근하는 것 (claude를 실행한 디렉터리 기준)

프로젝트: 그 디렉터리와 하위 디렉터리의 파일, 그리고 사용자 허락을 받은 다른 곳의 파일
터미널: 사용자가 명령줄에서 할 수 있는 모든 명령(빌드 도구, git, 패키지 관리자, 시스템 유틸리티, 스크립트). 원본 표현은 "If you can do it from the command line, Claude can too"이다. 실제로 묻지 않고 실행하는 범위는 권한 모드와 규칙이 정한다(권한 모드).
git 상태: 현재 브랜치, 커밋하지 않은 변경, 최근 커밋 기록
CLAUDE.md: 매 세션 알아야 할 프로젝트 지시. 다른 코딩 에이전트용 AGENTS.md가 있으면 CLAUDE.md 대신 읽을 수 있다. → 메모리(CLAUDE.md)
자동 메모리: MEMORY.md의 앞 200줄 또는 25KB 중 먼저 닿는 쪽이 매 세션 시작 때 로드된다. → 자동 메모리(Auto memory)
설정한 확장: MCP 서버, 스킬, 서브에이전트, 브라우저 조작용 Claude in Chrome

원본은 프로젝트 전체를 보기 때문에 "인증 버그를 고쳐" 같은 요청에서 여러 파일을 찾아 읽고, 여러 파일을 함께 고치고, 테스트로 확인하고, 요청하면 커밋까지 한다고 말하며, 현재 파일만 보는 인라인 코드 도우미와 다르다고 대비한다.

실행 환경 (원본 표)

환경	코드가 도는 곳	쓰임
Local	내 컴퓨터	기본값. 내 파일·도구·환경에 전부 접근
Cloud	Anthropic 관리 VM, 또는 조직이 운영하는 self-hosted 환경	작업 넘기기, 로컬에 없는 저장소 작업
Remote Control	내 컴퓨터, 브라우저에서 조종	웹 UI를 쓰면서 실행과 파일은 로컬에

인터페이스는 터미널, 데스크톱 앱, IDE 확장, claude.ai/code, Remote Control, Slack, CI/CD 파이프라인이다. 원본은 인터페이스가 보고 상호작용하는 방식만 바꾸고 에이전트 루프·도구·능력은 어디서나 같다고 말한다.

세션

/resume 선택 창은 기본으로 현재 worktree의 세션을 보여 주고, 단축키로 다른 worktree·프로젝트까지 넓힌다.
브랜치를 바꾸면 Claude는 새 브랜치의 파일을 보지만 대화 기록은 그대로다.
세션이 디렉터리에 묶이므로 git worktree로 브랜치별 디렉터리를 만들어 Claude 세션을 병렬로 돌릴 수 있다.
claude --continue·claude --resume은 같은 세션 ID로 다시 열어 기존 대화에 이어 쓴다. --fork-session이나 /branch는 기록을 새 세션 ID로 복사하고 원래 세션은 그대로 둔다.

컨텍스트 창

컨텍스트 창에는 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 스킬, 시스템 지시가 들어간다. 자동으로 컴팩션하지만 대화 초반의 지시는 사라질 수 있으니 지속 규칙은 CLAUDE.md에 둔다.
Claude Code가 스스로 더하는 컨텍스트(system reminder): CLAUDE.md 파일, 출력 스타일 지시, 앞서 읽은 파일이 디스크에서 바뀌었다는 알림, 커밋·PR 서명(attribution) 줄. 사용자가 쓰지 않은 규칙(예: 커밋에 Co-Authored-By 붙이기)을 Claude가 따르면 여기서 왔을 수 있다. 서명 줄은 attribution, 내장 커밋·PR 지침은 includeGitInstructions: false로 바꾸거나 끈다.
한도에 가까워지면 오래된 도구 출력부터 지우고, 필요하면 대화를 요약한다. 요청과 핵심 코드 조각은 남고, 대화 초반의 자세한 지시는 사라질 수 있다.
컴팩션 때 무엇을 남길지는 CLAUDE.md에 "Compact Instructions" 절을 두거나 /compact focus on the API changes처럼 초점을 주어 정한다.
파일 하나나 도구 출력 하나가 너무 커서 요약 직후 다시 차면, 몇 번 시도한 뒤 자동 컴팩션을 멈추고 반복하는 대신 오류를 보여 준다(복구 절차는 원본이 Troubleshooting 문서로 넘김).
MCP 도구 정의는 기본으로 미뤄져 tool search로 필요할 때 로드되므로, 특정 도구를 쓰기 전까지는 도구 이름과 서버 지시만 컨텍스트를 쓴다.
스킬은 시작 때 설명만 보이고 전체 내용은 쓸 때 로드된다. 직접 부르는 스킬은 disable-model-invocation: true로 설명도 빼고, 직접 쓰지 않은 스킬은 설정의 skillOverrides로 같은 효과를 낸다.
서브에이전트는 자기 컨텍스트 창에서 일한다. 포크가 아니면 새로 시작하고, 포크는 지금까지 대화의 사본으로 시작한다. 어느 쪽이든 서브에이전트의 도구 호출은 메인 컨텍스트에 들어오지 않고, 끝나면 요약이 돌아온다.

체크포인트와 권한

체크포인트: 파일을 편집하기 전에 현재 내용을 스냅샷한다. Esc 두 번으로 이전 상태로 되감거나 Claude에게 되돌려 달라고 한다. git과 별개이고 대화를 재개해도 남는다. 파일 변경만 다루고, 복원은 심볼릭 링크·하드 링크 파일을 건너뛴다. 원격 시스템에 미친 동작은 체크포인트할 수 없다.
권한 모드: Shift+Tab으로 순환한다. 원본이 든 네 모드: Auto(분류기가 대부분의 동작을 백그라운드에서 검토해 위험한 것은 묻는 대신 막는다. v2.1.283 이상에서는 대화형 터미널·VS Code 세션의 내장 시작 모드, 그 이전 버전에서는 Pro·Max·Team 플랜에서만), Manual(파일 편집과 셸 명령 전에 묻는다), Accept edits(파일 편집과 mkdir·mv 같은 흔한 파일 시스템 명령은 묻지 않고, 다른 명령은 묻는다), Plan(소스 파일을 고치지 않고 살펴보고 계획을 제안). 원본은 이 문서에서 dontAsk·bypassPermissions를 다루지 않는다.
.claude/settings.json에서 npm test·git status 같은 믿을 만한 명령을 미리 허용할 수 있고, 설정은 조직 정책부터 개인 선호까지 범위를 나눈다(세부는 Permissions 문서. 2026-10-21 수집: Claude Code 권한 설정, 규칙 문법은 Claude Code 권한 규칙 문법).

도움 받기: "훅은 어떻게 설정해?"처럼 Claude Code에게 사용법을 물을 수 있다. /init은 시작용 CLAUDE.md를 만들고, /doctor는 설치·설정 문제를 진단하고 고칠 수 있다.

끼어들어 방향 잡기

Esc: 즉시 멈춘다. 실행 중인 도구 호출이 취소되고 Claude는 다음 지시를 기다린다. 대기열에 메시지가 있으면 그것을 다음에 보낸다.
정정을 입력하고 Enter: 멈추지 않는다. 메시지는 대기열에 표시되고, Claude가 도구 호출 중이면 그 호출들이 끝나는 대로 같은 턴 안에서 읽고 다음 단계 전에 조정한다.

원본 예시 프롬프트(위임): "The checkout flow is broken for users with expired cards. The relevant code is in src/payments/. Can you investigate and fix it?"

원본이 링크한 관련 문서#

Common workflows, Extend Claude Code(→ Claude Code 확장 기능 개요), Model configuration, Tools reference, code intelligence 플러그인, self-hosted environments, desktop·VS Code·Remote Control·Slack·GitHub Actions, Manage sessions(세션 선택 창 단축키, 같은 세션을 두 터미널에서 열 때), worktrees, ~/.claude 애플리케이션 데이터(경로·보존 기간·지우는 법), glossary의 system reminder, settings reference(attribution, includeGitInstructions), Agent SDK의 "Turn off the context your agent replaces", Troubleshooting의 thrashing 오류, Checkpointing(링크 파일 복원 제외), Permissions, interactive mode의 메시지 대기열, Best practices, costs의 토큰 줄이기