PM K씨는 수백만 줄의 코드가 얽힌 모노레포(여러 프로젝트를 하나의 저장소에서 관리하는 방식)에서 특정 함수가 어디서 쓰이는지 찾느라 시간을 보낸다. 파일 시스템을 뒤지고 grep(텍스트 검색 도구)을 돌려가며 수동으로 추적하는 과정이 반복된다. 이런 곤란을 겪는 개발자가 늘고 있다.

대규모 코드베이스를 위한 Claude Code의 작동 방식

Anthropic(앤스로픽)은 수백만 줄의 모노레포, 수십 년 된 레거시 시스템(오래된 낡은 시스템), 수십 개의 저장소로 분산된 아키텍처에서 작동하는 Claude Code의 운용 패턴을 공개했다. 이 도구는 C, C++, C#, Java, PHP 같은 언어에서도 지원되며, 최근 모델 릴리스를 통해 해당 언어들에서의 성능이 향상되었다. Claude Code는 개발자의 로컬 머신에서 직접 작동하는 구조다. 별도의 코드베이스 인덱스(색인)를 구축하거나 유지 관리할 필요가 없으며, 데이터를 외부 서버로 업로드하는 과정도 생략한다.

RAG의 한계와 에이전틱 검색의 도입

기존 AI 코딩 도구는 RAG(검색 증강 생성, 외부 데이터를 찾아 답변에 활용하는 기술) 기반의 검색에 의존했다. 전체 코드베이스를 임베딩(데이터를 벡터 숫자로 변환하는 과정)하여 쿼리 시점에 관련 조각을 가져오는 방식이다. 반면 Claude Code는 에이전틱 검색(AI가 스스로 도구를 사용해 탐색하는 방식)을 사용한다. RAG 방식은 임베딩 파이프라인이 실시간 커밋 속도를 따라가지 못해 며칠 전의 낡은 코드를 참조하는 오류가 잦다. 개발자가 쿼리를 던졌을 때 이미 삭제된 모듈이나 이름이 바뀐 함수를 반환하는 사례가 대표적이다. 그러나 에이전틱 검색은 중앙 인덱스 없이 라이브 코드베이스에서 직접 작동하므로 최신 상태를 유지한다.

다만 에이전틱 검색 방식에는 트레이드오프(Trade-off, 어느 하나를 얻으면 다른 하나를 잃는 관계)가 존재한다. Claude가 어디를 찾아야 할지 알 수 있는 충분한 시작 컨텍스트가 제공되어야 최적의 성능을 낸다. 만약 수십억 줄의 코드베이스에서 모호한 패턴을 찾아달라고 요청하면, 작업이 시작되기도 전에 컨텍스트 윈도우(AI가 한 번에 처리할 수 있는 데이터 양) 제한에 도달한다. 따라서 CLAUDE.md 파일과 스킬을 통해 코드베이스 설정을 정교하게 구축한 팀일수록 더 나은 결과를 얻는다.

주목할 점은 모델의 벤치마크 수치보다 이를 둘러싼 하네스(Harness, 모델의 능력을 끌어내는 실행 환경)의 구성이 실제 성능을 결정한다는 사실이다. 하네스는 다섯 가지 확장 지점으로 구성된다. CLAUDE.md 파일은 세션 시작 시 자동으로 읽히는 컨텍스트 파일이다. 루트 파일은 전체적인 그림을, 하위 디렉토리 파일은 지역적 관례를 제공한다. 훅(Hooks, 특정 이벤트 발생 시 실행되는 스크립트)은 세션 종료 후 CLAUDE.md 업데이트를 제안하는 스톱 훅(Stop hook)과 팀별 컨텍스트를 동적으로 로드하는 스타트 훅(Start hook)으로 나뉜다. 린팅(Linting, 코드 문법 검사)이나 포맷팅 같은 자동화 체크는 훅을 통해 결정론적으로 강제된다.

스킬(Skills, 특정 작업에 특화된 전문 지식)은 필요한 순간에만 전문 지식을 로드하는 점진적 공개 방식을 취한다. 보안 리뷰 스킬은 취약점 평가 시에만 로드되며, 문서 처리 스킬은 코드 변경 후 문서 업데이트가 필요할 때만 활성화된다. 이는 컨텍스트 윈도우의 낭비를 막아 성능 저하를 방지한다. 또한 스킬은 특정 경로에만 바인딩할 수 있어, 결제 서비스 팀의 배포 스킬이 모노레포의 다른 영역에서 작동하지 않도록 제어할 수 있다. 플러그인(Plugins, 기능 묶음 패키지)은 스킬, 훅, MCP(Model Context Protocol, AI 모델과 외부 데이터 소스를 연결하는 표준 규격) 설정을 하나로 묶어 배포한다. 신입 엔지니어가 플러그인을 설치하는 즉시 기존 팀원과 동일한 컨텍스트와 능력을 갖추게 된다. 여기에 LSP(Language Server Protocol, 코드 분석 및 자동완성을 위한 표준 프로토콜) 통합과 서브에이전트(Subagents, 특정 작업을 수행하는 하위 AI) 기능이 추가되어 전체 시스템을 완성한다.

AI 코딩의 승부처는 모델의 벤치마크 수치가 아니라 로컬 환경의 컨텍스트를 얼마나 정교하게 제어하느냐에 달려 있다.