가장 성공적인 Claude Code 배포 사례들은 설정, 도구, 조직 구조 전반에 걸쳐 식별 가능한 패턴을 공유한다. 이 글은 Claude Code at scale 시리즈의 일부로, 엔터프라이즈 규모에서 Claude Code를 도입하는 엔지니어링 조직을 위한 모범 사례를 다룬다.
Claude Code는 수백만 줄 규모의 모노레포, 수십 년에 걸쳐 만들어진 레거시 시스템, 여러 저장소에 걸친 분산 아키텍처, 그리고 개발자가 수천 명에 이르는 조직의 프로덕션 환경에서 실행되고 있다. 이런 환경은 작고 단순한 코드베이스에서는 보기 힘든 문제들을 안고 있다. 빌드 명령어가 하위 디렉터리마다 제각각이거나, 공통 루트도 없이 여러 폴더에 흩어져 있는 레거시 코드가 그런 예다.
이 글은 우리가 관찰해 온, 대규모 환경에서 Claude Code 도입을 성공으로 이끌었던 패턴들을 정리한 것이다. 여기서 말하는 "대규모 코드베이스"는 폭넓은 배포 형태를 가리킨다. 수백만 줄짜리 모노레포, 수십 년에 걸쳐 쌓아 올린 레거시 시스템, 별도 저장소에 흩어진 수십 개의 마이크로서비스, 혹은 이들이 뒤섞인 형태가 모두 여기 해당한다. C, C++, C#, Java, PHP 같은, AI 코딩 도구와는 잘 묶이지 않던 언어로 돌아가는 코드베이스도 포함된다. (특히 최근 모델 릴리스 이후로는, 이런 경우에도 Claude Code가 팀들의 예상을 훨씬 뛰어넘는 성능을 낸다.) 모든 대규모 코드베이스 배포는 각자의 버전 관리 방식과 팀 구조, 그리고 누적된 관행에 따라 모양이 다르지만, 여기 정리한 패턴들은 그 차이를 가로질러 일반화되며 Claude Code 도입을 고민하는 팀에게 좋은 출발점이 된다.
Claude Code가 대규모 코드베이스를 탐색하는 방식
Claude Code는 사람 엔지니어가 하는 방식으로 코드베이스를 돌아다닌다. 파일 시스템을 순회하고, 파일을 읽고, grep으로 필요한 부분을 정확히 찾아내고, 참조를 따라 코드베이스 곳곳을 옮겨 다닌다. 개발자의 로컬 머신에서 동작하며, 코드베이스 인덱스를 미리 빌드하거나 유지보수하거나 서버에 업로드할 필요도 없다.
RAG 기반 AI 코딩 도구는 코드베이스 전체를 임베딩한 뒤 질의 시점에 관련 청크를 검색하는 식으로 작동한다. 규모가 커지면 이런 시스템은 종종 무너진다. 임베딩 파이프라인이 활발하게 움직이는 엔지니어링 팀의 속도를 따라잡지 못하기 때문이다. 개발자가 인덱스를 조회할 무렵이면 그 인덱스는 몇 주 전, 며칠 전, 심지어 몇 시간 전 상태의 코드베이스를 비추고 있다. 그 결과 검색은 2주 전에 이름이 바뀐 함수를 그대로 돌려주거나, 지난 스프린트에 삭제된 모듈을 참조하면서도 이게 더 이상 유효하지 않다는 신호를 전혀 주지 않는다.
에이전틱 검색은 이런 실패 양상을 피해 간다. 수천 명의 엔지니어가 새 코드를 커밋하는 동안 유지해야 할 임베딩 파이프라인이나 중앙 집중 인덱스가 아예 없다. 각 개발자의 인스턴스가 살아 있는 코드베이스 위에서 직접 동작한다.
다만 트레이드오프가 있다. 이 방식은 Claude가 어디를 봐야 할지 알 수 있을 만큼 출발선의 컨텍스트가 충분할 때 가장 잘 작동한다. 즉, Claude의 탐색 품질은 CLAUDE.md 파일과 스킬을 통해 컨텍스트를 어떻게 층층이 쌓아 두었는지, 그러니까 코드베이스를 얼마나 잘 셋업해 두었는지에 달려 있다. 10억 줄짜리 코드베이스에서 모호한 패턴의 모든 인스턴스를 찾으라고 시키면, 작업이 본격적으로 시작되기도 전에 컨텍스트 윈도우 한계에 부딪힐 것이다. 코드베이스 셋업에 투자한 팀들이 더 나은 결과를 본다.
하니스(harness)는 모델만큼 중요하다
Claude Code 같은 도구를 보면, 그 역량이 사용된 모델 하나로 결정된다고 가정하기 쉽다. 팀들은 모델 벤치마크와 테스트 과제에서의 성능에 주목한다. 실제로는 모델 주위에 만들어진 생태계, 즉 하니스(harness) 가 모델 단독보다 Claude Code의 성능을 더 크게 좌우한다.
하니스는 다섯 개의 확장 지점으로 구성된다. CLAUDE.md 파일, 훅(hook), 스킬, 플러그인, MCP 서버다. 각각 다른 역할을 하며, 팀이 이들을 쌓아 올리는 순서가 중요하다. 각 층이 그 아래 층 위에서 의미를 갖기 때문이다. 추가로 LSP 통합과 서브에이전트라는 두 가지 역량이 셋업을 완성한다. 아래에서 각 구성 요소와 역량이 어떤 일을 하는지 설명한다.
CLAUDE.md 파일이 첫 단추다. 매 세션 시작 시 Claude가 자동으로 읽어들이는 컨텍스트 파일이다. 루트 파일은 큰 그림을, 하위 디렉터리 파일은 그 지역의 관행을 담는다. 이 파일은 Claude가 무엇이든 잘 해내기 위해 필요한 코드베이스 지식을 제공한다. 작업 종류와 무관하게 매 세션마다 로드되므로, 두루두루 적용되는 내용에만 집중해야 한다. 그렇지 않으면 성능을 끌어내리는 짐이 된다.
훅(Hooks)은 셋업을 스스로 개선하게 만든다. 많은 팀이 훅을 Claude가 잘못된 행동을 하지 못하게 막는 스크립트로만 생각한다. 그러나 더 가치 있는 쓰임은 지속적 개선이다. 스톱(stop) 훅은 세션이 끝날 때 그 안에서 무슨 일이 있었는지 되짚어 보고, 맥락이 아직 신선할 때 CLAUDE.md 업데이트를 제안할 수 있다. 스타트(start) 훅은 팀별 컨텍스트를 동적으로 로드해서, 모듈을 처음 만지는 개발자라도 별도 설정 없이 자신에게 맞는 셋업을 받게 만든다. 린팅이나 포매팅 같은 자동 검사에서는, 훅이 규칙을 결정론적으로 강제하기 때문에 Claude가 지시를 기억해 주기를 바라는 것보다 훨씬 일관된 결과를 낸다.
스킬(Skills)은 적절한 전문 지식을 매 세션을 부풀리지 않으면서 필요할 때만 꺼내 쓸 수 있게 해 준다. 작업 유형이 수십 가지인 대규모 코드베이스에서 모든 전문성이 매 세션마다 미리 들어가 있을 필요는 없다. 스킬은 점진적 공개(progressive disclosure) 방식으로 이를 해결한다. 컨텍스트 공간을 두고 다투었을 특수 워크플로와 도메인 지식을 따로 빼 두었다가, 작업이 필요로 할 때만 불러온다. 예컨대 보안 리뷰 스킬은 Claude가 취약점 점검을 할 때 로드되고, 문서 처리 스킬은 코드 변경에 따른 문서 갱신 작업이 생겼을 때 로드되는 식이다.
스킬은 특정 경로에 묶어서 코드베이스의 해당 영역에서만 작동하도록 한정할 수도 있다. 결제 서비스를 담당하는 팀이 자신들의 배포 스킬을 그 디렉터리에 바인딩해 두면, 모노레포의 다른 곳에서 일할 때는 자동으로 끌어오지 않는다.
플러그인(Plugins)은 잘 작동하는 셋업을 퍼뜨린다. 대규모 코드베이스의 한 가지 골치는 좋은 셋업이 끼리끼리만 공유되는 비공식 지식으로 머무르는 점이다. 플러그인은 스킬과 훅, MCP 설정을 하나의 설치 가능한 패키지로 묶기 때문에, 새로 합류한 엔지니어가 첫날 플러그인을 설치하기만 하면 기존 사용자들과 똑같은 컨텍스트와 역량을 곧바로 손에 쥐게 된다. 플러그인 업데이트는 관리형 마켓플레이스를 통해 조직 전체에 배포할 수 있다.
예컨대 우리가 함께 일했던 한 대형 리테일 조직은 Claude를 내부 분석 플랫폼과 연결해, 비즈니스 분석가가 워크플로를 벗어나지 않고도 성과 데이터를 끌어다 쓸 수 있게 해 주는 스킬을 만들었다. 이들은 비즈니스 부문 전체로 본격 확산하기 전에 이 스킬을 플러그인 형태로 배포했다.
언어 서버 프로토콜(LSP) 통합은 Claude에게 개발자가 IDE에서 쓰는 것과 같은 탐색 능력을 부여한다. 큰 코드베이스용 IDE는 보통 이미 LSP가 돌고 있어 "정의로 이동"이나 "모든 참조 찾기" 기능을 제공한다. 이를 Claude에게도 노출해 주면 심볼 단위의 정밀도를 얻는다. 함수 호출을 따라가서 정확히 어떤 정의가 해당 호출과 연결되어 있는지 알 수 있는데, grep은 텍스트만 본 채 엉뚱한 심볼에 도달하기 십상이다. 우리가 함께 일했던 한 엔터프라이즈 소프트웨어 회사는 Claude Code를 본격 배포하기에 앞서, 특히 C와 C++ 탐색을 대규모로 안정적으로 만들기 위해 조직 전체에 LSP 통합을 먼저 깔았다. 다언어 코드베이스에서는 이것이 가장 투자 대비 효과가 큰 항목 중 하나다.
MCP 서버는 모든 것을 확장한다. MCP 서버는 Claude가 다른 방법으로는 닿을 수 없는 내부 도구, 데이터 소스, API와 연결되는 통로다. 가장 정교한 팀들은 구조화된 검색 기능을 Claude가 직접 호출할 수 있는 툴로 노출하는 MCP 서버를 만들어 두었다. 다른 팀들은 Claude를 사내 문서, 티켓팅 시스템, 분석 플랫폼과 연결한다.
서브에이전트(Subagents)는 탐색과 편집을 분리한다. 서브에이전트는 자체 컨텍스트 윈도우를 가진 독립된 Claude 인스턴스로, 과제를 받아 작업을 수행한 뒤 최종 결과만을 부모 에이전트에게 돌려준다. 하니스가 자리 잡고 나면, 일부 팀은 읽기 전용 서브에이전트를 띄워 하위 시스템을 매핑하게 하고 그 결과를 파일로 남긴 다음, 메인 에이전트가 그 전체 그림을 보고 편집하는 식으로 일한다.
Claude Code의 확장 계층을 한눈에.
아래 표는 각 구성 요소가 무엇인지, 언제 로드되는지, 그리고 우리가 자주 보아 온 흔한 오해를 정리한 것이다.
| 구성 요소 | 무엇인가 | 언제 로드되는가 | 가장 적합한 용도 | 흔한 혼동 |
|---|---|---|---|---|
| CLAUDE.md | Claude가 자동으로 읽는 컨텍스트 파일 | 매 세션 | 프로젝트별 관행, 코드베이스 지식 | 스킬에 속해야 할 재사용 가능한 전문성을 여기에 넣음 |
| 훅 | 주요 시점에 실행되는 스크립트 | 이벤트에 의해 트리거 | 일관된 동작 자동화, 세션 학습 캡처 | 자동으로 돌아야 할 일을 프롬프트로 처리함 |
| 스킬 | 특정 작업 유형을 위한 패키지화된 지시문 | 관련 작업이 있을 때 온디맨드로 | 세션과 프로젝트를 가로질러 재사용되는 전문성 | 모든 것을 CLAUDE.md에 우겨 넣음 |
| 플러그인 | 스킬·훅·MCP 설정을 묶은 번들 | 한번 설정해 두면 항상 사용 가능 | 잘 작동하는 셋업을 조직 전체에 배포 | 좋은 셋업이 비공식 지식으로 머무름 |
| 언어 서버 프로토콜(LSP)* | 언어별 서버를 통한 실시간 코드 인텔리전스 | 한번 설정해 두면 항상 사용 가능 | 타입 있는 언어에서 심볼 단위 탐색과 자동 오류 감지 | 자동으로 켜져 있다고 가정함 |
| MCP 서버 | 외부 도구·데이터와의 연결 | 한번 설정해 두면 항상 사용 가능 | 다른 방법으로는 닿을 수 없는 내부 도구로의 접근 부여 | 기본기가 안 잡힌 상태에서 MCP부터 만들기 시작함 |
| 서브에이전트* | 특정 과제용 별도 Claude 인스턴스 | 호출될 때 | 탐색과 편집의 분리, 병렬 작업 | 탐색과 편집을 같은 세션에서 돌림 |
| *LSP는 플러그인 계층을 통해 접근한다. 서브에이전트는 설정해 두는 확장 지점이라기보다 위임 역량에 가깝다. |
성공적인 배포에서 반복되는 세 가지 설정 패턴
대규모 코드베이스에서 Claude Code를 어떻게 설정할지는 그 코드베이스가 어떤 구조인지에 크게 좌우된다. 그럼에도 우리가 관찰한 배포 사례들에서 일관되게 나타난 세 가지 패턴이 있었다.
코드베이스를 규모와 상관없이 탐색 가능하게 만들기
대규모 코드베이스에서 Claude가 도움을 줄 수 있는 한계는, 결국 적절한 컨텍스트를 찾아낼 수 있는 능력에 의해 결정된다. 매 세션마다 컨텍스트가 너무 많이 실리면 성능이 떨어지고, 너무 적게 실리면 Claude가 깜깜이로 헤매게 된다. 가장 효과를 본 배포들은 코드베이스를 Claude가 읽기 쉬운 형태로 만드는 일에 미리 투자한다. 다음과 같은 몇 가지 패턴이 반복해서 나타난다.
- CLAUDE.md 파일은 가볍고 계층적으로 유지한다. Claude는 코드베이스를 옮겨 다니며 이 파일들을 누적해서 로드한다. 루트 파일은 큰 그림을, 하위 디렉터리 파일은 그 지역의 관행을 담는다. 루트 파일에는 포인터와 빠질 수 있는 중요한 함정만 적고, 그 외의 것은 들이지 않는다. 그렇지 않으면 노이즈로 흘러들어 간다.
- 루트가 아닌 하위 디렉터리에서 초기화한다. Claude는 작업과 실제로 관련 있는 코드베이스 영역에 범위가 좁혀져 있을 때 가장 잘 작동한다. 모노레포에서는 이게 직관에 어긋나게 느껴질 수 있다. 도구들이 흔히 루트 접근을 가정하기 때문이다. 그러나 Claude는 디렉터리 트리를 자동으로 거슬러 올라가면서 만나는 모든 CLAUDE.md 파일을 로드하므로, 루트 레벨 컨텍스트가 사라지는 일은 없다.
- 테스트와 린트 명령어는 하위 디렉터리별로 범위를 잡는다. Claude가 한 서비스만 바꿨는데도 전체 스위트를 돌리면 타임아웃이 나고, 관련 없는 출력으로 컨텍스트만 낭비한다. 하위 디렉터리 수준의 CLAUDE.md 파일에는 그 영역에 해당하는 명령어를 명시해야 한다. 디렉터리마다 자체 테스트·빌드 명령을 갖는 서비스 지향 코드베이스에 잘 맞는다. 디렉터리 간 의존이 깊은 컴파일 언어 모노레포에서는 하위 디렉터리별 범위 한정이 더 어렵고, 프로젝트별 빌드 설정이 필요할 수도 있다.
- 생성된 파일과 빌드 산출물, 서드파티 코드는
.ignore파일로 제외한다..claude/settings.json에permissions.deny규칙을 커밋해 두면 제외 항목이 버전 관리에 들어가므로, 팀의 모든 개발자가 별도 설정 없이 동일한 잡음 제거 효과를 누린다. 일부 코드베이스에서는 생성된 파일 자체가 개발의 대상이 된다. 코드 생성기를 다루는 개발자는 자신의 로컬 설정에서 프로젝트 수준의 제외 규칙을 덮어쓰면 되고, 팀의 다른 사람들에게는 영향을 주지 않는다. - 디렉터리 구조만으로 안내가 부족할 때는 코드베이스 지도를 만든다. 코드가 관례적인 디렉터리 구조로 모여 있지 않은 조직에서는, 최상위 폴더 각각에 한 줄짜리 설명을 붙인 가벼운 마크다운 파일을 저장소 루트에 두는 것만으로도 Claude에게 파일을 열기 전에 훑어볼 목차를 쥐여 주는 셈이 된다. 최상위 폴더가 수백 개에 이르는 코드베이스라면 계층화된 접근이 가장 잘 맞는다. 루트 파일은 가장 큰 단위의 구조만 묘사하고, 그다음 단계의 세부는 하위 디렉터리 CLAUDE.md 파일이 맡아 Claude가 트리를 옮겨 다닐 때 필요한 순간에 로드되도록 한다. 더 단순한 경우라면 Claude가 참조해야 할 특정 파일이나 디렉터리를 @-멘션해 주는 것만으로도 같은 효과를 낼 수 있다.
- LSP 서버를 돌려서 Claude가 문자열이 아니라 심볼로 검색하게 한다. 대규모 코드베이스에서 흔한 함수 이름을 grep으로 찾으면 매치가 수천 개씩 나오고, Claude는 어떤 것이 진짜 관련이 있는지 알아내려고 파일을 여닫는 데 컨텍스트를 다 써 버린다. LSP는 같은 심볼을 가리키는 참조만 돌려주기 때문에, Claude가 무엇이라도 읽기 전에 필터링이 끝난다. 이를 셋업하려면 해당 언어용 코드 인텔리전스 플러그인과 대응하는 언어 서버 바이너리를 설치해야 한다.
모델 지능의 진화에 맞춰 CLAUDE.md 파일을 능동적으로 유지하기
모델이 진화함에 따라, 현재 모델을 위해 작성된 지시문이 다음 모델에는 도리어 발목을 잡을 수 있다. 이전 모델이 헤매던 패턴을 잡아 주려고 만들어 둔 CLAUDE.md 규칙이, 새 모델이 등장하면 불필요해지거나 적극적으로 제약이 되기도 한다. 예를 들어 "모든 리팩토링을 단일 파일 변경 단위로 쪼개라"는 CLAUDE.md 규칙은 이전 모델이 길을 잃지 않게 도와주었을 수 있다. 그러나 같은 규칙이, 여러 파일에 걸친 조율된 편집을 잘 해내는 새 모델에게는 그 능력을 막아 버린다.
특정 모델의 한계, 즉 모델 추론의 한계든 Claude Code 자체 도구의 한계든, 그 한계를 메우려고 만든 스킬과 훅은 그 한계가 사라진 순간 불필요한 부담이 된다. 예컨대 퍼포스(Perforce) 코드베이스에서 p4 edit을 강제하려고 파일 쓰기를 가로채던 훅은, Claude Code가 네이티브 퍼포스 모드를 추가하면서 잉여가 되어 버렸다.
팀은 의미 있는 설정 리뷰를 3~6개월마다 한 번씩 한다고 잡아 두는 게 좋고, 큰 모델 릴리스 이후 성능이 정체된 것처럼 느껴질 때마다 추가로 점검해 볼 가치가 있다.
Claude Code 운영과 보급의 오너십 배치
기술적 설정만으로 채택이 굴러가지는 않는다. 제대로 해낸 조직들은 조직 차원의 층위에도 함께 투자했다.
가장 빠르게 퍼진 롤아웃은 광범위한 접근을 열기 전에 인프라 투자가 선행되어 있었다. 적은 인원, 때로는 단 한 명만으로도 미리 도구를 엮어 두어서, 개발자들이 처음 Claude를 만졌을 때 이미 자신들의 워크플로에 맞아떨어지도록 만들어 두었다. 어느 회사에서는 엔지니어 두어 명이 첫날부터 사용할 수 있는 플러그인과 MCP 묶음을 만들어 두었고, 또 다른 회사에서는 AI 코딩 도구 관리를 전담하는 팀 하나가 롤아웃이 시작되기 전에 인프라를 준비해 두었다. 두 경우 모두 개발자들의 첫 경험은 좌절스러움 대신 생산성이었고, 채택은 거기서부터 번져 나갔다.
오늘날 이 일을 맡는 팀은 보통 개발자 경험(developer experience)이나 개발자 생산성(developer productivity) 산하에 자리한다. 이 조직은 신규 엔지니어 온보딩과 개발 도구 구축을 맡는 부서다. 여러 조직에서 새로 등장한 역할이 에이전트 매니저(agent manager) 다. PM과 엔지니어를 절반씩 섞은 듯한 하이브리드 직무로, Claude Code 생태계 관리를 전담한다. 전담 팀이 없는 조직이라면 최소 단위로라도 DRI(Directly Responsible Individual)를 두어야 한다. 한 사람이 Claude Code 설정에 대한 오너십을 가지고, 설정·권한 정책·플러그인 마켓플레이스·CLAUDE.md 관행에 대해 결정을 내릴 권한과, 그것들을 최신 상태로 유지할 책임을 함께 짊어진다.
바텀업 채택은 열기를 만들어 내지만, 중심을 잡아 주는 사람이 없으면 파편화된다. 누군가, 혹은 어떤 팀이 올바른 Claude Code 관행(예컨대 표준화된 CLAUDE.md 계층 구조, 큐레이션된 스킬과 플러그인 묶음)을 모아 보급해야 한다. 그 일이 빠지면 지식은 끼리끼리 머무르고, 채택은 어느 선에서 정체된다.
대규모 조직, 특히 규제 산업에 속한 조직에서는 거버넌스 질문이 일찍 떠오른다. 어떤 스킬과 플러그인을 누구의 결정으로 사용 가능하게 할 것인가, 수천 명의 엔지니어가 각자 같은 것을 또 만드는 사태를 어떻게 막을 것인가, AI가 만든 코드가 사람이 만든 코드와 동일한 리뷰 절차를 거치도록 어떻게 보장할 것인가. 이런 문제를 일찍 다루려면, 승인된 스킬 목록과 필수 코드 리뷰 절차, 그리고 제한된 초기 접근부터 시작한 뒤 신뢰가 쌓이는 만큼 확장해 가기를 권한다.
가장 매끄러운 배포는 엔지니어링, 정보 보안, 거버넌스 대표가 모이는 범기능 워킹 그룹을 일찌감치 꾸리고, 함께 요구사항을 정의하면서 롤아웃 로드맵을 짜 둔 조직들에서 관찰되었다.
이 패턴들을 당신의 조직에 적용하기
Claude Code는 엔지니어가 코드베이스의 주된 기여자이고, 저장소는 Git을 쓰며, 코드가 표준적인 디렉터리 구조를 따르는 통상적인 소프트웨어 엔지니어링 환경을 전제로 설계되었다. 대부분의 대규모 코드베이스가 이 틀에 들어맞지만, 큰 바이너리 자산을 다루는 게임 엔진이나, 비통상적인 버전 관리 환경, 비엔지니어가 코드베이스에 기여하는 경우 같은 비전형적 셋업은 추가 설정 작업을 필요로 한다. 우리가 제시한 가이드는 통상적인 환경을 가정하며, 여기서 다룬 패턴들은 우리의 많은 고객사에서 효과를 보였다. 남은 복잡성은 당신의 코드베이스와 도구, 조직에 특화된 판단을 요구한다. 그 부분에서 Anthropic의 어플라이드 AI(Applied AI) 팀이 엔지니어링 팀과 직접 협업해 이 패턴들을 당신 조직의 구체적 요구사항으로 옮겨 낸다.
Claude Code for Enterprise와 함께 시작하세요.
감사의 말: Anthropic 어플라이드 AI 팀의 Alon Krifcher, Charmaine Lee, Chris Concannon, Harsh Patel, Henrique Savelli, Jason Schwartz, Jonah Dueck, Kirby Kohlmorgen에게 Claude Code의 대규모 배포 경험을 나눠 준 데 대해 특별한 감사를 전한다. 또한 이 글에 피드백을 준 Zoox의 Amit Navindgi에게도 감사를 전한다.