클로드 코드 작동 원리 완전 정리: 모델·도구·메모리·컨텍스트·가드레일과 에이전트 루프

핵심 메시지

• 클로드 코드는 반복 루프를 돌며 도구를 호출하는 LLM과, 그 루프·도구 구현·권한 시스템을 통제하는 '하네스' 소프트웨어의 결합이다.
• 모델은 도구를 직접 실행하지 못한다. '이 도구를 부르고 싶다'는 텍스트를 내놓을 뿐이고, 실제 실행은 하네스가 한다.
• 에이전트의 메모리는 사실 파일이다. 항상 읽히는 CLAUDE.md와 필요할 때 불러오는 메모리·스킬 파일이 프롬프트에 주입될 뿐이다.
• 가드레일은 모델이 아니라 소프트웨어가 강제한다. 사실상 '이 명령이면 사용자에게 물어라'는 조건문이라 모델이 뒤집을 수 없다.
• 발표자는 같은 구조를 파이썬 약 300줄로 재현해, 파일을 읽고 쓰고 코드를 생성하는 미니 클로드 코드를 실제로 돌려 보였다.

쉽게 이해하기

클로드 코드는 널리 쓰이지만 내부 작동을 아는 사람은 드물다. 강의는 이 도구를 두 부분으로 나눈다. 하나는 루프 안에서 돌며 도구를 호출하고 외부와 상호작용하는 LLM이고, 다른 하나는 그 모델을 감싼 '에이전틱 하네스'다. 하네스는 루프 진행, 도구 구현, 권한 확인을 맡는다. 모델이 다음에 할 일을 예측하면 실제 통제권은 하네스가 쥔다.

내부는 다섯 조각으로 정리된다. 모델, 도구, 메모리, 컨텍스트, 가드레일이다. 모델은 다음 토큰을 예측하는 거대한 텍스트 예측기일 뿐이어서 기본적으로 상태가 없고, 컨텍스트 윈도에 들어온 것만 볼 수 있다. 이전 대화를 기억하는 것처럼 보이는 이유는 지나간 대화를 매번 프롬프트에 다시 밀어 넣기 때문이다.

도구는 에이전트를 실제로 쓸모 있게 만드는 부분이다. 파일 읽기·쓰기·편집·검색·셸 명령 같은 입출력 도구가 기본으로 들어 있고, MCP 서버나 플러그인으로 도구를 더 붙일 수 있다. 여기서 결정적인 사실은 모델이 도구를 실행하지 않는다는 점이다. 모델은 '도구 이름은 read_file, 인자는 이것'이라는 형태의 구조화된 텍스트를 내놓고, 그 출력을 지켜보던 하네스가 도구를 실행해 결과를 다시 컨텍스트에 넣어 준다.

컨텍스트 윈도에는 시스템 프롬프트, 도구 정의, 스킬 정의, 메모리, 지금까지의 대화 기록, 도구 호출과 그 결과, 그리고 사용자의 요청이 한 덩어리로 쌓인다. 도구 정의와 대화 기록은 분량이 커지기 쉽고, 창이 80~90%까지 차면 모델 성능이 오히려 떨어진다. 어떤 정보를 이 창에 넣을지 고르는 일이 곧 컨텍스트 엔지니어링이다.

강의 후반부는 같은 구조를 파이썬으로 직접 만든다. 모델 호출 파일은 50여 줄로 요청 한 번을 보내는 게 전부고, 컨텍스트 파일은 기본 프롬프트에 CLAUDE.md 내용을 '프로젝트 메모리'로 덧붙인다. 도구 파일은 모델에게 보여 줄 정의와 실제로 실행될 파이썬 함수를 분리해 두고, 가드레일 파일은 읽기 전용 도구는 통과시키되 나머지는 승인을 묻고 한 턴에 25번까지만 호출하도록 제한한다.

주요 인사이트

• 모델이 '똑똑해 보이는' 착시는 대부분 컨텍스트 조립의 결과다. 기억도 목표도 상태도 없는 예측기에 방대한 텍스트를 넣어 주기 때문에 맥락을 아는 것처럼 보인다.
• 도구를 많이 붙이는 것이 늘 이득은 아니다. 수천 개의 도구 목록을 보여 주면 엉뚱한 도구를 고를 확률이 올라가므로, 목적이 뚜렷한 다섯여섯 개가 더 낫다는 지적이 나온다.
• 모델 성능 경쟁의 실체는 '컨텍스트에 담긴 정보를 보고 다음 토큰을 얼마나 정확히 고르는가'다. 도구 호출을 잘한다는 말도 결국 이 예측 정확도를 뜻한다.
• 에이전트가 느리게 느껴지는 이유가 설명된다. 사용자 요청 하나를 처리하려고 모델을 20~40번 다시 호출하며 도구 결과를 컨텍스트에 쌓는 구조이기 때문이다.
• 최소 구현은 15줄로도 가능하다. 즉 에이전트의 어려움은 개념이 아니라, 도구·권한·컨텍스트를 실전에서 다듬는 엔지니어링에 있다.

자주 묻는 질문

관련 AI 소식