출처 본문은 Anthropic의 공식 문서 How Claude Code works를 참고해 요약·번역했습니다. agentic loop, harness, tool, MCP, skill, hook, subagent, checkpoint, compaction 등 제품·프로토콜 용어는 원문 표기를 유지했습니다. 아래 다이어그램 이미지 URL은 해당 문서와 동일한 mintcdn 자산입니다. 최신 세부사항은 원문을 따르세요.
Claude Code는 터미널에서 돌아가는 agentic 어시스턴트다. 코딩에 강하지만, 명령줄에서 할 수 있는 일—문서 작성, 빌드 실행, 파일 검색, 주제 조사 등—을 넓게 돕는다. 이 글에서는 핵심 구조·기본 기능·세션과 컨텍스트를 짚고, 실사용 팁은 원문의 Work effectively with Claude Code 섹션과 Common workflows, 확장은 Extend Claude Code를 보라고 안내한다.
The agentic loop
작업을 주면 Claude는 대략 세 단계를 오간다: gather context(맥락 모으기), take action(행동), verify results(결과 확인). 이 단계들은 뒤섞이며 반복된다. 파일을 읽어 코드를 이해하고, 편집으로 바꾸고, 테스트로 검증하는 식으로 tool을 끊임없이 쓴다.
루프는 요청에 맞게 얇아지거나 두꺼워진다. 코드베이스 질문은 맥락 수집만으로 끝날 수 있고, 버그 수정은 세 단계를 여러 번 돈다. 사용자도 루프 안에 있다—언제든 끼어들어 방향을 바꾸거나 추가 맥락을 줄 수 있다.
루프는 두 축으로 돈다 — (1) 추론하는 model, (2) 행동하는 tool. 모델이 상황을 판단하면 tool이 실제 세계에 작용하고, 그 결과가 다시 모델의 다음 판단 입력이 된다.
Claude Code는 이 구조를 감싸는 agentic harness다. tool 목록, 컨텍스트 관리, 실행 환경을 갖춰 LLM이 실제 코딩 에이전트로 동작할 수 있게 한다.
Models
Claude Code는 Claude 모델로 코드를 읽고 작업을 쪼갠 뒤, 배운 것에 맞춰 다음 행동을 고른다. 세션 중 /model으로 바꾸거나 claude --model <name>으로 시작할 수 있다(자세한 트레이드오프는 Model config).
Tools
Tool이 없으면 Claude는 텍스트만 낼 수 있고, tool이 있으면 파일 읽기·편집, 셸 실행, 웹 검색, 외부 서비스 호출까지 할 수 있다. 한 tool 호출의 결과가 다음 판단의 입력이 된다—이게 agentic loop의 본질이다.
문서에서 말하는 built-in tool 범주는 대략 다음과 같다(전체 목록은 Tools available to Claude).
| Category | 할 수 있는 일(요약) |
|---|---|
| File operations | 읽기, 편집, 새 파일, 이름 변경·재배치 |
| Search | 패턴으로 파일 찾기, 정규식 검색, 코드베이스 탐색 |
| Execution | 셸, 서버 기동, 테스트, git |
| Web | 검색, 문서 fetch, 에러 메시지 조회 |
| Code intelligence | 편집 후 타입·경고, 정의로 이동, 참조 찾기(플러그인 필요, discover-plugins) |
기본 tool 위에 skills, MCP, hooks, subagents 같은 확장이 얹힌다.
Claude가 접근하는 것
claude를 디렉터리에서 실행하면 대략 다음에 닿을 수 있다(권한은 설정·프롬프트에 따름).
- 프로젝트 — 해당 디렉터리와 하위, 허락된 다른 경로
- 터미널 — 사용자가 셸에서 돌릴 수 있는 명령과 같은 범주
- git 상태 — 브랜치, 미커밋 변경, 최근 커밋
- CLAUDE.md — 프로젝트별 지시·관례
- Auto memory — 작업 중 자동 저장 학습; 세션 시작 시 MEMORY.md 앞부분(문서 기준 첫 200줄 또는 25KB 중 먼저 도달)이 로드된다
- 설정한 확장 — MCP, skills, subagents, Claude in Chrome 등
인라인 어시스턴트가 “지금 파일”만 보는 것과 달리, 프로젝트 전체를 가로지르는 작업(여러 파일 수정 후 테스트 등)에 맞춰져 있다는 설명이 문서의 요지다.
환경과 인터페이스
Execution은 코드가 어디서 돌아가느냐의 차이이고, interface는 어떻게 보이느냐의 차이다. agentic loop 자체는 동일하다고 문서는 정리한다.
| Environment | 코드 실행 위치 | 용도 요약 |
|---|---|---|
| Local | 사용자 머신 | 기본. 파일·도구·환경에 대한 전체 접근 |
| Cloud | Anthropic 관리 VM | 로컬에 없는 저장소 작업 등 오프로드 |
| Remote Control | 사용자 머신을 브라우저가 원격 조종 | 웹 UI를 쓰되 실행은 로컬에 유지 |
터미널·데스크톱 앱·IDE 확장·claude.ai/code·Remote Control·Slack·CI/CD 등에서 접근할 수 있다(전체 개요).
세션
대화는 로컬에 JSONL로 쌓인다(~/.claude/projects/ 아래). 덕분에 되감기(checkpoint), 재개·포크가 가능하다. 코드 변경 전에는 영향 파일 스냅샷도 남긴다. 보존·삭제는 application data in ~/.claude를 본다.
세션은 서로 독립이다—새 세션은 이전 대화 없이 새 context window로 시작한다. 세션을 넘는 지속 정보는 auto memory와 CLAUDE.md에 두라고 문서는 권한다.
브랜치를 바꿔도 같은 디렉터리의 세션 대화 기록은 유지되고, 파일 트리만 현재 브랜치를 본다. 병렬 작업은 git worktrees로 디렉터리를 나누는 패턴이 소개된다.
Resume / fork
claude --continue 또는 claude --resume으로 같은 session ID를 이어 간다. 세션 범위 권한은 복원되지 않아 다시 승인이 필요할 수 있다.
원래 세션을 건드리지 않고 갈래를 치려면:
claude --continue --fork-session같은 세션을 여러 터미널에서 동시에 열면 한 JSONL 파일에 메시지가 뒤섞여 나중에 볼 때 대화가 뒤죽박죽일 수 있다—문서는 병렬 작업에 --fork-session을 권한다.
Context window와 compaction
컨텍스트에는 대화, 파일 내용, 명령 출력, CLAUDE.md, auto memory, 로드된 skill, 시스템 지시 등이 들어간다. 한계에 가까워지면 자동 compaction이 돌아가고, 이른 지시문은 잘릴 수 있어 지속 규칙은 CLAUDE.md에 두라고 한다. /context로 무엇이 공간을 쓰는지 볼 수 있다.
MCP tool 정의는 기본적으로 지연 로드되어(tool search) 이름만 먼저 컨텍스트를 먹는다고 설명한다. /mcp로 서버별 비용을 확인할 수 있다.
Skill은 필요할 때 본문이 로드되고, subagent는 메인과 분리된 새 컨텍스트에서 돌아 요약만 돌려준다—긴 세션에서 컨텍스트 부풀림을 줄이는 수단으로 소개된다.
Checkpoints와 permissions
Checkpoint는 파일 편집 전 스냅샷으로, Esc 두 번 등으로 되돌릴 수 있다. git과 별개이며 원격에 영향을 주는 작업은 체크포인트 대상이 아니라서, 그런 명령 전에는 물어보는 흐름이 이어진다.
Shift+Tab으로 permission mode를 바꿀 수 있다—기본(편집·셸 전에 질문), 편집 자동 수락, Plan mode(읽기 전용으로 계획만), Auto mode(연구 프리뷰) 등. .claude/settings.json에 신뢰 명령을 넣어 반복 질문을 줄일 수 있다(Permissions).
효과적으로 쓰기(요약)
원문에는 /init, /agents, /doctor 같은 내장 명령과, 구체적인 프롬프트 예시, Plan mode로 조사와 구현을 나누는 패턴, “동료에게 위임한다”는 톤의 지시 등이 더 길게 실려 있다. 한 번에 다 옮기지 않고, 필요하면 아래 링크로 이어가면 된다.