대규모 코드베이스에서 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

관련 논문

• Needle: Gemini의 Tool Calling 능력을 26M 파라미터 모델로 증류

  Gemini의 함수 호출(tool calling) 능력만 뽑아서 26M(2600만) 파라미터짜리 초경량 모델로 만든 프로젝트로, 폰/워치/스마트글라스 같은 엣지 디바이스에서 직접 실행 가능하다.

• 메인프레임과 COBOL을 위한 Agentic 개발 환경 'Hopper'

  수십 년 된 메인프레임(z/OS) 환경을 AI 에이전트로 조작할 수 있게 해주는 개발 도구로, COBOL 코드 작성부터 JCL 실행, 디버깅까지 자연어로 처리할 수 있어 레거시 시스템 유지보수 비용을 크게 줄일 수 있다.

• Statewright – AI 에이전트를 안정적으로 만드는 Visual State Machine

  AI 에이전트에게 40개 이상의 도구를 주면 오히려 성능이 떨어지는 문제를 State Machine으로 각 단계별 사용 가능한 도구를 제한해 해결하는 오픈소스 프로젝트다. 더 큰 모델 대신 더 작은 문제 공간을 만들어 신뢰성을 높이는 접근이 핵심이다.

• adamsreview: Claude Code용 멀티 에이전트 PR 코드 리뷰 파이프라인

  Claude Code에서 최대 7개의 병렬 서브 에이전트가 각각 다른 관점으로 PR을 리뷰하고, 자동 수정까지 해주는 오픈소스 플러그인이다. 기존 /review나 CodeRabbit보다 실제 버그를 더 많이 잡는다고 주장하지만 커뮤니티에서는 복잡도와 실효성에 대한 회의론도 나왔다.

• Claude를 User Space IP Stack으로 써서 Ping에 응답시키면 얼마나 빠를까?

  Claude Code에게 IP 패킷을 직접 파싱하고 ICMP echo reply를 구성하도록 시켜서 실제로 ping에 응답하게 만든 실험으로, 'Markdown이 곧 코드이고 LLM이 프로세서'라는 아이디어를 네트워크 스택 수준까지 밀어붙인 재미있는 사례다.

• LLM의 Tool Calling은 내부적으로 선형 구조로 읽고 조종할 수 있다

  LLM이 어떤 툴을 호출할지는 내부 activation에 선형적으로 인코딩되어 있어서, 벡터 하나만 더하면 툴 선택을 바꿀 수 있다.

Related Resources

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