배경 및 맥락
Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. IDE에 통합되는 Cursor나 Copilot과 달리, CLI에서 직접 실행되며 파일 시스템, 셸, Git 등에 직접 접근한다. 이 문서는 VineeTagarwaL이 작성한 Claude Code의 내부 작동 원리 해설로, 에이전트가 실제로 어떻게 작동하는지를 구조적으로 설명한다.
Claude Code를 쓰는 사람은 많지만, 내부에서 실제로 무슨 일이 일어나는지 이해하는 사람은 많지 않다. 이 내부 구조를 알아야 CLAUDE.md, 훅, 스킬, MCP 같은 고급 기능을 제대로 활용할 수 있다.
핵심 내용
에이전트 루프 (Agentic Loop)
Claude Code의 핵심은 연속적인 에이전트 루프다.
- 요청 수신: 사용자의 입력을 받는다
- 추론(Reasoning): 무엇을 해야 하는지 판단한다
- 도구 호출(Tool Call): 파일 검색, 코드 편집, 명령어 실행 등 도구를 호출한다
- 결과 관찰(Observe): 도구 실행 결과를 확인한다
- 반복: 작업이 완료되거나 사용자 입력이 필요할 때까지 반복
작업을 받으면 세 단계로 진행된다: 컨텍스트 수집 → 액션 실행 → 결과 검증. 파일을 검색해 코드를 이해하고, 편집을 통해 변경하고, 테스트를 실행해 검증한다.
컨텍스트 조립 (Context Assembly)
모델을 호출하기 전에 Claude Code는 시스템 프롬프트를 조립한다. 여기에 포함되는 것:
- 현재 날짜
- Git 상태: 브랜치, 최근 커밋, 워킹 트리 상태
- CLAUDE.md 메모리 파일: 프로젝트별 설정, 규칙, 컨텍스트
- 사용 가능한 도구 목록: 파일 읽기/쓰기, 셸 실행, 검색 등
이 컨텍스트 조립이 중요한 이유는, CLAUDE.md에 어떤 내용을 넣느냐에 따라 에이전트의 행동이 달라지기 때문이다.
도구 실행 및 권한 (Tool Execution & Permissions)
각 도구 호출 전에 Claude Code는 현재 권한 모드와 허용/거부 규칙을 평가한다. 모드에 따라:
- 자동 승인: 안전한 도구(파일 읽기, 검색 등)는 자동 실행
- 사용자 확인 요청: 위험할 수 있는 도구(파일 수정, 셸 명령어 등)는 확인 후 실행
- 완전 차단: 특정 도구는 아예 실행 불가
로컬 실행 (Local Execution)
에이전트 루프는 완전히 사용자의 터미널 프로세스에서 실행된다. 원격 실행 서버가 없다. 파일, 셸, 인증 정보는 도구가 명시적으로 전송하지 않는 한 로컬에 머물러 있다. 이것이 Devin 같은 클라우드 기반 에이전트와의 근본적 차이점이다.
멀티 에이전트 (Multi-Agent)
Claude는 Task 도구를 통해 서브 에이전트를 생성할 수 있다. 각 서브 에이전트는:
- 독립된 대화 컨텍스트로 자체 에이전트 루프를 실행
- 제한된 도구 세트를 선택적으로 적용 가능
- 로컬(in-process) 또는 원격 컴퓨팅에서 실행 가능
이 구조 덕분에 복잡한 작업을 여러 에이전트에 분배하고 병렬로 처리할 수 있다.
경쟁 구도 / 비교
Cursor / Windsurf: IDE 통합형. 에디터 안에서 실행되며, 파일 시스템과 셸에 대한 접근이 IDE 샌드박스로 제한된다. Claude Code는 터미널에서 직접 실행되며 시스템 전체에 접근 가능.
Devin / OpenClaw: 클라우드 기반 에이전트. 원격 서버에서 실행되며, 사용자의 로컬 환경과 분리된다. Claude Code는 로컬 실행이 기본이라 보안과 레이턴시 면에서 유리.
GitHub Copilot: 코드 자동완성 중심. 에이전트 루프 없이 인라인 제안에 집중. Claude Code는 에이전트로서 스스로 판단하고 실행한다.
의미
Claude Code의 내부 구조를 이해하는 것은 단순한 호기심을 넘어 실용적인 가치가 있다. 컨텍스트 조립 구조를 알면 CLAUDE.md에 무엇을 넣어야 하는지 전략적으로 판단할 수 있고, 권한 모델을 이해하면 훅을 더 효과적으로 설정할 수 있다. 멀티 에이전트 구조를 알면 복잡한 작업을 서브 에이전트로 분배하는 방법을 설계할 수 있다.
AI 코딩 도구가 블랙박스에서 투명한 구조로 바뀌고 있다는 점에서도 의미가 있다. Claude Code 소스 공개, Claw Code 같은 재구현 프로젝트, 그리고 이런 해설 문서들이 나오면서 개발자들이 에이전트를 더 잘 이해하고 활용할 수 있는 환경이 만들어지고 있다.