Claude Code 작동 방식

에이전트 루프, 내장 도구, 그리고 Claude Code가 프로젝트와 상호작용하는 방식을 이해합니다.

Claude Code는 터미널에서 실행되는 에이전트 기반 어시스턴트입니다. 코딩에 뛰어나지만, 커맨드 라인에서 할 수 있는 모든 작업을 도와줄 수 있습니다: 문서 작성, 빌드 실행, 파일 검색, 주제 조사 등.

이 가이드는 핵심 아키텍처, 내장 기능, 그리고 효과적으로 작업하기 위한 팁을 다룹니다. 단계별 워크스루는 일반적인 워크플로우를 참조하세요. skills, MCP, hooks 같은 확장 기능은 Claude Code 확장을 참조하세요.

에이전트 루프

Claude에게 작업을 부여하면, 컨텍스트 수집, 행동 수행, 결과 검증의 세 단계를 거칩니다. 이 단계들은 서로 자연스럽게 연결됩니다. Claude는 코드를 이해하기 위해 파일을 검색하거나, 변경을 위해 편집하거나, 작업을 확인하기 위해 테스트를 실행하는 등 전 과정에서 도구를 사용합니다.

루프는 요청에 따라 적응합니다. 코드베이스에 대한 질문은 컨텍스트 수집만 필요할 수 있습니다. 버그 수정은 세 단계를 반복적으로 순환합니다. 리팩토링은 광범위한 검증을 수반할 수 있습니다. Claude는 이전 단계에서 학습한 내용을 바탕으로 각 단계에서 무엇이 필요한지 판단하며, 수십 개의 작업을 연결하고 진행 중에 경로를 수정합니다.

여러분도 이 루프의 일부입니다. 언제든지 개입하여 Claude의 방향을 전환하거나, 추가 컨텍스트를 제공하거나, 다른 접근 방식을 시도하도록 요청할 수 있습니다. Claude는 자율적으로 작업하지만 여러분의 입력에 항상 반응합니다.

에이전트 루프는 추론하는 모델과 행동하는 도구라는 두 가지 구성 요소로 작동합니다. Claude Code는 Claude를 감싸는 에이전트 하네스 역할을 합니다: 언어 모델을 유능한 코딩 에이전트로 만들어주는 도구, 컨텍스트 관리, 실행 환경을 제공합니다.

모델

Claude Code는 코드를 이해하고 작업을 추론하기 위해 Claude 모델을 사용합니다. Claude는 모든 언어의 코드를 읽고, 컴포넌트 간의 연결을 이해하며, 목표 달성을 위해 무엇을 변경해야 하는지 파악할 수 있습니다. 복잡한 작업의 경우 작업을 단계로 나누고, 실행하며, 학습한 내용을 바탕으로 조정합니다.

여러 모델을 사용할 수 있으며 각각 다른 트레이드오프를 가집니다. Sonnet은 대부분의 코딩 작업을 잘 처리합니다. Opus는 복잡한 아키텍처 결정에 대해 더 강력한 추론을 제공합니다. 세션 중에 /model로 전환하거나 claude --model <name>으로 시작할 수 있습니다.

이 가이드에서 "Claude가 선택한다" 또는 "Claude가 결정한다"라고 할 때, 추론을 수행하는 것은 모델입니다.

도구

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

내장 도구는 일반적으로 다섯 가지 범주로 분류되며, 각각 서로 다른 종류의 에이전시를 나타냅니다.

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

이것들이 주요 기능입니다. Claude에는 서브에이전트 생성, 질문하기, 기타 오케스트레이션 작업을 위한 도구도 있습니다. 전체 목록은 Claude에게 제공되는 도구를 참조하세요.

Claude는 프롬프트와 진행 중에 학습한 내용을 바탕으로 어떤 도구를 사용할지 선택합니다. "실패하는 테스트를 수정해줘"라고 하면, Claude는 다음과 같이 진행할 수 있습니다:

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

각 도구 사용은 Claude에게 다음 단계를 알려주는 새로운 정보를 제공합니다. 이것이 에이전트 루프의 실제 동작입니다.

기본 기능 확장: 내장 도구는 기반입니다. skills로 Claude가 아는 것을 확장하고, MCP로 외부 서비스에 연결하고, hooks로 워크플로우를 자동화하고, 서브에이전트에 작업을 위임할 수 있습니다. 이러한 확장은 핵심 에이전트 루프 위에 레이어를 형성합니다. 필요에 맞는 확장을 선택하는 방법은 Claude Code 확장을 참조하세요.

Claude가 접근할 수 있는 것

이 가이드는 터미널에 초점을 맞춥니다. Claude Code는 VS Code, JetBrains IDE, 기타 환경에서도 실행됩니다.

디렉토리에서 claude를 실행하면, Claude Code는 다음에 접근할 수 있습니다:

• 프로젝트. 디렉토리와 하위 디렉토리의 파일, 그리고 허가된 경우 다른 위치의 파일.
• 터미널. 실행할 수 있는 모든 명령: 빌드 도구, git, 패키지 매니저, 시스템 유틸리티, 스크립트. 커맨드 라인에서 할 수 있다면, Claude도 할 수 있습니다.
• git 상태. 현재 브랜치, 커밋되지 않은 변경사항, 최근 커밋 이력.
• CLAUDE.md. 프로젝트별 지침, 규칙, Claude가 매 세션마다 알아야 할 컨텍스트를 저장하는 마크다운 파일.
• 자동 메모리. Claude가 작업하면서 자동으로 저장하는 학습 내용으로, 프로젝트 패턴과 선호도 등입니다. MEMORY.md의 처음 200줄이 각 세션 시작 시 로드됩니다.
• 구성한 확장. 외부 서비스를 위한 MCP 서버, 워크플로우를 위한 skills, 위임 작업을 위한 서브에이전트, 브라우저 상호작용을 위한 Claude in Chrome.

Claude는 전체 프로젝트를 볼 수 있으므로 프로젝트 전반에 걸쳐 작업할 수 있습니다. "인증 버그를 수정해줘"라고 요청하면, 관련 파일을 검색하고, 여러 파일을 읽어 컨텍스트를 이해하고, 파일들에 걸쳐 조율된 편집을 수행하고, 테스트를 실행하여 수정을 검증하고, 요청하면 변경사항을 커밋합니다. 이것은 현재 파일만 볼 수 있는 인라인 코드 어시스턴트와 다릅니다.

환경과 인터페이스

위에서 설명한 에이전트 루프, 도구, 기능은 Claude Code를 사용하는 모든 곳에서 동일합니다. 달라지는 것은 코드가 실행되는 위치와 상호작용 방식입니다.

실행 환경

Claude Code는 세 가지 환경에서 실행되며, 코드가 실행되는 위치에 따라 각각 다른 트레이드오프를 가집니다.

환경	코드 실행 위치	사용 사례
로컬	사용자의 머신	기본값. 파일, 도구, 환경에 대한 전체 접근
클라우드	Anthropic 관리 VM	작업 오프로드, 로컬에 없는 저장소 작업
리모트 컨트롤	사용자의 머신, 브라우저에서 제어	모든 것을 로컬로 유지하면서 웹 UI 사용

인터페이스

터미널, 데스크톱 앱, IDE 확장, claude.ai/code, 리모트 컨트롤, Slack, CI/CD 파이프라인을 통해 Claude Code에 접근할 수 있습니다. 인터페이스에 따라 Claude를 보고 상호작용하는 방식이 달라지지만, 기본 에이전트 루프는 동일합니다. 전체 목록은 어디서나 Claude Code 사용하기를 참조하세요.

세션 작업

Claude Code는 작업하면서 대화를 로컬에 저장합니다. 각 메시지, 도구 사용, 결과가 저장되어 세션의 되감기, 재개 및 포크가 가능합니다. Claude가 코드를 변경하기 전에, 필요시 되돌릴 수 있도록 영향을 받는 파일의 스냅샷도 생성합니다.

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

브랜치 간 작업

각 Claude Code 대화는 현재 디렉토리에 연결된 세션입니다. 재개할 때는 해당 디렉토리의 세션만 표시됩니다.

Claude는 현재 브랜치의 파일을 봅니다. 브랜치를 전환하면 Claude는 새 브랜치의 파일을 보지만, 대화 이력은 그대로 유지됩니다. 브랜치를 전환한 후에도 Claude는 논의했던 내용을 기억합니다.

세션은 디렉토리에 연결되어 있으므로, 개별 브랜치를 위한 별도 디렉토리를 만드는 git worktrees를 사용하여 병렬 Claude 세션을 실행할 수 있습니다.

세션 재개 또는 포크

claude --continue 또는 claude --resume으로 세션을 재개하면, 동일한 세션 ID를 사용하여 중단한 곳에서 계속합니다. 새 메시지는 기존 대화에 추가됩니다. 전체 대화 이력이 복원되지만, 세션 범위 권한은 복원되지 않습니다. 해당 권한은 다시 승인해야 합니다.

원래 세션에 영향을 주지 않고 다른 접근 방식을 시도하려면 --fork-session 플래그를 사용하세요:

claude --continue --fork-session

이렇게 하면 해당 시점까지의 대화 이력을 보존하면서 새 세션 ID가 생성됩니다. 원래 세션은 변경되지 않습니다. 재개와 마찬가지로, 포크된 세션은 세션 범위 권한을 상속하지 않습니다.

여러 터미널에서 같은 세션: 같은 세션을 여러 터미널에서 재개하면, 두 터미널 모두 같은 세션 파일에 기록합니다. 양쪽의 메시지가 인터리브되어, 마치 두 사람이 같은 노트에 쓰는 것과 같습니다. 손상되지는 않지만, 대화가 뒤섞이게 됩니다. 각 터미널은 세션 중에는 자신의 메시지만 보지만, 나중에 해당 세션을 재개하면 모든 것이 인터리브된 것을 볼 수 있습니다. 같은 시작점에서 병렬 작업을 하려면 --fork-session을 사용하여 각 터미널에 고유한 깨끗한 세션을 제공하세요.

컨텍스트 윈도우

Claude의 컨텍스트 윈도우는 대화 이력, 파일 내용, 명령 출력, CLAUDE.md, 로드된 skills, 시스템 지침을 담고 있습니다. 작업할수록 컨텍스트가 채워집니다. Claude는 자동으로 압축하지만, 대화 초반의 지침이 손실될 수 있습니다. 영구적인 규칙은 CLAUDE.md에 넣고, /context를 실행하여 무엇이 공간을 차지하는지 확인하세요.

컨텍스트가 가득 찼을 때

Claude Code는 한계에 가까워지면 자동으로 컨텍스트를 관리합니다. 먼저 오래된 도구 출력을 지우고, 필요하면 대화를 요약합니다. 요청과 핵심 코드 스니펫은 보존됩니다; 대화 초반의 자세한 지침은 손실될 수 있습니다. 대화 이력에 의존하지 말고 영구적인 규칙은 CLAUDE.md에 넣으세요.

압축 시 보존되는 내용을 제어하려면, CLAUDE.md에 "Compact Instructions" 섹션을 추가하거나 /compact를 초점과 함께 실행하세요 (예: /compact focus on the API changes).

/context를 실행하여 무엇이 공간을 차지하는지 확인하세요. MCP 서버는 모든 요청에 도구 정의를 추가하므로, 몇 개의 서버만으로도 작업을 시작하기 전에 상당한 컨텍스트를 소비할 수 있습니다. /mcp를 실행하여 서버별 비용을 확인하세요.

skills와 서브에이전트로 컨텍스트 관리

압축 외에도, 컨텍스트에 로드되는 내용을 제어하기 위해 다른 기능을 사용할 수 있습니다.

Skills는 필요할 때 로드됩니다. Claude는 세션 시작 시 skill 설명을 보지만, 전체 내용은 skill이 사용될 때만 로드됩니다. 수동으로 호출하는 skills의 경우, disable-model-invocation: true를 설정하여 필요할 때까지 설명을 컨텍스트에서 제외할 수 있습니다.

서브에이전트는 메인 대화와 완전히 분리된 자체 컨텍스트를 받습니다. 서브에이전트의 작업은 컨텍스트를 비대하게 만들지 않습니다. 완료되면 요약을 반환합니다. 이 격리가 서브에이전트가 긴 세션에 도움이 되는 이유입니다.

각 기능의 비용은 컨텍스트 비용을, 컨텍스트 관리 팁은 토큰 사용량 줄이기를 참조하세요.

체크포인트와 권한으로 안전하게 유지

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

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

모든 파일 편집은 되돌릴 수 있습니다. Claude가 파일을 편집하기 전에 현재 내용의 스냅샷을 생성합니다. 문제가 생기면 Esc를 두 번 눌러 이전 상태로 되감거나, Claude에게 되돌리라고 요청하세요.

체크포인트는 세션에 로컬이며, git과는 별개입니다. 파일 변경사항만 다룹니다. 원격 시스템(데이터베이스, API, 배포)에 영향을 미치는 작업은 체크포인트할 수 없으며, 이것이 Claude가 외부 부작용이 있는 명령을 실행하기 전에 묻는 이유입니다.

Claude가 할 수 있는 작업 제어

Shift+Tab을 눌러 권한 모드를 순환할 수 있습니다:

• 기본: Claude가 파일 편집과 셸 명령 전에 확인을 요청
• 편집 자동 승인: Claude가 확인 없이 파일을 편집하고, 명령에 대해서만 확인 요청
• 플랜 모드: Claude가 읽기 전용 도구만 사용하여, 실행 전에 승인할 수 있는 계획을 생성

.claude/settings.json에서 특정 명령을 허용하여 Claude가 매번 묻지 않도록 할 수도 있습니다. 이는 npm test나 git status 같은 신뢰할 수 있는 명령에 유용합니다. 설정은 조직 전체 정책부터 개인 선호도까지 범위를 지정할 수 있습니다. 자세한 내용은 권한을 참조하세요.

---

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

이 팁들은 Claude Code에서 더 나은 결과를 얻는 데 도움이 됩니다.

Claude Code에게 도움 요청하기

Claude Code는 사용법을 알려줄 수 있습니다. "hooks를 어떻게 설정하나요?" 또는 "CLAUDE.md를 구성하는 가장 좋은 방법은?"과 같은 질문을 하면 Claude가 설명해줍니다.

내장 명령도 설정을 안내합니다:

• /init은 프로젝트를 위한 CLAUDE.md 생성을 안내합니다
• /agents는 커스텀 서브에이전트 구성을 도와줍니다
• /doctor는 설치의 일반적인 문제를 진단합니다

대화입니다

Claude Code는 대화형입니다. 완벽한 프롬프트가 필요하지 않습니다. 원하는 것부터 시작한 다음 다듬으세요:

Fix the login bug

[Claude가 조사하고, 무언가를 시도함]

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

[Claude가 접근 방식을 조정함]

첫 번째 시도가 맞지 않을 때, 처음부터 다시 시작하지 않습니다. 반복적으로 개선합니다.

중단하고 방향 전환

언제든지 Claude를 중단할 수 있습니다. 잘못된 방향으로 가고 있다면, 수정 내용을 입력하고 Enter를 누르세요. Claude는 하던 작업을 멈추고 입력에 따라 접근 방식을 조정합니다. 완료를 기다리거나 처음부터 다시 시작할 필요가 없습니다.

처음부터 구체적으로 지시

초기 프롬프트가 정확할수록 수정이 적게 필요합니다. 특정 파일을 참조하고, 제약 조건을 언급하고, 예시 패턴을 가리키세요.

The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.

모호한 프롬프트도 작동하지만, 방향을 잡는 데 더 많은 시간이 소요됩니다. 위와 같은 구체적인 프롬프트는 첫 번째 시도에서 성공하는 경우가 많습니다.

Claude에게 검증할 수 있는 것을 제공

Claude는 자체 작업을 확인할 수 있을 때 더 잘 수행합니다. 테스트 케이스를 포함하거나, 예상 UI의 스크린샷을 붙여넣거나, 원하는 출력을 정의하세요.

Implement validateEmail. Test cases: '[email protected]' → true,
'invalid' → false, '[email protected]' → false. Run the tests after.

시각적 작업의 경우, 디자인 스크린샷을 붙여넣고 Claude에게 구현과 비교하도록 요청하세요.

구현 전에 먼저 탐색

복잡한 문제의 경우, 조사와 코딩을 분리하세요. 플랜 모드(Shift+Tab 두 번)를 사용하여 먼저 코드베이스를 분석하세요:

Read src/auth/ and understand how we handle sessions.
Then create a plan for adding OAuth support.

계획을 검토하고, 대화를 통해 다듬은 다음, 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가 스스로 파악합니다.

다음 단계

• 기능으로 확장: Skills, MCP 연결, 커스텀 명령 추가
• 일반적인 워크플로우: 일반적인 작업에 대한 단계별 가이드