클로드 코드 작동 원리 분석 - ReAct 루프와 서브에이전트, 할 일 목록 구조

핵심 메시지

• 클로드 코드의 뼈대는 특별한 신기술이 아니라, 언어모델이 계획을 세우고 도구를 실행한 뒤 그 결과를 다시 맥락에 넣는 ReAct(추론+행동) 반복 구조다.
• 복잡한 요청에서 컨텍스트가 넘치는 문제를 막기 위해 서브에이전트에게 코드베이스 탐색을 맡기고, 메인 에이전트에는 필요한 정보만 올려 보낸다.
• 시스템 프롬프트의 큰 축은 안전이다. 파일 삭제나 임의의 커밋 같은 행위를 막고 판단 권한을 사용자에게 남긴다.
• 코드를 실행하기 전에 린트·타입 검사로 스스로 검증해, 오류 메시지가 맥락을 잠식하고 대화가 늘어나는 것을 줄인다.
• 복잡한 작업은 할 일 목록을 실제 파일로 적어두고 하나씩 지워가며 진행하는데, 강연자는 이 구조를 여러 에이전트 서비스의 공통 뼈대로 봤다.

쉽게 이해하기

터미널에서 대화하듯 코딩을 시키는 CLI 기반 코드 에이전트가 빠르게 늘고 있다. 제미나이 CLI, 코덱스, 오픈코드처럼 원하는 모델 API를 꽂아 쓰는 오픈소스 도구까지 선택지가 많아졌지만, 강연자는 여전히 클로드 코드가 앞서 있다고 평가한다. 그래서 그 안에서 실제로 무슨 일이 벌어지는지를 들여다보는 것이 이번 강연의 목적이다.

구조 자체는 의외로 단순하다. 사용자가 프롬프트를 보내면 모델 API에 요청이 가고, 필요하면 도구를 쓴다. 터미널에서 명령을 실행하거나 로컬 파일을 읽고 쓰고 지우는 도구들이 있고, 그 실행 결과가 다시 모델의 맥락으로 들어간다. 맥락이 충분하면 바로 답하고, 부족하면 다시 도구를 찾는다. 강연자는 이 반복을 에이전트의 기본기인 ReAct, 즉 추론과 행동의 결합으로 설명한다.

그럼에도 여러 에이전트를 쓰는 이유는 맥락 관리 때문이다. 예를 들어 코드베이스 전체를 읽고 리팩터링하라고 시키면, 일부만 읽어도 컨텍스트 창의 절반 이상이 채워질 수 있다. 그러면 정작 시켜야 할 작업에 쓸 맥락이 남지 않는다. 그래서 서브에이전트가 탐색을 대신 수행하고 '문제가 어디에 있는지'만 추려 메인 에이전트에 올린다. 메인 에이전트는 그 정보를 받아 실제 수정을 담당한다.

안전 설계도 성능만큼 비중이 크다. 파일 시스템에 접근하는 도구를 쓰는 이상 파일이 지워지거나 코드베이스가 통째로 사라질 여지가 있기 때문에, 시스템 프롬프트는 임의로 추측하거나 고치지 말고 권한을 사용자에게 넘기라고 반복해 강조한다. 강연자는 에이전트가 얼마나 스스로 밀고 나가는지를 뜻하는 '적극성'의 수위를 어디에 둘지가, 어떤 에이전트 서비스를 만들든 피할 수 없는 딜레마라고 말한다.

실무에 옮길 지점도 분명하다. 코드 에이전트는 긴 설명이 필요 없으므로 '불필요한 설명 없이 결과물과 짧은 요약만' 같은 지시가 유효하고, 코드베이스의 명명 규칙이 일관되지 않으면 에이전트가 엉뚱한 파일을 붙잡는다. 강연자 본인도 파일명에 밑줄을 넣고 안 넣고가 섞여 원하는 결과가 나오지 않았던 경험을 예로 들었다.

주요 인사이트

• 코드 에이전트의 성능 차이는 모델 자체보다 맥락을 어떻게 아껴 쓰느냐에서 갈린다. 서브에이전트 분리는 역할 분담이 아니라 컨텍스트 절약 장치에 가깝다.
• '실행 전 검증'은 품질 장치인 동시에 비용 장치다. 오류를 뒤늦게 만나면 오류 메시지가 맥락에 쌓이고 해결에 대화 턴이 더 필요해진다.
• 할 일 목록을 모델의 머릿속이 아니라 파일로 빼두는 방식은, 긴 작업에서 에이전트가 진행 상황을 잃지 않게 하는 값싼 해법이다.
• 모델의 학습 시점이 과거에 머물러 있다는 점을 시스템 프롬프트가 먼저 인정하고 검색을 유도하도록 설계한 것도 실전형 처리다.
• 라이브러리 하나로 이런 구조를 흉내 낼 수는 있지만, 내부 원리를 모르면 잘 돌아가도 이유를 모르고 실패해도 원인을 못 찾는다는 지적이 남는다.

자주 묻는 질문

관련 AI 소식