Claude Code API 호출 분석: 지연 로딩과 프롬프트 엔지니어링의 내부 구조

실용적 조언

대규모 도구 세트를 사용하는 LLM 앱 개발 시, 모든 스키마를 한꺼번에 보내지 말고 지연 로딩 방식을 도입하여 비용을 절감하라.
프로젝트별 가이드라인은 CLAUDE.md와 같은 평문 파일로 관리하여 프롬프트에 동적으로 주입하는 것이 유연성 측면에서 유리하다.

섹션별 상세

Claude Code는 프로젝트의 규칙과 메모리를 담은 CLAUDE.md 파일을 평문 텍스트로 처리하여 첫 번째 사용자 메시지에 태그와 함께 삽입한다. 별도의 특수 API 필드를 사용하는 대신 순수하게 프롬프트 엔지니어링 기법을 활용하여 모델에게 맥락을 전달하는 방식이다. 이를 통해 사용자는 텍스트 파일 수정만으로 모델의 행동 지침을 손쉽게 제어할 수 있다.

초기 구동 시 모든 도구의 상세 스키마를 전송하지 않고 도구의 이름만 먼저 보낸 뒤, 실제 사용 시점에 ToolSearch를 통해 스키마를 가져오는 지연 로딩 방식을 사용한다. 이러한 방식은 입력 토큰에 포함되는 불필요한 스키마 정보를 제거하여 초기 토큰 사용량을 약 85%까지 획기적으로 줄여준다. 모델이 필요한 정보만 적시에 로드하게 하여 추론 효율성을 극대화한 설계이다.

/code-review와 같은 명령어 기반의 Skills 기능은 내부적으로 프롬프트가 담긴 도구 결과값을 로드하여 실행되는 구조를 가진다. 사용자가 스킬을 호출하면 Claude는 해당 스킬 도구를 실행하고 반환된 마크다운 형식의 지침을 그대로 따라 작업을 수행한다. 이는 복잡한 기능을 하드코딩하는 대신 유연한 프롬프트 주입 방식으로 구현했음을 의미한다.

대화 내용이 길어지면 전체 대화를 상세 요약 블록으로 압축하여 컨텍스트 윈도우를 관리하지만, CLAUDE.md와 지연 로딩된 도구 정보는 매 호출마다 재주입된다. 시스템은 대화의 흐름을 요약하여 용량을 확보하는 동시에 프로젝트의 핵심 규칙과 도구 사용 능력은 보존하는 이중 전략을 취한다. 결과적으로 제한된 컨텍스트 내에서 장기적인 프로젝트 수행 능력을 유지하도록 돕는다.

용어 해설

지연 로딩(Lazy Loading): — 데이터가 실제로 필요한 시점에만 로드하여 초기 실행 속도를 높이고 자원 낭비를 줄이는 최적화 기법이다. Claude Code에서는 모든 도구 스키마를 한꺼번에 보내지 않고 모델이 도구를 호출할 때만 상세 정보를 가져와 초기 토큰 사용량을 85% 절감한다. 이는 API 비용 효율성과 컨텍스트 윈도우 관리에 매우 중요하다.
컨텍스트 윈도우 관리(Context Window Management): — 모델이 한 번에 처리할 수 있는 토큰 제한 내에서 정보를 효율적으로 배치, 요약, 유지하는 기술이다. 대화가 길어지면 이전 내용을 요약 블록으로 압축하면서도 프로젝트 규칙 같은 핵심 정보는 매번 재주입하여 모델의 일관성을 유지한다. 복잡한 코딩 작업에서 모델의 추론 성능을 장기간 유지하는 핵심 메커니즘이다.
토큰 최적화(Token Optimization): — API 호출 시 발생하는 비용과 지연 시간을 줄이기 위해 입력 데이터의 크기를 최소화하는 과정이다. 지연 로딩과 대화 압축 기술을 결합하여 모델이 처리해야 할 불필요한 텍스트를 제거함으로써 더 빠르고 경제적인 추론 환경을 구축한다. 대규모 프로젝트를 수행하는 AI 에이전트의 실용성을 결정짓는 요소이다.
스키마(Schema): — 데이터나 도구의 구조, 입력 파라미터, 반환 형식을 정의한 명세서이다. LLM이 외부 도구를 정확하게 호출하기 위해서는 해당 도구의 스키마를 반드시 인지해야 한다. Claude Code는 이 스키마를 동적으로 로드하여 모델이 초기 단계에서 수많은 도구 정보를 한꺼번에 처리해야 하는 부담을 낮춘다.

언급된 도구

Claude Code추천

Anthropic의 CLI 기반 코딩 에이전트 도구

ToolSearch중립

필요한 시점에 도구 스키마를 동적으로 로드하는 내부 도구