대규모 코드베이스에서 Claude Code가 동작하는 방식: 모범 사례와 시작점

Who Should Read

수십 명 이상의 엔지니어링 조직에서 Claude Code 도입을 검토 중이거나 이미 사용 중인 테크 리드 또는 플랫폼 엔지니어. 특히 대형 모노레포나 레거시 코드베이스에 AI 코딩 도구를 적용하려는 사람.

Core Mechanics

• Claude Code는 코드베이스 전체를 미리 임베딩(텍스트를 벡터로 변환해 인덱스를 만드는 방식)하지 않는다. 대신 실제 파일 시스템을 직접 탐색하고, grep으로 필요한 부분을 찾고, 참조를 따라가는 방식으로 동작한다.
• RAG(검색 증강 생성) 기반 코딩 도구는 대규모 팀 환경에서 인덱스가 실제 코드보다 뒤처지는 문제가 생긴다. 수천 명이 커밋하는 환경에서는 인덱스가 몇 주, 심지어 몇 시간 전 상태를 반영해 이미 삭제된 모듈이나 이름이 바뀐 함수를 참조할 수 있다.
• 에이전틱 검색(Claude가 직접 파일 시스템을 돌아다니며 탐색하는 방식)은 인덱스 동기화 문제를 피할 수 있지만, 시작 컨텍스트가 충분하지 않으면 탐색 품질이 크게 떨어진다. 수십억 줄짜리 코드베이스에서 애매한 패턴을 찾아달라고 하면 성능 한계에 부딪힌다.
• CLAUDE.md 파일과 Skills(재사용 가능한 작업 정의 파일)를 계층적으로 구성해 컨텍스트를 쌓아주는 것이 대규모 코드베이스에서 성공적인 Claude Code 운영의 핵심 패턴이다.
• C, C++, C#, Java, PHP처럼 AI 코딩 도구와 연관짓기 어렵다고 여겨진 언어들에서도 최근 모델 릴리스 기준으로 팀들이 기대하는 것보다 더 잘 동작한다고 Anthropic은 밝혔다.
• 성공적인 대규모 배포 사례들은 설정, 툴링, 조직 구조에 걸쳐 공통된 패턴을 공유하고 있으며, 이를 이 시리즈에서 지속적으로 다룰 예정이다.

Evidence

• '소프트웨어 엔지니어처럼 탐색한다'는 표현에 의문을 제기하는 댓글이 있었다. 실제 개발자는 LSP, CMD+P 자동완성, 과거에 쌓인 코드베이스 기억(이것 자체가 일종의 RAG 아닌가?) 등 다양한 인덱싱 도구를 함께 사용하는데, 왜 Claude는 인덱스를 쓰지 않는 것이 장점처럼 묘사되는지 납득하기 어렵다는 지적이었다.
• 실제 경험담으로, Claude Code가 각 파일의 앞 40줄만 읽는 초기 접근 방식을 선택했다가 나중에 스스로 결함을 발견해 AST(추상 구문 트리) 분석으로 전환한 사례가 공유됐다. 댓글 작성자는 '개별 결정은 합리적으로 보여도 조합이 나쁜 결과를 낳는 진짜 품질 문제는 도구가 수렴하기 어렵다'는 구조적 한계를 지적했다.
• 레지스트리 패턴을 코드베이스 전체에 걸쳐 통일하라는 명시적 규칙이 있었음에도 Claude Code가 4개의 독립적인 레지스트리를 별도로 구현해버린 경험이 공유됐다. 이 문제를 바로잡는 데 반나절이 걸렸고, 결국 직접 수정했다는 사용자는 '전체 코드베이스 이해가 필요한 변경에는 Claude Code가 약하다'고 평가했다.
• Claude Code가 Skills와 CLAUDE.md에 명시된 지시를 90%의 경우에 무시한다는 불만이 여러 댓글에서 반복됐다. 특히 테스트 실패 원인을 파일에 저장해 분석하라는 Skill이 있어도 매번 tail 10으로 잘라서 보는 비효율적인 방식을 반복한다는 구체적 사례가 있었다.
• PHPStorm 같은 JetBrains IDE의 코드베이스 인덱싱이 실제로 잘 작동한다는 댓글이 있었다. RAG 기반 인덱싱이 대규모에서 실패한다는 원문의 주장에 직접 반론을 제기한 것이다.

How to Apply

• 수십 개의 서브디렉토리마다 빌드 명령이 다른 모노레포를 운영 중이라면, 각 서브디렉토리에 CLAUDE.md 파일을 두고 해당 디렉토리의 빌드 명령, 테스트 방법, 주요 패턴을 명시적으로 적어두어야 한다. Claude Code는 이 파일을 계층적으로 읽어 컨텍스트를 쌓기 때문에 탐색 품질이 크게 올라간다.
• 코드베이스 전반에 걸쳐 지켜야 할 아키텍처 패턴(예: 레지스트리 패턴, 특정 추상화 계층 사용 규칙)이 있다면 CLAUDE.md에 단순 언급이 아닌 구체적인 예시 코드와 함께 명시해야 한다. 댓글 사례처럼 규칙만 적어두면 Claude Code가 무시하는 경우가 많기 때문이다.
• 레거시 C/C++ 또는 Java 코드베이스를 관리 중인데 AI 코딩 도구 도입을 망설이고 있다면, Anthropic이 최근 모델에서 해당 언어 지원이 개선됐다고 밝혔으므로 작은 서브모듈부터 파일럿 테스트를 해볼 수 있다.
• Claude Code가 반복적으로 비효율적인 방식(예: tail 10으로 로그 잘라 읽기)을 사용한다면, Skills를 통해 표준 작업 흐름을 정의하되 프롬프트에 해당 Skill을 명시적으로 호출하도록 지시하는 습관이 필요하다. 현재는 Skill이 자동으로 호출되지 않는 경우가 많다는 커뮤니티 경험이 있다.

Terminology

관련 논문

• 프로덕션 AI 에이전트를 GPT-5.6으로 마이그레이션: 2.2배 빠르고 27% 저렴

  마케팅 웹사이트를 자동 생성하는 프로덕션 AI 에이전트를 Claude Opus 4.8에서 GPT-5.6 Sol로 전환한 실전 경험담으로, 단순 모델 교체가 아니라 eval 하네스, 툴 스키마, 캐싱, 추론 리플레이까지 손봐야 했던 과정을 구체적인 수치와 함께 정리했다.

• xAI Grok Build CLI가 xAI 서버로 전송하는 데이터: 네트워크 레벨 분석

  xAI의 공식 코딩 CLI 도구 Grok Build가 사용자 동의 없이 전체 Git 저장소와 .env 시크릿 파일을 xAI 서버로 업로드한다는 사실이 네트워크 트래픽 분석으로 밝혀졌다.

• 중요할 때 기억하라: Long-Horizon 에이전트를 위한 Proactive Memory Agent

  LLM 에이전트가 긴 작업 중 중요한 정보를 잊어버리는 문제를 별도의 메모리 에이전트가 '적절한 타이밍에' 끼어들어 해결하는 방법

• WebSwarm: 깊고 넓은 웹 검색을 위한 재귀적 Multi-Agent Orchestration

  복잡한 웹 검색을 재귀적으로 분해하고 각 노드에 적합한 검색 모드를 동적으로 할당하는 멀티에이전트 프레임워크

• 웹 앱을 리버스 엔지니어링해서 AI Agent 도구로 자동 변환하기

  로그인된 웹 앱의 API 호출을 브라우저에서 감시해 자동으로 MCP 도구로 변환하는 에이전트를 만들었다. 소스 코드나 공식 API 문서 없이도 Jira, Spotify 같은 서비스에 AI 어시스턴트를 붙일 수 있다.

• FableCut – AI 에이전트가 조작할 수 있는 브라우저 기반 비디오 에디터 (zero deps)

  타임라인 전체를 JSON 파일 하나로 표현하고 MCP/REST로 AI 에이전트가 직접 편집할 수 있는 브라우저 비디오 에디터로, Claude 같은 AI가 프롬프트 하나로 영상을 자동 컷편집하고 결과를 실시간으로 UI에 반영해준다.

Related Resources

• How Claude Code works in large codebases: Best practices and where to start (원문)