Claude Code CLI는 Anthropic에서 개발한 터미널 기반 AI 코딩 비서로, 자연어 명령을 통해 코드 편집, 버그 수정, 테스트 실행, Git 작업 등을 도와주는 에이전트형 코딩 도구이다. Claude Code CLI의 내부 구조와 동작 방식은 오픈소스로 공개되진 않았지만 NPM 패키지로 배포되어, 소스맵 등을 활용한 리버스 엔지니어링을 통해 상당 부분이 밝혀졌다. 또한 직접 리버스 엔지니어링을 시도해 본 결과, 일부 구현 방식을 확인할 수 있었다. 본 보고서에서는 Claude Code CLI의 아키텍처와 핵심 구성, 대용량 코드베이스 처리 전략, 파일 선택 로직과 컨텍스트 구성의 한계, AI 프롬프트 생성 및 API 통신 흐름, 실제 사용 시나리오와 예시, 그리고 현재 구현의 한계점 및 향후 개선 방향을 차례로 분석한다.

아키텍처 및 핵심 구조

모놀리식 번들 구조: Claude Code CLI의 코드는 ESBuild로 번들링되어 단일 실행 파일로 구성되어 있으며, 내부적으로 몇 가지 주요 모듈 레이어로 나뉜다. 대표적으로 toolDefs, taskPlanner, gitDriver, llmClient 등의 컴포넌트가 핵심적인 역할을 수행하며, 여기에 터미널 UI와 유틸리티 모듈 등을 포함해 5개 내외의 주요 레이어로 이루어져 있다. 전체 구조는 크게 UI, 코어 로직, 서비스 계층, 툴 집합, 데이터/상태 관리, 유틸리티 등으로 구분할 수 있다.

  • UI 레이어: 터미널 기반 REPL 인터페이스를 제공하며, 사용자 입력과 AI 응답을 출력하는 역할이다. React 기반의 Ink 프레임워크를 사용하여 CLI 화면을 구성하고, 대화 메시지 표시나 권한 승인 다이얼로그, 설정 인터페이스 등을 렌더링한다. 예를 들어 대화형 프롬프트 창, 사용자 확인 요청 팝업 등이 UI 레이어에서 구현된다.
  • **코어 로직: **애플리케이션의 핵심 흐름을 오케스트레이션한다. 사용자 입력을 파싱하여 일반 자연어 질의인지 슬래시 명령인지 구분하고, 대화 상태를 관리하며, LLM(Claude API)과 상호작용을 조율한다. 또한 LLM이 툴 사용을 요청하면 적절한 툴을 호출하고, 결과를 받아 다시 모델에게 전달하는 등의 에이전트 제어 흐름을 담당한다.
  • **서비스 계층: **외부 서비스 연동과 핵심 기능을 모듈화한 부분이다. Anthropic Claude API 서비스, OAuth 인증 서비스, Statsig (기능 플래그/실험), Sentry (에러 모니터링), MCP 클라이언트 등의 서비스가 별도 모듈로 구현되어 있다. 이를 통해 API 키 인증, 요청 재시도와 백오프, 사용량 추적, 에러 로깅 등의 기능을 캡슐화한다.
  • 툴 모듈 집합: LLM이 호출할 수 있는 일련의 도구 함수들이다. 파일 읽기/쓰기/편집과 같은 파일 시스템 조작 툴(View, Replace, Edit 등), 내용 검색을 위한 grep 툴(GrepTool 또는 RipGrep), 경로 패턴으로 파일 목록을 찾는 glob 툴(GlobTool), 셸 명령 실행을 위한 Bash 툴, 주피터 노트북 셀 조작 툴, 웹 컨텐츠 fetch 툴 등 다양한 도구가 정의되어 있다. 이러한 도구 레지스트리는 JSON-RPC 스타일로 래핑되어 모델이 특정 형식으로 도구 호출을 요청하면 CLI가 해당 함수를 실행하고 결과를 반환하는 방식으로 동작한다. 또한 BatchTool과 AgentTool 등의 메타-툴도 있어, 여러 툴 호출을 병렬/순차 실행하거나, 보조 에이전트를 런칭하는 기능도 제공된다.
  • 데이터 및 세션 관리: 설정 파일 및 대화 세션 정보를 관리하는 구성요소이다. 전역/프로젝트별 설정값(예: API 키, 툴 권한, 사용자 프롬프트 이력), 명령 히스토리, 대화 컨텍스트, 토큰 사용량 추적 등의 상태 관리 로직이 포함된다. 세션 관리 측면에서, Claude Code CLI는 이전 대화 맥락을 유지하여 멀티턴 대화를 지원하는데, CLI 내부적으로 프롬프트에 특정 8바이트 헤더를 붙여서 새로운 대화 세션의 시작 여부를 판별하는 기술이 사용된다. 이를 통해 사용자가 연속 질의를 하는 경우 이전 메시지들을 컨텍스트로 전달할지 여부를 결정한다.
  • 유틸리티 및 기타: 파일시스템 조작, Git 통신, 문자열 파싱, 명령어 처리 등의 공통 함수들이 여기 속한다. 예를 들어 gitDriver 모듈은 Git과 상호작용 (커밋, 브랜치 변경 등) 기능을 담당하며, fileOps 유틸은 안전한 파일 읽기/쓰기 구현과 경로 정규화, 파일 크기 제한 검사를 수행한다. executionEnv 모듈은 보안 샌드박스 내에서 셸 명령을 실행하고, 위험한 명령을 필터링하며, 백그라운드 프로세스를 관리하는 기능을 제공한다.

명령 파싱과 도구 호출 흐름: 사용자가 터미널에서 입력을 하면 CLI는 우선 명령어 파싱기를 통해 입력을 해석한다. 슬래시(/)로 시작하는 예약어 명령 (예: /init, /help, /debug 등)이 감지되면 해당 명령에 등록된 핸들러를 실행하고, 그렇지 않은 일반 자연어 질의는 대화 프롬프트로 간주한다. 명령어의 구현은 커맨드 레지스트리에 사전 등록되어 있는데, CLI 엔트리포인트(cli.ts)에서 사용자의 입력을 토큰화하여 해당 커맨드를 찾아 실행하는 구조다.

예를 들어 /explain 명령은 파일 경로 인자를 받아 해당 파일 내용을 읽은 후 “이 코드를 설명해줘”라는 프롬프트를 생성하여 LLM에 보낸다. 간략한 실제 코드 구현을 보면 다음과 같다:

// `explain` 명령의 간략한 구현 (commands/register.ts)
handler: async (args) => {
    const { file } = args;
    const fileContent = await readTextFile(file);  // 파일 내용 읽기
    const prompt = `Please explain this code:\n\n\`\`\`\n${fileContent}\n\`\`\``;
    const result = await aiClient.complete(prompt);  // LLM 호출하여 결과 얻기
    // ... 응답 출력 ...
}

이처럼 기본적으로 단일 파일에 대한 동작은 파일을 읽어 프롬프트에 삽입한 후 LLM의 응답을 받아 출력하는 구조다. CLI 내부의 LLM 클라이언트는 Anthropic API와 통신하는 래퍼로 구현되어 있으며, OAuth를 통한 사용자 인증을 거쳐 API 키를 확보하고 인퍼런스 요청을 보낼 수 있도록 초기화된다. llmClient.complete() 메서드는 Anthropics의 완성형 모델 API (v1/complete 또는 채팅 API)를 호출하여 결과를 받아오며, 최대 토큰 수, 온도 등의 파라미터를 설정하고, 스트리밍 응답을 처리하는 기능도 포함한다.

LLM 호출 스케줄러: Claude Code의 두드러진 특징은 에이전트 루프를 통해 LLM이 필요에 따라 도구를 사용하면서 다단계로 작업을 수행한다는 점이다. 단순 질의가 아닐 경우, 내부적으로 3-스텝 루프를 진행하는데, 이를 요약하면 ① 코드베이스 개괄 요약 → ② 작업 계획(Plan) 수립 및 툴 시퀀스 실행 → ③ 결과로부터 diff 패치 적용의 흐름이다. 구체적으로, 모델이 처음 사용자 요청을 받으면 우선 프로젝트의 전체 맥락이나 관련 파일 정보를 요약하도록 시스템 프롬프트에 지시하며, 이후 모델이 “Todo 리스트” 형태의 계획을 세우면(TodoWrite 툴 이용), CLI가 이를 받아 순차적인 Task 실행 단계로 돌입한다. 각 Task에서는 모델이 View, Glob, Grep, Bash 등 다양한 툴을 호출하며 필요한 정보를 수집하거나 코드를 변경하고, 각 단계가 끝날 때마다 Todo의 상태를 완료로 업데이트(TodoWrite 호출)하여 다음 단계로 진행한다. 이러한 플랜-태스크 수행 메커니즘을 통해 복잡한 요청도 단계적으로 처리할 수 있게 설계되어 있다. 아래는 이러한 흐름을 간략히 표현한 의사코드이다:

class PlanExecutor {
  async execute(userRequest: string) {
    // 1. 복잡한 사용자 요청 분석 및 Plan 생성
    const plan = this.generatePlan(userRequest);   // Todo 목록 작성
    await this.savePlan(plan);                     // Plan 저장

    // 2. Plan의 각 할 일을 순차 실행
    for (const item of plan) {
      await this.updateStatus(item.id, 'in_progress');  // 상태: 진행중

      // 3. 각 Plan 아이템에 대한 세부 Task 목록 생성
      const tasks = this.generateTasksForPlan(item);
      // 4. 생성된 Task들을 순차 실행
      for (const task of tasks) {
        await this.executeTask(task);                   // 툴 호출 등 작업 수행
      }

      await this.updateStatus(item.id, 'completed');    // 상태: 완료
    }
  }
}

위 과정에서 LLM은 Plan 생성을 위해 TodoWrite라는 가상의 툴 호출로 다중 작업 목록을 내놓고(예: “1. 프로젝트 구조 파악, 2. 기능 A 구현, 3. 테스트 작성…”), CLI는 이를 화면에 Todo 리스트로 보여주거나 내부 상태로 저장한다. 이후 모델이 각 Todo를 처리하기 위해 연이어 GlobTool이나 View 등을 호출하면, CLI는 해당 동작을 수행한 뒤 결과(예: 파일 내용, 검색 매치 결과 등)를 다시 모델에게 전달한다. 최종적으로 모든 Todo가 완료되면 모델은 전체 결과를 요약하거나 최종 코드 변경 내역(diff)을 생성하여 응답하며, CLI는 그 변경사항을 실제 파일에 적용하고 대화를 마무리한다. 이렇듯 Claude Code는 대화형 에이전트로서 한 번의 명령에 대해서도 내부적으로는 여러 차례 LLM 호출과 툴 실행이 오가는 멀티턴 프로세스를 관리한다. 이러한 복잡한 흐름은 Core Logic과 LLM 클라이언트에 내장된 LLM 호출 스케줄러에 의해 조율되며, 작업 중간중간 API 호출 비용 추적, 대화 메시지 기록, 사용자 승인 요구 등도 함께 처리된다.

보안 및 권한 제어: Claude Code CLI는 로컬 시스템에 영향을 주는 도구들을 다루므로, 보안상 여러 장치를 갖추고 있다. 예를 들어 파일 경로를 열 때는 경로 문자열을 정규화(RegEx)하여 상위 디렉토리 접근(.. 경로 등)을 방지하고, 파일 읽기/쓰기 시 파일 크기 제한(기본 10MB)을 넘어가는 경우 오류를 반환하여 메모리 과사용을 막는다. 셸 명령 실행(BashTool)의 경우 미리 정의된 위험한 명령어 패턴 (예: rm -rf /)을 차단하고, 실행 시간 제한과 백그라운드 프로세스 정리 로직을 구현하여 시스템 피해를 예방한다. 또한 모델이 파일을 수정하거나 명령을 실행하려 할 때는 사용자 승인 절차를 거치도록 되어 있다. CLI 초기 실행 시 출력되는 권한 다이얼로그나, 설정 파일(settings.json)의 허용 목록을 통해 특정 툴/경로에 대한 사전 승인 또는 차단을 설정할 수 있다. 이러한 다층적인 보안 장치 덕분에, Claude Code는 모델의 잘못된 행동으로 인한 치명적 변경을 방지하고 사용자가 통제권을 유지하도록 설계되어 있다.

대용량 코드베이스 처리 전략

Claude Code는 수십만 줄 이상의 대규모 프로젝트에서도 동작하도록 만들어졌지만, 기본적으로 LLM 컨텍스트 크기 제약이 있기 때문에 여러 최적화 전략을 활용하고 있다. 핵심 전략은 파일을 무작정 모두 모델에게 보내지 않고, 필요한 정보만 추려서 효율적으로 제공하는 데 초점이 맞춰져 있다. Claude Code가 적용하는 대용량 코드베이스 처리 기법은 다음과 같이 정리된다:

  • 파일 필터링 및 제한: 우선 프로젝트의 모든 파일을 스캔한 후, 사전에 정해진 기준에 따라 불필요한 파일을 제외한다. 예를 들어 기본 설정으로 node_modules, .git, dist, build, .min.js 등 일반적으로 소스 이해에 불필요하거나 방대하여 컨텍스트로 보내기 적합하지 않은 경로/파일들이 자동 제외된다. 그리고 나머지 파일도 개수와 크기에 제한을 두는데, 최대 1000개 파일까지만 고려하고 각 파일은 1MB 이하인 경우에만 읽어서 사용한다. 이러한 값들은 설정으로 존재하며 필요시 조정 가능하나, 기본값으로 대용량 프로젝트에서 과도한 파일을 취급하지 않도록 안전장치를 둔 것이다. 만약 검색된 파일이 1000개를 초과하면 경고 로그를 남기고 단순히 처음 1000개만 사용하도록 구현되어 있다. 실제 코드 조각을 보면 다음과 같다: 
    // 파일 목록 제한 (analyzer.ts)
if (allFiles.length > maxFiles) {
  logger.warn(`Too many files (${allFiles.length}), limiting to ${maxFiles}`);
  allFiles = allFiles.slice(0, maxFiles);  // 처음 1000개로 잘라버림
}
  • 마찬가지로 파일별 크기도 체크해서, 정해진 최대 크기를 넘는 파일은 아예 읽지 않고 건너뛰거나 에러로 처리한다. 예를 들어 1MB를 넘는 거대한 소스 파일은 무시되며, 10MB를 초과하는 읽기 시도는 에러를 반환한다. 이러한 크기/수량 제한 기반 필터링은 가장 1차적인 방어선으로, LLM 컨텍스트가 너무 커지지 않게 하고 성능을 확보하기 위한 것이다.
  • 우선순위 기반 파일 선택: 단순한 정적 필터링 외에, 코드 의미에 기반한 파일 선정도 지향한다. Claude Code의 설계 개요에 따르면, 모든 파일을 동일하게 보는 것이 아니라 언어별로 분류하고 핵심 소스 코드 위주로 우선순위를 두는 로직이 포함되어 있다. 예를 들어 프로젝트 내 여러 종류의 파일 중 JavaScript/TypeScript, Python, Java 등의 코드 파일만 중점적으로 분석하고, JSON이나 Markdown, 이미지 등의 파일은 필요시에만 본다. 이를 위해 파일 확장자별로 해당 언어를 자동 인식하는 매핑 (EXTENSION_TO_LANGUAGE) 테이블이 있어 .ts → TypeScript, .py → Python 식으로 분류한다. 또한 Dependency 분석기를 통해 import/require 관계를 파악하여 특정 파일과 연관된 모듈들을 찾을 수도 있다. 다만 현행 구현에서는 이러한 의존성 정보가 아직 실제 파일 선택에 적극 활용되지는 못하고 있다. 이상적으로는 “특정 기능에 관련된 파일들만 선별”하거나 “변경 영향도에 따라 컨텍스트 파일 결정” 같은 지능형 필터링을 목표로 하지만, 현재 버전은 주로 정적 기준에 의존하는 상태다.
  • 점진적/배치 분석: 대용량 코드베이스에서는 한꺼번에 모든 파일을 처리하기 어려우므로 단계적으로 분석하는 접근을 취한다. 예컨대 Claude Code는 백그라운드에서 주기적으로(예: 5분 간격) 프로젝트를 재분석하여 요약 정보를 업데이트하거나, 너무 많은 파일이 있을 경우 여러 배치로 나누어 순차 처리하는 전략을 사용한다. 50개 파일씩 묶어 처리하면서 진행 상황을 로그로 남기거나, 사용자와 상호작용 중일 때는 대화 흐름을 방해하지 않도록 비동기적으로 백그라운드 작업으로 수행하는 등 UX를 고려한 설계를 갖추고 있다. 이러한 점진적 분석은 사용자가 대화를 이어가는 동안에도 백그라운드에서 프로젝트 인덱싱이 이뤄져서, 이후 질의에 더 빠르게 응답하거나 더 나은 컨텍스트를 제공하기 위함이다. 다만 현 시점의 실제 구현에서는 이러한 주기적 백그라운드 분석이 활발히 이루어지고 있다는 뚜렷한 증거는 부족하며, 추후 기능 확장의 여지로 남아있는 부분으로 보인다.

  • 컨텍스트 윈도우 관리: LLM 입력 프롬프트의 토큰 한계를 극복하기 위해 Claude Code는 청크 단위로 컨텍스트를 관리하고 요약 정보 활용을 병행한다. 즉, 한 번에 모든 코드를 보내는 것이 아니라 현재 요청과 관련된 파일들만 추려서 LLM에게 전달하는 방식이다. 예를 들어 “이 특정 함수에 버그가 있으니 고쳐줘”라는 요청이라면, 기본적으로 그 함수가 있는 파일만 모델에 보내고, 추가로 직접 지정한 컨텍스트 파일만 제공하는 식이다. 프로젝트 전반의 구조 요약 정보도 미리 구성해 활용한다. analyzer 모듈은 프로젝트를 스캔하여 전체 파일 수, 언어별 파일 분포, 총 코드 줄 수, 의존 라이브러리 목록 등을 담은 메타데이터 구조를 생성할 수 있다. 예를 들어 ProjectStructure 인터페이스에는 아래와 같은 요약 정보가 담길 수 있다: plain text interface ProjectStructure { totalFiles: number; filesByLanguage: Record<string, number>; totalLinesOfCode: number; dependencies: DependencyInfo[]; }

  • 이 요약을 통해 모델에게 “이 프로젝트는 총 파일 N개, 주요 언어는 X, 사용 라이브러리는 Y개 정도다”라는 맥락을 전달할 수 있다. 이러한 정보는 프롬프트의 시스템 메시지나 사용자 메시지 앞부분에 첨가되어 모델이 전체 그림을 이해하도록 도와준다. 또한 필요한 경우 디렉터리 구조나 파일 목록을 요약해서 보여주기도 하는데, 실제 Claude Code의 시스템 프롬프트에는 프로젝트 디렉토리 트리(폴더/파일 구조)를 나열해 맥락을 주는 부분이 확인되며, 이는 모델이 전체적인 프로젝트 구성을 파악하는 데 도움을 준다. 단, 전체 트리를 과다하게 넣으면 토큰을 많이 잡아먹기 때문에, 일정 수준 이상 깊이에서는 요약하거나 생략하는 등 알고리즘적인 처리가 들어간다.
  • 메모리 최적화: 대용량 파일 처리 시에는 스트림 기반 처리를 사용하여 메모리 사용량을 줄인다. 예컨대 매우 큰 파일을 읽을 때 한꺼번에 메모리에 올리지 않고 스트리밍으로 청크 단위로 읽어서 필요한 부분만 모델에 전달하거나, 일정 크기씩 잘라 순차적으로 처리한다. (현재 구현에서는 앞서 언급한 대로 일정 크기를 넘는 파일은 아예 제외하기 때문에, 스트림 처리의 실제 활용은 제한적일 수 있다.) 또한 동시성 제어를 통해 한 번에 처리하는 파일/요청의 수를 제한한다. 내부 설정으로 최대 5개까지 작업 동시 진행을 허용하고 그 이상은 대기시키는데, 이를 통해 여러 파일을 병렬 처리할 때도 메모리 및 API 호출 부하를 관리한다. 마지막으로 결과 캐싱도 고려되어 있어, 동일한 파일에 대한 반복 설명이나 이전에 계산한 코드베이스 요약 정보를 캐시해두고 재사용함으로써 불필요한 중복 작업을 피하도록 설계되어 있다. 이러한 최적화 기법들은 대용량 프로젝트에서 응답 지연을 줄이고 비용을 절감하기 위한 것이다.

요약하면, Claude Code는 큰 코드베이스를 다룰 때 “필요한 것만, 가능한 효율적으로” 접근하려고 시도한다. 다만 이는 이상적인 목표이고, 실제 구현은 아직 완전하지 않은 부분이 있다. 다음 절에서 이러한 파일 선택 및 컨텍스트 구성의 한계를 구체적으로 살펴본다.

파일 선택 및 컨텍스트 구성의 한계

앞서 언급한 “지능적 파일 선택” 메커니즘은 Claude Code의 목표 지향점이지만, 현재 버전에서는 완전한 형태로 구현되지 못한 상태다. 리버스 엔지니어링을 통해 확인된 현행 동작은 오히려 단순한 규칙 기반 처리에 가깝다. 중요한 한계와 미구현 사항은 다음과 같이 정리된다:

  • 자동 맥락 선택 미흡: 공식 문서에서는 “프로젝트 파일을 수동으로 컨텍스트에 추가할 필요 없이 Claude가 알아서 코드를 탐색한다”고 소개하지만, 실제로는 대부분 사용자가 명시적으로 지정한 파일만을 모델에 제공하는 경우가 많다. 예를 들어 /explain이나 /fix 같은 명령은 기본적으로 인자로 단일 파일 경로를 받도록 되어 있으며, 해당 파일 하나만 읽어 모델에게 전달한다. 사용자가 추가로 맥락을 주고 싶으면 -context 옵션을 통해 파일 경로들을 직접 열거해야 한다. 즉, 자동으로 관련 파일을 찾아주는 지능형 기능은 구현되어 있지 않다.
  • 의존성 기반 파일 포함 없음: 코드 상에는 import나 require 구문을 파싱하여 의존 파일을 찾는 로직이 일부 존재하나, 그 결과를 컨텍스트 구성에 활용하지는 않는다. 예를 들어 어떤 모듈 A를 수정하는 경우 A가 의존하는 모듈 B나, 반대로 A를 사용하는 상위 모듈 C를 함께 모델에게 보여주면 더 정확한 변경이 가능할 것이다. 하지만 현재 Claude Code는 그런 의존성 추적에 따른 파일 선정은 하지 않고, 오직 요청된 파일(A) 자체만 다룬다. 이는 모델이 변경 시 부작용을 예측하거나 연쇄적인 수정에 한계가 있음을 의미한다.
  • 관련성 점수 계산 등 부재: 현대 코드 비서들이 도입하는 TF-IDF 기반 유사도 검색이나 embedding을 통한 연관도 계산 등의 기능은 Claude Code에 아직 없다. 따라서 “이 함수와 가장 밀접한 5개 파일 자동 포함”과 같은 스마트한 맥락 선정은 이루어지지 않고, 여전히 사용자가 필요하면 해당 파일들을 직접 찾아 추가해줘야 한다. 결국 현행 버전은 동적이고 맥락적인 선택이 전혀 없고, 설령 프로젝트 전반을 스캔하더라도 그 정보가 모델 질의 시 파일 자동선택에 활용되지 못하고 있다.
  • 실제 동작 예시 - 버그 수정: 예를 들어 사용자가 “이 에러를 고쳐줘”라고 요청하는 시나리오를 보자. 현재 CLI에서 /fix 명령은 -issue 옵션으로 에러 메세지를 받고 대상 파일 경로를 인자로 받는다. claude fix src/api/users.ts --issue "Type error in getUserData"라고 하면, 구현상 users.ts 파일 하나만 모델에 전달하여 오류를 해결하도록 시도한다. 이 파일에서 다른 타입 정의를 참조하고 있는데도, 관련 타입 선언 파일이나 API 스키마 정의 파일 등은 자동으로 함께 제공되지 않는다. 이상적으로는 타입 에러의 경우 해당 타입이 정의된 파일(.d.ts나 인터페이스 선언부)을 추가로 보여주고, API 관련 에러라면 API 모델/스키마 파일도 참고하도록 해야 한다. 그러나 현재 Claude Code에는 그런 맥락 확장이 전혀 없어, 모델이 필요 정보를 알지 못한 채 추론을 해야 하므로 답변의 정확도가 떨어질 수 있다.
  • 실제 동작 예시 - 신규 기능 생성: 또 다른 시나리오로 “프로젝트에 새로운 기능을 추가해줘”를 생각해보자. 예컨대 사용자가 /generate "Add user authentication" --language TypeScript 명령으로 새 기능 구현을 요청하면, 현재 Claude Code는 아무 컨텍스트도 주지 않은 상태에서 모델에게 타입스크립트로 인증 기능 코드를 생성해 달라는 프롬프트만 던진다. 그 결과 모델이 만들어내는 코드는 해당 프로젝트의 구조나 코딩 컨벤션과 동떨어진, 일종의 보편적인 boilerplate 코드가 될 가능성이 높다. 실제로도 현재 방식은 기존 코드베이스 스타일이나 아키텍처를 전혀 고려하지 않고 기능을 생성하기 때문에, 생성 결과물을 수동으로 프로젝트에 맞게 수정해야 하는 경우가 발생한다. 이상적인 구현에서는 “유사한 기능을 이미 프로젝트에 구현한 부분 참고”, “프로젝트의 아키텍처 패턴에 맞춤”, “사용 중인 프레임워크/라이브러리 API 활용” 등이 이루어져야 할 것이다. 그러나 현 버전은 그러한 맥락을 전혀 모델에게 주지 않으므로, 사실상 코드 조각 생성기 수준에 머물게 된다.
  • 대용량 프로젝트에서의 수동 개입 필요: 앞서 대용량 코드베이스 최적화 전략에서 여러 자동화 기법을 설명했지만, 현실적으로는 여전히 사용자의 수동 작업에 의존하는 부분이 많다. Claude Code는 프로젝트를 초기 분석하여 대략적인 구조 정보를 얻지만, 정작 모델에게 답을 줄 때는 그 구조 정보를 활용해 관련 파일을 자동으로 골라주지 않는다. 결국 사용자가 문제를 해결하려면, 어떤 파일들이 관련 있는지 스스로 파악해서 -context 옵션 등으로 일일이 지정하거나, 한 번에 하나의 파일만 집중적으로 다루는 방식으로 우회해야 한다. 공식 문구와 달리 “전체 프로젝트를 이해하고 필요 파일을 알아서 탐색”하는 지능형 동작은 현재는 구현 미비 상태인 것이다.

분석을 종합하면, Claude Code CLI의 파일 선택 로직은 아직 초기 수준이며, 진정한 의미의 “자동 컨텍스트 관리”는 향후 개선 과제로 남아 있다. 프로젝트 규모가 클수록 이러한 한계는 더욱 두드러지며, 개발자는 Claude Code를 효율적으로 쓰기 위해 여전히 수동으로 맥락을 관리해야 하는 상황이다.

4. AI 프롬프트 구성 및 API 통신 흐름

Claude Code CLI의 AI 통신 흐름은 사용자 입력을 적절한 프롬프트로 만들어 Anthropic의 Claude API에 보내고, 응답을 처리하여 결과를 적용하는 일련의 사이클로 이뤄진다. 이 절에서는 프롬프트 생성부터 응답 파싱, 코드 적용에 이르는 상세 메커니즘을 설명한다.

시스템 프롬프트와 사용자 프롬프트 구성: Claude Code는 내부적으로 여러 시스템 프롬프트 템플릿을 가지고 있어, 모델에게 대화의 맥락과 역할을 설정해준다. 예를 들어 코드 설명, 코드 생성, 코드 리뷰 각각에 특화된 시스템 지침이 존재하며, prompts.ts 파일에 하드코딩되어 있다. 그런 다음, 사용자의 명령 내용과 선택된 컨텍스트 파일 내용 등을 합쳐 최종 사용자 프롬프트를 형성한다. 상용구 형태의 템플릿이 사용되는데, 예컨대 코드 설명 요청의 경우 “Please explain this code:” 라는 문구 다음에 해당 코드가 마크다운 코드블록(```) 안에 삽입되는 형태다. 코드 생성 요청의 경우 “Generate [언어] code that does X. Provide only the code.”와 같은 프롬프트를 생성한다. 아래는 두 가지 프롬프트 예시를 JSON 형태로 보여준다:

// 코드 설명 요청의 실제 API 페이로드 예
{
  "model": "claude-3-opus-20240229",
  "messages": [{
    "role": "user",
    "content": "Please explain this code:\n\n```javascript\nfunction factorial(n) {\n  if (n <= 1) return 1;\n  return n * factorial(n - 1);\n}\n```"
  }],
  "max_tokens": 4096
}

// 코드 생성 요청의 실제 API 페이로드 예
{
  "model": "claude-3-opus-20240229",
  "messages": [{
    "role": "user",
    "content": "Generate TypeScript code that implements a binary search tree. Please provide only the code without explanations."
  }]
}

위처럼 Anthropic 완성형 API는 대화 형식의 messages 배열(각 요소는 role과 content 필드)로 프롬프트를 전달하며, Claude Code는 컨텍스트에 따라 user role로 된 메시지 목록을 구성한다. 멀티턴 대화의 경우 이전 대화 메시지들도 messages에 포함되지만, 단일 턴 명령의 경우 시스템 프롬프트+사용자 프롬프트만 보내는 식으로 단순하게 구성된다. model 파라미터에는 사용 모델 (예: claude-3-opus-20240229)이 지정되며, max_tokens는 최대 생성 토큰 수, temperature 등도 옵션으로 설정된다.

API 호출 및 스트리밍: 프롬프트가 준비되면 Claude API 서비스가 HTTP POST 요청을 보내 모델 추론을 호출한다. 이때 Anthropic API 키와 버전 등이 헤더로 포함되며, 요청 본문에는 위와 같은 JSON이 담긴다. Claude Code는 스트리밍 응답을 기본 지원하므로, 응답은 HTTP SSE(Stream)로 수신된다. fetch API를 사용해 스트림을 읽으면서, 일정한 청크가 도착할 때마다 UI에 출력하여 사용자가 답변을 실시간으로 볼 수 있도록 구현되어 있다. 예컨대 긴 설명이 생성되는 경우, 한 번에 모두 출력하는 것이 아니라 토막토막 출력하여 인터랙티브한 경험을 제공한다. 응답이 완료되면 스트림을 닫고 전체 텍스트를 취합하게 된다.

API 응답 파싱: 모델의 응답은 보통 한 개 또는 여러 개의 메시지 content 블록으로 전달된다. Claude Code에서는 응답 객체를 받아 가장 첫 번째 텍스트 블록을 추출하여 사용한다. 응답 내용이 일반 자연어라면 그저 콘솔에 출력하면 되지만, 코드나 구조화된 지시사항이 포함된 경우에는 추가 파싱 처리가 이뤄진다. 대표적으로 코드 블록 추출 및 파일 생성 기능이 있다. 모델이 답변 중에 코드블럭으로 감싼 코드조각을 여러 개 내놓을 수 있는데, Claude Code는 이를 찾아내 각 코드블록을 파일로 저장한다. 예를 들어 모델이 새로운 함수 코드와 테스트 코드를 두 개의 코드블록으로 제시하면, 각각을 별도 파일로 생성해주는 것이다. 이를 위한 CodeResponseParser 유틸리티 클래스가 구현되어 있으며, 정규식을 통해 “typescript\n// filename\n” 이런 패턴을 탐지하여 파일명과 내용을 추출한다. 아래는 그 동작을 보여주는 코드 일부이다:

class CodeResponseParser {
  extractCodeBlocks(responseText: string) {
    const codeBlocks = [];
    const regex = /```(?:typescript|javascript)?\n(?:\/\/\s*([\w\.]+)\n)?([\s\S]*?)```/g;
    let match;
    while ((match = regex.exec(responseText)) !== null) {
      const filename = match[1] || 'snippet.txt';
      const content = match[2];
      codeBlocks.push({ filename, content });
    }
    return codeBlocks;
  }
}

위 함수는 응답 텍스트에서 코드 블록들을 찾아내, 코드 블록에 주석으로 파일명이 명시되어 있으면 그 이름을, 없으면 기본 이름(snippet.txt 등)으로 파일명을 설정하고 내용을 추출한다. 추출된 코드 블록들은 곧바로 파일로 생성된다. CLI의 파일 조작 유틸 fileOps를 이용해 지정 경로에 파일을 쓰며 (writeFile), 필요한 경우 상위 디렉토리가 없으면 생성(createDirs: true)하도록 한다. 이렇게 생성된 파일은 CLI가 곧바로 현재 프로젝트 디렉토리에서 확인할 수 있고, 모델이 제시한 새로운 코드가 실제로 적용된 형태를 띄게 된다. Claude Code는 이러한 방식으로 모델의 출력물을 실제 코드베이스에 반영하여 결과를 빠르게 검증하거나 이어서 작업할 수 있게 한다.

추가 지시사항 처리: 모델의 응답에는 코드만이 아니라 “1. 을 설치하세요. 2. 설정을 업데이트하세요.” 등의 순차 지시사항(instructions)이 포함될 수 있다. Claude Code는 응답 텍스트에서 이런 목록 형태의 지시를 추출하는 로직도 갖추고 있다. 정규식을 통해 1. ... 처럼 숫자 목록을 찾아내 문자열로 수집한 후, 그 중 npm install 같은 키워드가 포함된 항목을 식별하여 실제 명령으로 실행한다. 예컨대 모델 응답에 “1. npm install --save-dev jest ...“가 있었다면, 백틱(```) 안의 명령을 뽑아내어 로컬 executionEnv를 통해 실행하는 식이다. 이를 통해 모델이 제안한 패키지 설치 등을 자동으로 수행해 개발자 개입을 줄여준다. 다만 보안상 이러한 자동 명령 실행은 BashTool과 동일한 권한 체크를 거치므로, 위험한 명령은 실행되지 않고 사용자 승인이 필요할 수도 있다.

응답 결과의 코드 반영: 앞서 설명한 코드블록 자동 파일생성 외에도, 모델이 기존 파일 수정 사항을 제시하는 경우 이를 반영하는 로직이 있다. Claude Code는 두 가지 접근을 취하는데, 하나는 Patch(diff) 적용이고 다른 하나는 전체 파일 대치이다. 모델이 만약 “diff\n--- a/file.js\n+++ b/file.js\n@@ ...” 형태의 패치를 응답하면, fileOps.applyPatch()를 통해 해당 diff를 원본 파일에 적용해준다. 반면 모델이 리팩토링된 코드 전체를 통째로 코드블록으로 내놓는 경우(그리고 변경 요약을 별도로 텍스트로 주는 경우), CLI는 원본 파일을 백업한 뒤 새 코드로 파일을 교체한다. 예를 들어 리팩토링 시나리오에서, handleRefactoringRequest 함수는 다음과 같이 동작한다:

// 리팩토링 명령 처리 예시
const originalCode = await fileOps.readFile(filePath);
const prompt = {...생략...`${originalCode.content}`...};  // 프롬프트 구성
const response = await aiClient.complete([prompt]);
// 응답에서 코드와 변경사항 추출
const refactoredCode = extractRefactoredCode(response.content[0].text);
const changes = extractChangesList(response.content[0].text);
// 기존 파일 백업 및 새 코드 써넣기
if (refactoredCode) {
    await fileOps.writeFile(`${filePath}.backup`, originalCode.content);
    await fileOps.writeFile(filePath, refactoredCode);
    console.log('Refactoring completed. Changes:');
    changes.forEach((c, i) => console.log(`${i+1}. ${c}`));
}

위 예시처럼, 응답 파싱을 통해 새로운 코드 조각과 변경 요약 목록을 얻은 뒤, 원본 파일은 .backup으로 저장하고 새 코드로 덮어씌운다. 그리고 모델이 제공한 변경 사항 설명을 콘솔에 출력하여 어떤 개선이 있었는지 사용자에게 보여준다. 이러한 자동화 덕분에 개발자는 모델의 수정 결과를 바로 코드에 적용하고 검토할 수 있으며, 문제 시 백업본으로 롤백하는 것도 가능하다.

오류 처리 및 재시도 로직: LLM 호출이나 응답 처리 중 발생하는 오류에 대비해 Claude Code에는 재시도 및 보정 로직이 포함되어 있다. aiClient.complete() 내부나 그 래퍼에서 HTTP 요청 실패, 타임아웃 등에 대해 최대 3회 재시도하도록 구성되어 있고, 재시도 간에 지수 백오프 (initial delay 1초, 최대 10초 등) 전략을 적용한다. 또한 응답 파싱 단계에서 JSON 형식 오류 등이 발생할 경우, 모델에게 형식 수정 요청을 자동으로 보내는 기능이 있다. 예컨데 내부적으로 JSON 파싱을 기대했는데 응답이 흐트러진 경우, ... Please format your response as valid JSON.이라는 문구를 프롬프트 끝에 추가해 모델이 다시 시도하도록 하는 식이다. 이는 한 번의 명령 수행 중에 추가 API 호출을 발생시키지만, 전체 프로세스의 신뢰성을 높이기 위한 장치다. 이러한 오류 처리 로직은 Claude Code의 안정성을 높여주며, 실제 Anthropic API 서비스 모듈에도 재시도 및 백오프, 응답 파싱 보조 기능이 내장되어 있음을 알 수 있다. 요컨대, Claude Code는 API 통신 단계에서 발생할 수 있는 네트워크 문제나 모델 출력 오류를 최대한 자동으로 수습하여 사용자 경험을 해치지 않도록 설계되어 있다.

실제 사용 시나리오 및 예시

이 절에서는 Claude Code CLI의 실제 사용 흐름을 몇 가지 대표 시나리오로 살펴본다. 각 시나리오에서 어떻게 Plan/Task 구조가 활용되거나, 단순 질의로 처리되는지, 그리고 멀티턴 대화 관리가 어떻게 이루어지는지 설명한다.

  • 시나리오 1: 함수 리팩토링 – “이 함수를 더 효율적으로 리팩토링해줘” 개발자가 특정 파일의 함수를 개선하고자 할 때, Claude Code에 리팩토링을 요청할 수 있다. 예를 들어 claude refactor src/utils/helper.js --focus performance와 같이 명령을 실행하면, 내부적으로 위 파일 내용을 읽어 성능 향상을 위한 리팩토링을 지시하는 프롬프트를 생성한다. 이때 특별히 Plan 등을 만들지는 않고, 단일 턴으로 처리한다. 모델은 응답으로 개선된 코드 블록과 변경 사항 설명을 함께 줄 수 있다. 앞서 설명한 대로 CLI는 이를 파싱해 파일을 업데이트하고 변경 요약을 출력한다. 사용자는 곧바로 코드 변경 결과물을 확인하고, 필요한 경우 백업본과 비교하여 검토할 수 있다. 이 시나리오에서는 하나의 파일에 대한 작업이므로 컨텍스트 관리가 단순하며, --focus 옵션처럼 사용자 힌트를 일부 줄 수는 있으나, 대부분 모델의 단일 응답으로 문제를 해결한다. Plan-Task 에이전트 루프를 돌지 않는 케이스지만, 모델 자체가 변경 내용을 요약까지 제공하여 한 번의 응답으로 충분한 정보를 준다.

  • 시나리오 2: 버그 수정 – “이 에러를 고쳐줘” 프로젝트 코드에서 발생한 에러(stack trace나 컴파일 에러 등)를 해결하는 경우다. 예를 들어 claude fix src/api/userService.ts --issue "Type error in getUserData"라고 입력하면, Claude Code는 userService.ts 파일을 읽어 해당 에러 메시지와 함께 모델에 넘긴다. 모델은 주어진 코드와 에러 내용을 보고 원인을 파악한 뒤, 수정된 코드 블록 또는 수정 지침(diff 등) 형태로 응답한다. 만약 간단한 타입 오류라면 모델은 코드 한 두 줄만 고치면 될 것이고, CLI는 그에 따라 파일을 편집(FileEditTool 또는 applyPatch)하게 된다. 이 과정에서도 기본적으로 한 턴으로 처리되지만, 만약 모델이 “이 타입이 정의되지 않았네요”처럼 다른 파일을 참고하고 싶어하면 (그러나 자동 맥락이 제공되지 않았으므로) 적절히 추측해서 답을 내놓게 된다. 이 시나리오에서 멀티턴이 발생하는 경우는 모델이 수정 후 테스트 실행 등을 제안하는 때다. 예컨대 모델이 “고쳤으니 테스트를 돌려보자”라고 하면, 사용자가 yes로 응답해 BashTool을 통한 npm test 실행이 이어질 수 있다. Claude Code는 대화 맥락을 유지하므로, 이전 턴에서 수정한 내용이 이후 턴 대화에 반영되어, 테스트 결과에 따라 추가 버그를 잡는 대화형 디버깅 세션이 가능하다. 이처럼 버그 수정 시나리오는 문제에 따라 단일턴으로 끝날 수도, 여러 턴의 대화로 이어질 수도 있다.

  • 시나리오 3: 새로운 기능 추가 – “프로젝트에 다크 모드 기능을 추가해줘” 비교적 복잡한 요청으로, 여러 파일을 변경하고 새로운 모듈을 작성해야 하는 작업이다. 이러한 복합적 요구에 대해 Claude Code는 Plan-Task 구조를 적극 활용한다. 사용자가 자연어로 “다크 모드를 구현해줘”라고 입력하면 (현재 /generate 명령으로 할 수도 있고, 그냥 대화 모드로 말할 수도 있다), 모델은 이를 복잡한 요청으로 인식하고 우선 수행할 작업들을 나열하는 Plan을 만든다. 예를 들어 Plan에는 ① 현재 테마 시스템 분석, ② 테마 컨텍스트 생성, ③ 다크모드 스타일 추가, ④ 테마 토글 UI 구현, ⑤ 기존 컴포넌트에 테마 적용 등의 할 일 목록이 포함될 수 있다. Claude Code CLI는 이 Plan을 받아 리스트로 표시하고, 순서대로 항목을 실행하기 시작한다. 먼저 Plan 1 “현재 테마 시스템 분석”이 수행된다. 모델은 이 작업을 위해 프로젝트에서 관련 정보를 찾으려고, GlobTool로 CSS 파일들을 찾고, GrepTool로 코드에서 “theme”이나 “dark” 키워드를 검색하며, View로 주요 스타일 파일이나 진입 컴포넌트 파일을 열람한다. CLI는 각각의 툴 호출을 실행하여 결과(예: “45개의 CSS 파일 발견”, “5개의 파일에서 ‘dark’ 문자열 발견”, “src/App.tsx 내용” 등)를 모델에게 반환한다. 모델은 이 정보를 토대로 현재 테마 구현 상황을 파악하고 Plan 1을 완료한다. CLI는 Plan 1을 완료로 표시한 뒤, Plan 2 “테마 Context 구현”으로 넘어간다. 여기서는 모델이 새로운 파일을 작성하기 위해 Write 툴을 호출하여 ThemeContext.tsx 파일을 생성하고, Edit 툴로 기존 App.tsx에 <ThemeProvider>를 래핑하도록 수정한다. CLI는 실제로 해당 파일을 생성하고, 기존 파일을 수정하여 패치 적용한다. 이런 식으로 Plan의 각 항목마다 필요한 Task들이 연쇄적으로 일어나며, 모델이 에이전트로서 능동적으로 탐색→코딩→편집을 수행하는 것이다. 모든 Plan 항목(Plan 3: 스타일 정의, Plan 4: 토글 컴포넌트, Plan 5: 기존 코드 적용)이 끝나면, 모델은 최종적으로 “다크모드 기능 추가 완료”라는 요약 메시지나 추가 확인 사항을 제시할 수 있고, 세션이 종료된다. 이 시나리오를 통해 보는 것처럼, Claude Code는 복잡한 요구를 처리할 때 여러 턴에 걸쳐 도구 사용과 코드 생성을 병행하며, 사용자 대신 코드를 여러 파일에 걸쳐 삽입/수정해준다. 개발자는 이러한 과정을 실시간으로 지켜보면서, 각 단계에서 허가(예: 파일 생성/수정 권한)를 내리고 결과를 검토할 수 있다. 대화 히스토리는 Plan과 Task 내역까지 모두 남아서, 차후에 “방금 한 작업을 요약해줘”라고 물어보는 등도 가능하다. 멀티턴 대화 관리 측면에서, Claude Code는 대화 컨텍스트에 이전 메시지 + 툴 사용 내역 + 결과를 모두 쌓아가며 모델에게 전달하므로, 모델은 매 턴 현재까지의 진행 상황을 기억하고 일관성 있게 다음 행동을 결정할 수 있다.

  • 시나리오 4: 멀티턴 코드 리뷰 및 개선 – “코드베이스를 분석해서 개선사항을 제안해줘” 이 시나리오는 보다 고급 활용으로, 전체 프로젝트를 대상으로 한 분석과 지속적 개선 작업을 수행하는 경우다. 예를 들어 사용자가 “프로젝트를 살펴보고 개선할 부분을 알려줘”라고 하면, Claude Code는 우선 프로젝트 구조를 분석하여 요약 정보를 얻는다 (이미 언급한 analyzeCodebase 함수 등이 이에 해당). 그런 다음 그 구조 정보를 포함한 프롬프트를 생성한다. 한 예로, AIConversationManager라는 관리 클래스가 있다고 가정하면, 다음과 같은 프롬프트를 만들 수 있다:

// 프로젝트 구조 요약을 포함한 초기 분석 프롬프트 생성 예시
const structure = analyzeCodebase('.');
const prompt = `
  I'm working with a ${structure.filesByLanguage.TypeScript ? 'TypeScript' : 'JavaScript'} project.
  Project structure:
  - Total files: ${structure.totalFiles}
  - Main language: ${Object.keys(structure.filesByLanguage)[0]}
  - Dependencies: ${structure.dependencies.length} packages

  Now, please analyze this code and suggest improvements:
  ${someRelevantCodeExcerpt}
`;
const response = await aiClient.complete([{role: 'user', content: prompt}]);
  • 여기서 프로젝트 통계와 함께, 일부 핵심 코드 발췌본(${someRelevantCodeExcerpt})을 첨부하여 모델이 중요한 맥락을 파악하도록 돕는다. 모델은 응답으로 여러 개선 제안을 목록 형태로 줄 수 있다 (예: “1. 함수 X 리팩토링: 너무 복잡함, 2. 의존성 Y 업그레이드: 보안 취약” 등). Claude Code는 응답을 파싱하여 개선사항 리스트를 추출하고, 각각의 우선순위를 계산하거나 분류한다. 그런 다음 사용자가 특정 개선안을 실행하도록 지시하면 (executeImprovement(improvement) 호출), 해당 항목을 구현하는 프롬프트를 생성해 모델에게 보낸다. 모델은 해당 개선에 필요한 코드 변경사항을 결과로 주고, CLI는 이를 파싱하여 파일 생성/편집을 수행한다. 이 방식은 일종의 대화형 코드 리뷰 및 리팩토링 세션으로, 모델이 먼저 프로젝트를 리뷰한 후 여러 아이디어를 제공하면, 개발자가 “좋아, 2번 항목을 적용해줘” 식으로 요청하여 모델이 코드를 바꾸게 하는 것이다. 이 때 대화 컨텍스트에는 앞서 나온 개선 제안 내용이 포함되어 있으므로, 모델은 해당 부분을 참조하면서 변경을 수행한다. Claude Code는 각 턴의 메시지를 this.messages 등의 리스트에 쌓아두고, 매번 aiClient.complete(this.messages) 형태로 전체 대화맥락을 모델에게 보내 멀티턴 컨텍스트를 유지한다. 이러한 멀티턴 관리 방식 덕분에, 모델은 이전에 자체 제안한 개선사항을 기억하고, 그것을 구현하는 과정에서도 일관성을 가지게 된다. 사용자는 단계별로 결과를 확인하면서 필요하면 수정 지시를 추가하거나, 다음 개선항목으로 넘어갈 수 있다. 이 시나리오는 아직 일반적인 사용 사례라기보다는 Claude Code의 잠재력을 보여주는 예시이다. 현재 구현이 얼마나 이 시나리오를 뒷받침하는지는 완벽하지 않지만, 코드상에 이와 유사한 형태의 대화 관리 로직이 포함되어 있어 향후 가능성을 시사한다. 무엇보다 Claude Code가 단순히 한 두 파일 작업에 그치지 않고, 프로젝트 수준으로 대화를 확장할 수 있음을 보여준다. 이것이 실현된다면, 개발자는 AI와 함께 지속적인 리팩토링/품질 개선 피드백 루프를 돌 수 있을 것으로 기대된다.

요약하자면, Claude Code CLI는 간단한 명령 (단일턴)부터 복잡한 요구 (플랜 기반 멀티턴)까지 폭넓게 대응하도록 설계되어 있다. Plan-Task 구조는 복잡한 작업을 잘게 나눠 수행하는 데 유용하며, 대화형으로 피드백을 주고받으며 코드를 개선해 나가는 시나리오도 지원된다. 다만 현 시점에서는 Plan 기능이 항상 발동되는 것은 아니고, 명시적인 슬래시 명령 위주로 동작하는 경향이 있다. 예를 들어 사용자가 그냥 자연어로 복잡한 요구를 했을 때 Plan을 잘 생성해내는지는 시스템 프롬프트와 모델의 판단에 달려 있다. 이러한 부분 역시 추후 사용자 제어 옵션이나 인텔리전스 개선 여지가 있다.

결론 및 개선 방향

Claude Code CLI의 내부 구현을 살펴보면, 현재는 완전한 “지능형” 에이전트라기보다 정교하게 포장된 프롬프트와 툴 호출 시퀀스로 이루어진 초기 단계 제품임을 알 수 있다. 아키텍처 측면에서 REPL 기반의 대화형 인터페이스, 다양한 도구 플러그인, 멀티턴 계획 수행 로직 등 최신 에이전트 프레임워크의 개념들을 적용하고 있으나, 대용량 코드베이스 지원이나 자동 컨텍스트 관리 같은 측면에서는 아직 한계가 뚜렷하다. 결론적으로 Claude Code CLI의 현황과 향후 개선 방향을 정리하면 다음과 같다:

  • 현재 구현의 한계: 파일 선택과 컨텍스트 구성에서 자동화 지능이 부족하며, 실질적으로는 크기/패턴 제한에 기반한 1차원적인 필터링과 사용자 수동 컨텍스트 지정에 의존하고 있다. 모델이 프로젝트를 폭넓게 이해한다고 하지만, 정작 필요한 파일들을 알아서 선별하여 제공해주지 않기 때문에, “코드베이스를 이해한다”는 슬로건 대비 실제 체감 효용은 낮을 수 있다. 또한 Plan-Task 구조의 활용이 일관되지 않고, 어떤 때는 모델이 계획을 잘게 세워 진행하지만 어떤 때는 단순 응답으로 끝나는 등 에이전트 능동성의 편차가 존재한다. 성능 면에서는, 다중 호출 루프로 인한 응답 지연과 토큰 비용 상승 문제가 지적될 수 있다. (MAX 요금제를 사용하면 토큰비용을 별도로 내지 않음) 토큰 비용 상승은 필요 이상의 맥락(예: 전체 디렉토리 트리)을 매번 포함하거나, 여러 차례 API 호출을 거치기 때문으로 추정된다.
  • 보안 및 안정성: 긍정적으로 볼 부분은 강력한 권한 체계와 제한 장치를 통해 비교적 안전하게 동작한다는 점이다. 그러나 보안상의 제약으로 인해 모델이 어떤 작업을 하려다 막히는 경우(예: 권한 거부) 대화 흐름이 종종 끊길 수 있고, 아직 미흡한 UI 피드백으로 인해 사용자가 혼란을 겪는 사례도 있다. 예를 들어 권한 요구 창이 반복된다거나, 이미 읽은 파일을 다시 읽으려고 시도하는 등의 세션 관리 이슈가 보고된 바 있다. 이러한 부분은 버그 수정을 통해 개선될 필요가 있다.
  • 향후 개선 필요사항: 가장 핵심적인 개선 방향은 자동 컨텍스트 구성의 지능화다. 이를 위해 프로젝트 코드에 대한 임베딩 기반 유사도 검색, 정적 분석을 통한 종속 관계 그래프 활용, 실행 중인 프로그램 상태와 연동 등 다양한 기법을 도입할 수 있을 것이다. 예컨대 오류가 발생하면 스택트레이스를 파싱해 관련 모듈을 모두 불러온다든가, 새로운 기능 추가 시 기존 비슷한 구현을 참조하도록 하는 기능 등이 필요하다. Anthropic에서도 공식적으로 “Claude Code가 전체 프로젝트 구조를 인지하고 필요한 파일을 탐색한다”고 언급하고 있으므로, 이러한 컨텍스트 확장 기능은 향후 업데이트에서 실제로 구현될 것으로 기대된다.
  • 대화 경험 향상: 멀티턴 대화 관리 측면에서는, 현재는 단순히 메시지 배열을 유지하는 방식이지만 향후 대화 요약 기법이나 중요 맥락 강조 기법 등을 통해 장기 세션에서도 맥락을 잃지 않고 응답 속도를 높이는 방향으로 발전이 필요하다. 또한 사용자가 원하는 대화 방식(예: 한 번에 큰 변경 vs 단계적 진행)을 지정할 수 있는 옵션을 주거나, 모델이 Plan을 세웠을 때 이를 편집하거나 재명령할 수 있는 상호작용성 개선도 생각해볼 만하다.
  • 성능 및 비용 최적화: 여러 단계에 걸친 호출을 효과적으로 줄이기 위해, 내부 프롬프트 엔지니어링 개선이 요구된다. 예를 들어 간단한 변경에도 Plan을 생성하는 과정을 생략하고 단발성으로 처리하도록 하거나, 반대로 복잡한 건은 처음부터 한 번에 다 해결하려 하지 말고 Plan→Task로 나누게 하여 실패율을 낮추는 전략 등을 더 세밀히 튜닝할 수 있다. 캐싱된 프로젝트 인덱스 정보를 적극 활용해 같은 맥락 정보를 반복 전달하지 않도록 하거나, 필요시 외부 벡터 DB와 연계한 검색으로 토큰 낭비를 막는 것도 한 방향이다. Anthropic 측도 앞으로 “도구 실행 신뢰성, 장시간 실행 지원, 자체 능력에 대한 인식 향상” 등을 개선 과제로 언급했는데, 이는 곧 Claude Code의 에이전트로서의 완성도를 높이는 작업이라 할 수 있다.
  • 대용량 프로젝트 지원 강화: 현재 1000개 파일 제한 등은 현실의 거대 모노레포 환경에는 부족할 수 있다. 향후에는 부분적 코드베이스 로딩이나 프로젝트 셰이프에 따른 유동적 제한 등이 필요하다. 가령 거대한 프로젝트에서는 폴더 단위로 초점을 이동하며 분석한다든지, 중요도가 낮은 코드(예: 과거 릴리즈용 폴더)는 아예 제외하는 사용자 설정을 제공하는 식이다. 또한 UI/UX 측면에서, 대용량 프로젝트일수록 진행 상태를 시각적으로 표시하거나, 사용자에게 “어느 디렉토리를 집중 분석할까요?” 등을 물어보는 인터랙티브 설정이 있다면 유용할 것이다.

결론적으로, Claude Code CLI는 Anthropic의 LLM을 활용한 혁신적 개발자 도구로서 가능성을 보여주었지만, 아직은 초기 버전으로서 완전한 자동화보다는 반자동에 가까운 상태다. 그럼에도 불구하고, 강력한 언어모델과 터미널 통합 덕분에 개발 워크플로에 새로운 경험을 제공하고 있으며, 향후 지속적인 개선을 통해 대규모 프로젝트에서도 효율적이고 지능적으로 협업하는 AI 페어 프로그래머로 발전할 것으로 기대된다. 엔지니어팀은 이러한 도구를 도입할 때 현재의 한계를 인지하고 적절히 활용하는 한편, 추후 릴리스 노트를 주시하며 새로운 기능(특히 자동 맥락 관리)의 도입으로 인한 생산성 향상을 도모해야 할 것이다. 또한 기업 환경에서는 코드 프라이버시에 유의해야 하지만, 기술적인 관점에서 Claude Code는 AI와 개발자 협업의 흥미로운 청사진을 제시하고 있다.

참고자료

  1. Reid Barber, “Reverse engineering Claude Code,”
  2. Anthropic, “Claude Code Overview,” Anthropic Developer Docs, 2024
  3. Geoffrey Huntley, “Yes, Claude Code can decompile itself. Here’s the source code.,”