How Claude Code works in large codebases

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

Related Papers

• Show HN: Semble – Code search for agents that uses 98% fewer tokens than grep

  AI 에이전트가 코드베이스를 탐색할 때 grep+파일 읽기 대신 자연어로 관련 코드 스니펫만 뽑아주는 검색 라이브러리로, 토큰 사용량을 약 98% 줄여준다.

• Zerostack – A Unix-inspired coding agent written in pure Rust

  Claude Code나 OpenCode처럼 메모리를 수 GB씩 잡아먹는 코딩 에이전트 대신, Rust로 만든 초경량(~8MB RAM) 코딩 에이전트 Zerostack이 공개됐다. 저사양 환경에서도 쓸 수 있고, 직접 만든 유사 프로젝트들과 비교 토론이 활발하게 이뤄지고 있다.

• Δ-Mem: Efficient Online Memory for Large Language Models

  LLM의 컨텍스트 윈도우를 늘리지 않고도 과거 정보를 효율적으로 기억할 수 있는 경량 메모리 모듈 δ-mem을 제안한 논문. 모델 자체를 바꾸거나 파인튜닝 없이 기존 LLM에 붙여서 장기 기억 성능을 높일 수 있어 에이전트 시스템 개발자에게 관심을 끌고 있다.

• Show HN: Needle: We Distilled Gemini Tool Calling into a 26M Model

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

• Show HN: Agentic interface for mainframes and COBOL

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

• Show HN: Statewright – Visual state machines that make AI agents reliable

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

Related Resources

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