대규모 코드베이스에서 Claude Code 제대로 활용하기: 모범 사례와 시작 방법

Claude Code는 현재 수백만 줄 규모의 모노레포, 수십 년 된 레거시 시스템, 수십 개의 저장소에 걸친 분산 아키텍처, 그리고 수천 명의 개발자를 보유한 조직에서 실제 프로덕션 환경에 쓰이고 있다. 이런 환경에는 소규모의 단순한 코드베이스에서는 겪지 않는 문제들이 따른다. 서브디렉터리마다 빌드 명령어가 달라진다거나, 공통 루트 없이 여러 폴더에 레거시 코드가 흩어져 있는 경우가 그 예다.

이 글은 대규모 환경에서 Claude Code를 성공적으로 도입한 사례들에서 발견한 패턴을 정리한 것이다. 여기서 '대규모 코드베이스'는 다양한 형태를 아우른다. 수백만 줄 규모의 모노레포, 수십 년에 걸쳐 구축된 레거시 시스템, 별도 저장소에 분산된 수십 개의 마이크로서비스, 혹은 이들의 조합이 모두 해당된다. AI 코딩 도구와 어울리지 않는다고 여겨지는 언어들, 예컨대 C, C++, C#, Java, PHP로 작성된 코드베이스도 포함된다. (이런 경우에도 Claude Code는 대부분의 팀이 예상하는 것보다 훨씬 잘 작동하며, 최근 모델 릴리스 이후 특히 두드러진다.) 대규모 코드베이스 도입 사례는 버전 관리 방식, 팀 구조, 누적된 개발 관행에 따라 각기 다른 형태를 띠지만, 여기서 소개하는 패턴들은 그 모든 경우에 공통적으로 적용되며, Claude Code 도입을 검토하는 팀에 좋은 출발점이 될 것이다.

Claude Code의 대규모 코드베이스 탐색 방식

Claude Code는 소프트웨어 엔지니어가 코드를 탐색하는 방식 그대로 코드베이스를 파악한다. 파일 시스템을 순회하고, 파일을 읽고, grep으로 필요한 내용을 정확히 찾아내며, 코드베이스 전반에서 참조를 따라간다. 개발자의 로컬 머신에서 직접 실행되며, 코드베이스 인덱스를 별도로 구축하거나 유지·관리하거나 서버에 업로드할 필요가 없다.

기존 AI 코딩 도구들은 RAG(검색 증강 생성) 기반 검색에 의존했다. 코드베이스 전체를 임베딩한 뒤 쿼리 시점에 관련 청크를 가져오는 방식이다. 하지만 대규모 환경에서는 이 방식이 무너지기 쉽다. 임베딩 파이프라인이 활발하게 작업하는 엔지니어링 팀의 변경 속도를 따라가지 못하기 때문이다. 개발자가 인덱스를 조회할 시점에는 이미 며칠, 몇 주, 심지어 몇 시간 전 상태의 코드베이스를 반영하고 있다. 그 결과 2주 전에 이름이 바뀐 함수가 검색 결과로 반환되거나, 지난 스프린트에서 삭제된 모듈이 참조로 등장하는데, 어느 쪽이든 최신 정보가 아니라는 표시조차 없다.

에이전트 방식의 검색은 이런 실패 유형을 근본적으로 피한다. 수천 명의 엔지니어가 코드를 커밋하더라도 임베딩 파이프라인이나 중앙 집중식 인덱스를 따로 유지할 필요가 없다. 각 개발자의 인스턴스는 실시간 코드베이스를 직접 바라본다.

다만 이 방식에는 트레이드오프가 있다. Claude가 어디를 봐야 할지 파악할 수 있을 만큼 충분한 초기 컨텍스트가 주어질 때 가장 잘 작동한다. 즉, CLAUDE.md 파일과 스킬(skill)로 컨텍스트를 단계적으로 쌓아 코드베이스를 얼마나 잘 구성해두느냐에 따라 Claude의 탐색 품질이 결정된다. 수십억 줄 규모의 코드베이스에서 모호한 패턴을 모두 찾아달라고 하면, 작업을 시작하기도 전에 컨텍스트 윈도우 한계에 부딪힌다. 코드베이스 설정에 미리 투자한 팀이 더 나은 결과를 얻는 이유가 여기에 있다.

모델만큼 중요한 것, 하네스

Claude Code에 대한 가장 흔한 오해 중 하나는 성능이 오직 사용하는 모델에 의해 결정된다는 것이다. 팀들은 모델의 벤치마크와 테스트 태스크 성능에 주목한다. 하지만 실제로는 모델을 둘러싼 생태계, 즉 하네스(harness)가 모델 단독보다 Claude Code의 성능을 더 크게 좌우한다.

하네스는 다섯 가지 확장 포인트인 CLAUDE.md 파일, 훅(hook), 스킬, 플러그인, MCP 서버로 구성된다. 각각 역할이 다르며, 각 레이어가 이전 레이어 위에 쌓이는 구조이므로 팀이 이를 구축하는 순서가 중요하다. 여기에 LSP(언어 서버 프로토콜) 통합과 서브에이전트(subagent)라는 두 가지 추가 기능이 설정을 완성한다. 아래에서 각 구성 요소와 기능의 역할을 설명한다.

CLAUDE.md 파일이 첫 번째다. 매 세션이 시작될 때 Claude가 자동으로 읽는 컨텍스트 파일로, 루트 파일은 전체 그림을 담고 서브디렉터리 파일은 해당 영역의 로컬 규칙을 담는다. Claude가 어떤 작업이든 제대로 수행하는 데 필요한 코드베이스 지식을 제공한다. 태스크와 무관하게 모든 세션에서 로드되므로, 범용적으로 적용되는 내용에만 집중해야 성능 저하를 막을 수 있다.

훅은 설정을 자기 개선하는 구조로 만든다. 대부분의 팀은 훅을 Claude가 잘못된 동작을 하지 못하도록 막는 스크립트 정도로 생각하지만, 더 가치 있는 활용은 지속적인 개선이다. 스탑 훅(stop hook)은 세션 중에 일어난 일을 돌아보고, 컨텍스트가 생생할 때 CLAUDE.md 업데이트를 제안할 수 있다. 스타트 훅(start hook)은 팀별 컨텍스트를 동적으로 로드해서, 개발자가 수동으로 설정하지 않아도 자신이 담당하는 모듈에 맞는 환경을 자동으로 갖출 수 있게 한다. 린팅, 포매팅 같은 자동화 검사에서 훅은 규칙을 결정론적으로 적용하므로, Claude에게 지침을 기억하도록 요청하는 것보다 훨씬 일관된 결과를 낸다.

스킬은 매 세션을 무겁게 만들지 않으면서 필요한 전문 지식을 필요할 때 꺼낼 수 있게 한다. 수십 가지 태스크 유형이 존재하는 대규모 코드베이스에서는 모든 전문 지식을 매 세션에 올려둘 필요가 없다. 스킬은 점진적 공개(progressive disclosure) 방식으로 이 문제를 해결한다. 컨텍스트 공간을 놓고 경쟁할 수 있는 특화된 워크플로와 도메인 지식을 별도로 분리해두고, 해당 태스크가 필요할 때만 로드한다. 예를 들어 보안 리뷰 스킬은 코드의 취약점을 검토할 때 로드되고, 문서 처리 스킬은 코드 변경 후 문서를 업데이트해야 할 때 로드된다.

스킬은 특정 경로에 범위를 한정할 수도 있어, 코드베이스의 해당 부분에서만 활성화된다. 결제 서비스를 담당하는 팀은 배포 스킬을 해당 디렉터리에 연결해두면, 다른 팀원이 모노레포의 다른 곳에서 작업할 때는 자동으로 로드되지 않는다.

플러그인은 효과적인 설정을 조직 전체에 퍼뜨린다. 대규모 코드베이스에서 흔히 겪는 문제 중 하나는 잘 구성된 설정이 특정 팀에만 머무는 것이다. 플러그인은 스킬, 훅, MCP 설정을 하나의 설치 가능한 패키지로 묶어준다. 신규 엔지니어가 첫날 해당 플러그인을 설치하면, 기존에 Claude를 써온 팀원들과 동일한 컨텍스트와 기능을 즉시 갖출 수 있다. 플러그인 업데이트는 관리형 마켓플레이스(managed marketplace)를 통해 조직 전체에 배포할 수 있다.

예를 들어, 우리와 함께 일하는 한 대형 리테일 기업은 비즈니스 애널리스트들이 워크플로를 벗어나지 않고 성과 데이터를 직접 조회할 수 있도록 내부 분석 플랫폼과 Claude를 연결하는 스킬을 만들었다. 이를 플러그인으로 배포한 뒤 전사 롤아웃을 시작했다.

언어 서버 프로토콜(LSP) 통합은 Claude에게 개발자가 IDE에서 쓰는 것과 동일한 코드 탐색 능력을 부여한다. 대규모 코드베이스용 IDE 대부분에는 이미 LSP가 실행되어 "정의로 이동"이나 "모든 참조 찾기" 기능을 제공하고 있다. 이를 Claude에게 노출하면 심벌 수준의 정밀도가 생긴다. 함수 호출에서 정의로 따라가고, 파일 간 참조를 추적하며, 언어가 달라도 이름이 같은 함수를 구별할 수 있다. LSP 없이는 Claude가 텍스트 패턴 매칭에 의존해 엉뚱한 심벌에 도달할 수 있다. 우리가 함께 일한 한 엔터프라이즈 소프트웨어 기업은 Claude Code 롤아웃 전에 LSP 통합을 전사적으로 먼저 배포했는데, 이는 특히 C와 C++ 탐색을 대규모 환경에서 신뢰할 수 있게 만들기 위해서였다. 여러 언어를 혼용하는 코드베이스라면 LSP 통합은 가장 투자 대비 효과가 높은 작업 중 하나다.

MCP 서버는 모든 것을 확장한다. MCP 서버는 Claude가 자체적으로 접근할 수 없는 내부 도구, 데이터 소스, API에 연결하는 수단이다. 가장 정교하게 활용하는 팀들은 구조화된 검색을 Claude가 직접 호출할 수 있는 도구로 노출하는 MCP 서버를 구축했다. 또 다른 팀들은 Claude를 내부 문서, 티켓 시스템, 분석 플랫폼과 연결해 활용한다.

서브에이전트는 탐색과 편집을 분리한다. 서브에이전트는 자체 컨텍스트 윈도우를 가진 독립된 Claude 인스턴스로, 태스크를 받아 작업을 완료한 뒤 최종 결과만 부모 에이전트에 돌려준다. 하네스가 갖춰지고 나면, 일부 팀은 읽기 전용 서브에이전트를 띄워 서브시스템을 파악하고 결과를 파일에 기록한 다음, 메인 에이전트가 전체 그림을 바탕으로 편집을 진행하는 방식을 활용한다.

아래 표는 각 구성 요소의 역할, 로드 시점, 그리고 자주 보이는 실수를 정리한 것이다.

성공적인 도입 사례에서 발견한 세 가지 설정 패턴

대규모 코드베이스에서 Claude Code를 어떻게 설정하느냐는 코드베이스의 구조에 크게 달려 있다. 그럼에도 우리가 관찰한 도입 사례들에서는 세 가지 패턴이 공통적으로 나타났다.

대규모 환경에서 코드베이스를 탐색 가능하게 만들기

대규모 코드베이스에서 Claude가 도움을 줄 수 있는 수준은, 올바른 컨텍스트를 얼마나 잘 찾아낼 수 있느냐에 달려 있다. 매 세션에 너무 많은 컨텍스트를 로드하면 성능이 떨어지고, 너무 적으면 Claude가 방향을 잃고 헤매게 된다. 가장 효과적인 도입 사례들은 처음부터 코드베이스를 Claude가 이해하기 쉬운 구조로 만드는 데 투자했다. 공통적으로 나타난 패턴은 다음과 같다.

• CLAUDE.md 파일을 간결하고 계층적으로 유지하기. Claude는 코드베이스를 이동하면서 파일을 누적해 로드한다. 루트 파일은 전체 그림을, 서브디렉터리 파일은 로컬 규칙을 담는다. 루트 파일에는 핵심 포인터와 반드시 알아야 할 주의사항만 담아야 한다. 그 외의 내용은 잡음이 된다.
• 저장소 루트가 아닌 서브디렉터리에서 시작하기. Claude는 실제 태스크와 관련 있는 코드베이스 영역으로 범위가 좁혀졌을 때 가장 잘 작동한다. 모노레포에서는 툴링이 루트 접근을 전제하는 경우가 많아 직관에 어긋나는 느낌이 들 수 있지만, Claude는 디렉터리 트리를 자동으로 거슬러 올라가며 경로상의 모든 CLAUDE.md 파일을 로드하므로, 루트 수준의 컨텍스트는 항상 유지된다.
• 테스트 및 린트 명령어를 서브디렉터리별로 지정하기. Claude가 서비스 하나를 수정했는데 전체 테스트 스위트를 실행하면 타임아웃이 발생하고, 관련 없는 출력으로 컨텍스트를 낭비하게 된다. 서브디렉터리 수준의 CLAUDE.md 파일에 해당 코드베이스 영역에 적용되는 명령어를 명시해두면 이를 방지할 수 있다. 이 방식은 디렉터리별로 자체적인 테스트·빌드 명령어를 가진 서비스 지향 코드베이스에 잘 맞는다. 반면 디렉터리 간 의존성이 깊은 컴파일 언어 모노레포에서는 서브디렉터리별 범위 지정이 어렵고, 프로젝트별 빌드 설정이 추가로 필요할 수 있다.
• .ignore 파일로 생성된 파일, 빌드 산출물, 서드파티 코드 제외하기. permissions.deny 규칙을 .claude/settings.json에 커밋해 버전 관리하면, 팀의 모든 개발자가 개별 설정 없이 동일하게 노이즈를 줄인 환경을 갖게 된다. 일부 코드베이스에서는 생성된 파일 자체가 개발 대상인 경우도 있다. 코드 생성기를 다루는 개발자는 로컬 설정에서 프로젝트 수준의 제외 규칙을 재정의할 수 있으며, 나머지 팀원에게는 영향을 주지 않는다.
• 디렉터리 구조만으로 파악이 어려울 때 코드베이스 맵 만들기. 코드가 일반적인 디렉터리 구조에 통합되어 있지 않은 조직이라면, 저장소 루트에 각 최상위 폴더와 그 안에 무엇이 있는지를 한 줄로 설명하는 가벼운 마크다운 파일을 두는 것이 효과적이다. Claude가 파일을 열기 전에 훑어볼 수 있는 목차 역할을 한다. 최상위 폴더가 수백 개에 달하는 코드베이스라면 계층적 접근이 효과적이다. 루트 파일은 가장 상위 구조만 기술하고, 서브디렉터리 CLAUDE.md 파일이 다음 단계의 세부 정보를 온디맨드로 제공하는 방식이다. 단순한 경우에는 @-멘션으로 Claude가 참조해야 할 특정 파일이나 디렉터리를 직접 지정하는 것으로도 같은 효과를 낼 수 있다.
• LSP 서버를 실행해 Claude가 문자열이 아닌 심벌로 검색하게 하기. 대규모 코드베이스에서 흔한 함수 이름을 grep으로 검색하면 수천 건이 반환되고, Claude는 어떤 것이 관련 있는지 파악하기 위해 파일을 열다가 컨텍스트를 소모한다. LSP는 동일한 심벌을 가리키는 참조만 반환하므로, Claude가 파일을 읽기 전에 필터링이 완료된다. 설정하려면 사용 언어에 맞는 코드 인텔리전스 플러그인과 해당 언어 서버 바이너리를 설치해야 하며, 사용 가능한 플러그인과 문제 해결 방법은 Claude Code 문서에 안내되어 있다.

한 가지 주의할 점: 계층적 CLAUDE.md 방식도 한계에 부딪히는 엣지 케이스가 있다. 수십만 개의 폴더와 수백만 개의 파일을 가진 코드베이스나, Git이 아닌 버전 관리 시스템을 사용하는 레거시 시스템이 그 예다. 이에 대한 과제는 이 시리즈의 향후 편에서 다룰 예정이다.

모델 발전에 맞춰 CLAUDE.md 파일을 지속적으로 관리하기

모델이 발전하면, 이전 모델에 맞게 작성된 지침이 새 모델에서는 오히려 역효과를 낼 수 있다. Claude가 과거에 어려움을 겪던 패턴을 안내하던 CLAUDE.md 파일이, 다음 모델이 출시될 때는 불필요해지거나 오히려 제약이 될 수 있다. 예를 들어 모든 리팩터링을 단일 파일 변경으로 나누도록 지시하는 규칙은 이전 모델이 작업 흐름을 유지하는 데 도움이 됐을 수 있지만, 파일 간 협력 편집을 잘 처리하는 새 모델에서는 오히려 그 능력을 막는 결과를 낳는다.

특정 모델의 한계를 보완하기 위해 만든 스킬과 훅도, 모델의 추론 능력이든 Claude Code 자체 툴링이든 해당 한계가 사라지고 나면 부담만 남는다. 예를 들어 Perforce 코드베이스에서 파일 쓰기를 가로채 p4 edit를 강제하던 훅은, Claude Code에 네이티브 Perforce 모드가 추가된 이후 불필요해졌다.

팀은 3~6개월마다 주기적으로 설정을 점검해야 하지만, 주요 모델 릴리스 이후 성능이 정체된 느낌이 들 때도 점검하는 것이 좋다.

Claude Code 관리와 도입의 오너십 지정하기

기술적인 설정만으로는 도입이 확산되지 않는다. 성공한 조직들은 조직 운영 측면에도 함께 투자했다.

가장 빠르게 확산된 롤아웃 사례들은 공통적으로, 전사 접근 허용 전에 인프라에 먼저 투자했다. 소수의 팀, 때로는 단 한 명이 툴링을 구성해서, 개발자들이 처음 사용할 때부터 Claude가 자신들의 워크플로에 자연스럽게 맞아 들어오게 했다. 한 기업에서는 엔지니어 몇 명이 첫날부터 쓸 수 있는 플러그인과 MCP 스위트를 구축해뒀다. 또 다른 기업에서는 AI 코딩 도구 관리를 전담하는 팀이 롤아웃 시작 전에 인프라를 이미 갖춰놓았다. 두 경우 모두 개발자들의 첫 경험이 답답함이 아닌 생산성으로 시작됐고, 도입이 자연스럽게 퍼져나갔다.

이 역할을 맡는 팀은 대체로 개발자 경험(DX) 또는 개발자 생산성 조직 아래에 위치하는데, 이 조직이 통상 신규 엔지니어 온보딩과 개발 툴 구축을 담당하기 때문이다. 여러 조직에서 에이전트 매니저(agent manager)라는 역할이 새롭게 생겨나고 있다. Claude Code 생태계를 전담 관리하는 PM과 엔지니어의 역할을 겸하는 포지션이다. 전담 팀을 꾸리기 어려운 조직이라면, 최소한의 형태로 DRI(Directly Responsible Individual)를 두는 방법이 있다. Claude Code 설정 전반의 오너십을 가진 한 명이 설정 방향, 권한 정책, 플러그인 마켓플레이스, CLAUDE.md 규칙에 대한 결정권을 갖고, 이를 최신 상태로 유지하는 책임을 지는 것이다.

바텀업 방식의 도입은 구성원의 열의를 끌어내지만, 이를 한데 모아줄 주체가 없으면 분산된다. 표준화된 CLAUDE.md 계층 구조나 검증된 스킬·플러그인 모음처럼, 올바른 Claude Code 규칙을 취합하고 전파하는 역할을 맡는 개인 또는 팀이 반드시 필요하다. 이 작업 없이는 노하우가 특정 팀에만 머물고 도입이 정체될 수밖에 없다.

규제 산업을 포함한 대규모 조직에서는 거버넌스 문제가 일찍 등장한다. 어떤 스킬과 플러그인을 허용할지 누가 결정하는가, 수천 명의 엔지니어가 똑같은 것을 각자 만드는 상황을 어떻게 막을 것인가, AI가 생성한 코드가 사람이 작성한 코드와 동일한 리뷰 프로세스를 거치도록 어떻게 보장할 것인가 같은 질문들이다. 이를 초기에 해결하려면, 승인된 스킬의 명확한 집합을 정의하고, 필수 코드 리뷰 프로세스를 갖추며, 초기 접근 범위를 제한하는 것에서 시작해 신뢰가 쌓이는 만큼 점차 확대하는 방식을 권장한다.

가장 원활하게 진행된 도입 사례들은 엔지니어링, 정보 보안, 거버넌스 담당자들로 구성된 크로스 펑셔널(cross-functional) 워킹 그룹을 초기에 구성해, 요구사항을 함께 정의하고 롤아웃 로드맵을 함께 수립한 조직에서 나왔다.

이 패턴을 우리 조직에 적용하기

Claude Code는 엔지니어가 코드베이스의 주된 기여자이고, Git을 사용하며, 코드가 표준적인 디렉터리 구조를 따르는 일반적인 소프트웨어 엔지니어링 환경을 전제로 설계되었다. 대부분의 대규모 코드베이스가 이 범주에 들어맞지만, 대용량 바이너리 에셋이 포함된 게임 엔진, 비관례적인 버전 관리 환경, 비엔지니어가 코드베이스에 기여하는 구조처럼 비표준적인 설정에서는 추가적인 설정 작업이 필요하다. 이 글의 가이던스는 표준 환경을 전제로 하며, 여기서 설명한 패턴들은 우리 고객사 대다수에서 실제로 효과를 발휘했다. 남은 복잡한 부분은 각 코드베이스, 툴링, 조직의 특수한 상황에 맞는 판단이 필요하며, 그 지점에서 Anthropic의 Applied AI 팀이 엔지니어링 팀과 직접 협력해 이 패턴들을 조직별 요구사항으로 구체화하는 작업을 함께 한다.

Claude Code for Enterprise로 시작하기.

‍

감사의 말: 대규모 환경에서 Claude Code를 도입한 경험을 공유해 준 Anthropic Applied AI 팀의 Alon Krifcher, Charmaine Lee, Chris Concannon, Harsh Patel, Henrique Savelli, Jason Schwartz, Jonah Dueck, Kirby Kohlmorgen에게 특별히 감사드린다. 또한 이 글에 피드백을 준 Zoox의 Amit Navindgi에게도 감사를 전한다.

‍