Claude Code 아키텍처 분석: 에이전트 루프·도구·권한·메모리 구조 총정리

핵심 메시지

• Claude Code는 단순 챗봇이 아니라 파일을 읽고 셸 명령을 실행하며 코드를 수정하고 다른 에이전트까지 띄우는 완전한 에이전트 시스템이다.
• 핵심은 모델 호출과 도구 실행을 반복하는 ‘while-true’ 에이전트 루프로, 작업이 끝날 때까지 자율적으로 돌며 오류에서도 스스로 복구를 시도한다.
• 40개가 넘는 모든 도구가 동일한 인터페이스를 따르고 15단계 실행 파이프라인을 거치며, 컨텍스트 토큰을 아끼기 위해 도구는 지연 로딩(tool search)된다.
• 컨텍스트 압축은 무료에서 비싼 순으로 6단계가 단계적으로 작동하고, 권한은 5겹 방어로 위험한 명령을 차단하며 일부 검사는 우회 모드로도 무력화되지 않는다.
• 메모리는 YAML 머리말이 붙은 마크다운 파일로 저장되며, 사용자·피드백·프로젝트·참조 네 유형으로 나뉘고 작은 모델이 매 질의마다 관련 기억을 의미 기반으로 골라 불러온다.

쉽게 이해하기

영상은 Claude Code를 앤트로픽의 AI 코딩 어시스턴트이자 ‘완전한 에이전트 시스템’으로 소개한다. 파일 읽기, 셸 명령 실행, 코드 수정, 웹 검색은 물론 다른 AI 에이전트를 띄워 복잡한 작업을 자율적으로 처리한다. 코드베이스는 전부 타입스크립트로 작성돼 bun 런타임에서 돌고, 터미널 렌더링에는 React와 Ink의 커스텀 포크를 쓴다. 영상은 이 시스템을 떠받치는 일곱 가지 주요 영역을 차례로 짚는다.

가장 핵심은 에이전트 루프다. 사용자의 입력은 대화별 컨트롤러인 쿼리 엔진으로 가서 모델 선택·시스템 프롬프트 구성·슬래시 명령 처리를 거친 뒤 본 루프에 들어간다. 각 반복은 컨텍스트 준비, 스트리밍 API 호출, 응답 처리, 도구 병렬 실행, 계속할지 멈출지 판단을 반복한다. 도구를 썼다면 결과를 다시 넣어 루프를 잇고, 텍스트만 반환되면 잘림 등 복구 시나리오를 점검한 뒤 종료한다. 이 구조 덕분에 Claude Code는 단발 요청-응답이 아니라 작업이 끝날 때까지 자율적으로 돈다.

Claude Code에서는 파일 읽기·명령 실행·코드 검색 등 AI가 할 수 있는 모든 일이 ‘도구’로 모델링된다. 모든 도구가 같은 인터페이스(약 40개 속성)를 공유하기 때문에 입력 검증, 권한 검사, 훅 연동, 진행 표시, 일관된 UI를 공짜로 얻는다. 도구 호출은 등록부 조회부터 스키마 검증, 안전 분류, 훅·권한 병합, 실제 실행, 결과 처리에 이르는 15단계 파이프라인을 거친다. 수십~수백 개 도구의 스키마를 매번 보내면 토큰 낭비가 크므로, 대부분의 도구는 지연 로딩되고 모델은 tool search로 필요한 도구만 불러온다.

긴 대화를 컨텍스트 창에 맞추기 위한 압축은 ‘싼 것부터 비싼 것 순’으로 설계됐다. 마지막 압축 경계 이후만 보기, 메시지당 20만 자 제한과 큰 결과의 디스크 저장, 오래된 메시지 잘라내기, 시간 간격에 따른 마이크로 압축, 비파괴적인 컨텍스트 접기, 그리고 가장 비싼 단계로 별도 에이전트를 띄워 9개 섹션의 구조화된 요약을 만드는 전체 압축까지, 앞 단계가 충분한 공간을 확보하지 못할 때만 다음 단계가 발동한다.

안전을 책임지는 권한 시스템은 5겹 방어 구조다. 권한 모드, 허용·거부·확인 규칙, 도구 자체 검사, 훅 오버라이드, 그리고 별도의 AI 분류기가 차례로 작동하며, 한 층에 버그가 있어도 다른 층이 보호한다. 특정 보호 경로(예: git 디렉터리)나 내용 기반 검사는 우회 모드에서도 적용되며, 분류기를 쓸 수 없으면 ‘실패 시 차단(fail-closed)’으로 동작한다. 여기에 더해 대화를 가로질러 지식을 유지하는 파일 기반 메모리, 그리고 테스트 실행이나 리포지토리 복제 같은 장시간 작업을 대화를 막지 않고 처리하는 백그라운드 작업 시스템이 전체 구조를 완성한다.

주요 인사이트

• ‘모든 것을 도구로 통일’한 설계 덕분에 새 도구를 추가하면 권한·훅·UI·직렬화가 자동으로 따라온다. 일관성이 곧 유지보수성과 예측 가능성으로 이어진다.
• 출력 토큰 한도에 도달하는 것은 종료 조건이 아니라 ‘전이 사유’다. 시스템은 더 높은 토큰 한도로 재시도하거나 ‘이어서 작성’ 메시지를 보내며 끝까지 복구를 시도한다.
• 권한에서 훅이 ‘허용’해도 거부 규칙이 있으면 거부가 이긴다. 방어적 심층 설계에서는 어떤 단일 지점도 안전을 무너뜨리지 못하도록 했다.
• 메모리는 코드에서 유추 가능한 것(아키텍처, git 이력, 버그 수정 레시피)은 저장하지 않는다. 곧 낡아버리기 때문이며, 비자명하고 지속적인 지식만 남긴다.

자주 묻는 질문

관련 AI 소식