Claude Code의 작동 방식
출처: Anthropic 공식 문서 (한국어) — https://code.claude.com/docs/ko/how-claude-code-works
Claude Code는 터미널에서 실행되는 에이전트 어시스턴트입니다. 코딩에 탁월하지만 명령줄에서 할 수 있는 모든 작업을 도와줄 수 있습니다: 문서 작성, 빌드 실행, 파일 검색, 주제 조사 등.
에이전트 루프
Claude에게 작업을 주면 세 가지 단계를 거칩니다: 컨텍스트 수집, 작업 수행, 결과 검증. 이 단계들은 함께 진행됩니다.
- Claude는 파일을 검색하여 코드를 이해하든, 변경을 위해 편집하든, 작업을 확인하기 위해 테스트를 실행하든 전체적으로 도구를 사용합니다.
- 루프는 사용자가 요청한 내용에 맞게 조정됩니다:
- 코드베이스에 대한 질문 → 컨텍스트 수집만
- 버그 수정 → 세 단계 반복
- 리팩토링 → 광범위한 검증 포함
- Claude는 이전 단계에서 배운 내용을 바탕으로 각 단계에서 필요한 것을 결정하고, 수십 개의 작업을 연결하며 그 과정에서 방향을 수정합니다.
- 사용자도 이 루프의 일부입니다. 언제든지 중단하여 Claude를 다른 방향으로 유도하거나, 추가 컨텍스트를 제공하거나, 다른 접근 방식을 시도하도록 요청할 수 있습니다.
에이전트 루프는 두 가지 구성 요소로 구동됩니다: 추론하는 모델과 작용하는 도구. Claude Code는 Claude 주변의 에이전트 하네스 역할을 합니다: 언어 모델을 능력 있는 코딩 에이전트로 변환하는 도구, 컨텍스트 관리, 실행 환경을 제공합니다.
모델
Claude Code는 Claude 모델을 사용하여 코드를 이해하고 작업에 대해 추론합니다. Claude는 모든 언어의 코드를 읽을 수 있고, 구성 요소가 어떻게 연결되는지 이해하며, 목표를 달성하기 위해 무엇을 변경해야 하는지 파악할 수 있습니다.
복잡한 작업의 경우 작업을 단계로 나누고, 실행하고, 배운 내용을 바탕으로 조정합니다.
여러 모델을 사용할 수 있으며 각각 다른 장단점이 있습니다:
- Sonnet: 대부분의 코딩 작업을 잘 처리
- Opus: 복잡한 아키텍처 결정을 위한 더 강력한 추론
세션 중에 /model로 전환하거나 claude --model <name>으로 시작하세요.
도구
도구는 Claude Code를 에이전트로 만드는 것입니다. 도구가 없으면 Claude는 텍스트로만 응답할 수 있습니다. 도구가 있으면 Claude는 작용할 수 있습니다: 코드를 읽고, 파일을 편집하고, 명령을 실행하고, 웹을 검색하고, 외부 서비스와 상호작용합니다.
각 도구 사용은 루프에 다시 피드백되는 정보를 반환하여 Claude의 다음 결정을 알립니다.
내장 도구 범주
| 범주 | Claude가 할 수 있는 것 |
|---|---|
| 파일 작업 | 파일 읽기, 코드 편집, 새 파일 생성, 이름 변경 및 재구성 |
| 검색 | 패턴으로 파일 찾기, 정규식으로 콘텐츠 검색, 코드베이스 탐색 |
| 실행 | 셸 명령 실행, 서버 시작, 테스트 실행, git 사용 |
| 웹 | 웹 검색, 문서 가져오기, 오류 메시지 조회 |
| 코드 인텔리전스 | 편집 후 타입 오류 및 경고 확인, 정의로 이동, 참조 찾기 (코드 인텔리전스 플러그인 필요) |
에이전트 루프 예시
“실패한 테스트를 수정해”라고 말하면 Claude는:
- 테스트 스위트를 실행하여 무엇이 실패하는지 확인
- 오류 출력 읽기
- 관련 소스 파일 검색
- 해당 파일을 읽어 코드 이해
- 파일을 편집하여 문제 수정
- 테스트를 다시 실행하여 검증
기본 기능 확장
내장 도구는 기초입니다. skills로 Claude가 알 수 있는 것을 확장하고, MCP로 외부 서비스에 연결하고, hooks로 워크플로우를 자동화하고, subagents로 작업을 위임할 수 있습니다.
Claude가 접근할 수 있는 것
디렉토리에서 claude를 실행하면 Claude Code는 다음에 접근할 수 있습니다:
- 프로젝트: 디렉토리 및 하위 디렉토리의 파일, 그리고 허가를 받은 다른 곳의 파일
- 터미널: 실행할 수 있는 모든 명령 (빌드 도구, git, 패키지 관리자, 시스템 유틸리티, 스크립트)
- git 상태: 현재 브랜치, 커밋되지 않은 변경 사항, 최근 커밋 기록
- CLAUDE.md: 프로젝트별 지침, 규칙, 매 세션마다 알아야 할 컨텍스트
- 자동 메모리: Claude가 작업하면서 자동으로 저장하는 학습 내용 (MEMORY.md 처음 200줄 또는 25KB가 세션 시작 시 로드)
- 확장: MCP servers, skills, subagents, Claude in Chrome
Claude는 현재 파일만 보는 인라인 코드 어시스턴트와 다르게 전체 프로젝트에서 작업할 수 있습니다.
환경 및 인터페이스
실행 환경
| 환경 | 코드 실행 위치 | 사용 사례 |
|---|---|---|
| 로컬 | 사용자 머신 | 기본값. 파일, 도구, 환경에 대한 전체 접근 |
| 클라우드 | Anthropic 관리 VM | 작업 오프로드, 로컬에 없는 리포지토리에서 작업 |
| 원격 제어 | 사용자 머신, 브라우저에서 제어 | 웹 UI를 사용하면서 모든 것을 로컬로 유지 |
인터페이스
터미널, 데스크톱 앱, IDE 확장, claude.ai/code, 원격 제어, Slack, CI/CD 파이프라인을 통해 접근 가능. 인터페이스는 Claude를 보고 상호작용하는 방식을 결정하지만, 기본 에이전트 루프는 동일합니다.
세션으로 작업
Claude Code는 작업하면서 대화를 로컬에 저장합니다. 각 메시지, 도구 사용, 결과가 저장되어 되돌리기, 재개 및 포크 세션을 활성화합니다.
Claude가 코드를 변경하기 전에 영향을 받는 파일을 스냅샷하므로 필요하면 되돌릴 수 있습니다.
세션은 독립적입니다. 각 새 세션은 이전 세션의 대화 기록 없이 새로운 컨텍스트 윈도우로 시작합니다. Claude는 자동 메모리를 사용하여 세션 간에 학습을 유지할 수 있으며, CLAUDE.md에 지속적인 지침을 추가할 수 있습니다.
브랜치 간 작업
- Claude는 현재 브랜치의 파일을 봅니다. 브랜치를 전환하면 새 브랜치의 파일을 보지만 대화 기록은 유지됩니다.
- git worktrees를 사용하여 병렬 Claude 세션 실행 가능 (개별 브랜치에 대한 별도 디렉토리 생성).
세션 재개 또는 포크
claude --continue또는claude --resume: 동일한 세션 ID로 중단한 지점부터 재개claude --continue --fork-session: 원본에 영향 없이 새 세션 ID로 포크 (병렬 작업에 유용)- 여러 터미널에서 동일한 세션 재개 시 메시지가 인터리브됨 →
--fork-session으로 해결
컨텍스트 윈도우
Claude의 컨텍스트 윈도우는 대화 기록, 파일 콘텐츠, 명령 출력, CLAUDE.md, 자동 메모리, 로드된 skills, 시스템 지침을 보유합니다.
컨텍스트가 채워질 때
Claude Code는 한계에 접근할 때 자동으로 관리합니다:
- 먼저 이전 도구 출력을 지우고
- 필요하면 대화를 요약합니다
- 요청과 주요 코드 스니펫은 유지되지만 대화 초반의 자세한 지침이 손실될 수 있습니다
대책:
- 지속적인 규칙을 CLAUDE.md에 넣을 것
/context로 공간 사용 확인- CLAUDE.md에 “Compact Instructions” 섹션 추가
/compact를 포커스와 함께 실행 (예:/compact focus on the API changes)- MCP 도구 정의는 기본적으로 지연 로드 (도구 검색을 통해 요청 시 로드)
Skills 및 Subagents로 컨텍스트 관리
- Skills: 요청 시 로드됨. 세션 시작 시 설명만 보고, 전체 콘텐츠는 사용 시 로드.
disable-model-invocation: true로 완전히 지연 가능 - Subagents: 주 대화와 완전히 분리된 새로운 컨텍스트. 작업이 컨텍스트를 부풀리지 않고 완료 후 요약 반환
체크포인트 및 권한으로 안전 유지
체크포인트로 변경 취소
- 모든 파일 편집은 되돌릴 수 있습니다
- Claude가 파일을 편집하기 전에 현재 콘텐츠를 스냅샷합니다
- Esc를 두 번 눌러 이전 상태로 되돌리거나 Claude에게 취소 요청
- 체크포인트는 세션에 로컬이며 git과 분리됨
- 원격 시스템 (데이터베이스, API, 배포)에 영향을 주는 작업은 체크포인트 불가 → Claude는 외부 부작용이 있는 명령 실행 전 요청
Claude가 할 수 있는 것 제어
Shift+Tab으로 권한 모드 순환:
| 모드 | 설명 |
|---|---|
| 기본값 | Claude는 파일 편집 및 셸 명령 전에 요청 |
| 자동 수락 편집 | Claude는 파일을 편집하지만 명령은 여전히 요청 |
| 계획 모드 | Claude는 읽기 전용 도구만 사용하여 실행 전에 승인할 수 있는 계획 생성 |
| 자동 모드 | Claude는 백그라운드 안전 검사로 모든 작업을 평가 (연구 미리보기) |
.claude/settings.json에서 특정 명령을 허용하여 매번 요청하지 않도록 설정 가능 (예: npm test, git status).
Claude Code를 효과적으로 사용
Claude Code에 도움을 요청
Claude Code는 사용 방법을 가르칠 수 있습니다. 내장 명령:
/init: 프로젝트를 위한 CLAUDE.md 생성 안내/agents: 사용자 정의 subagents 구성 도움/doctor: 설치의 일반적인 문제 진단
대화입니다
완벽한 프롬프트가 필요하지 않습니다. 원하는 것으로 시작한 다음 개선하세요. 첫 번째 시도가 맞지 않으면 다시 시작할 필요 없이 반복합니다.
중단 및 조종
잘못된 경로로 가고 있으면 수정 사항을 입력하고 Enter를 누르세요. Claude는 작업을 중지하고 접근 방식을 조정합니다.
처음부터 구체적으로
특정 파일을 참조하고, 제약 조건을 언급하고, 예제 패턴을 지적하세요. 구체적인 프롬프트는 종종 첫 번째 시도에서 성공합니다.
Claude가 검증할 수 있는 것을 제공
테스트 케이스를 포함하고, 예상 UI의 스크린샷을 붙여넣거나, 원하는 출력을 정의하세요. Claude는 자신의 작업을 확인할 수 있을 때 더 잘 수행합니다.
구현 전에 탐색
복잡한 문제의 경우 연구와 코딩을 분리하세요. 계획 모드 (Shift+Tab 두 번)를 사용하여 먼저 코드베이스를 분석한 다음 구현하세요.
지시하지 말고 위임
능력 있는 동료에게 위임하는 것처럼 컨텍스트와 방향을 제공한 다음 Claude가 세부 사항을 파악하도록 신뢰하세요.
다음 단계
- 기능으로 확장: Skills, MCP 연결, 사용자 정의 명령 추가
- 일반적인 워크플로우: 일반적인 작업을 위한 단계별 가이드