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

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

가장 성공적인 Claude Code 배포 사례들은 구성(configurations), 도구(tooling), 그리고 조직 구조(org structure) 전반에 걸쳐 인식 가능한 일련의 패턴들을 공유합니다. 이 기사는 기업 규모에서 Claude Code를 사용하여 구축하는 엔지니어링 조직을 위한 모범 사례를 다루는 새로운 시리즈인 'Claude Code at scale'의 일부입니다.

Claude Code는 수백만 줄 규모의 모노레포(monorepos), 수십 년 된 레거시 시스템(legacy systems), 수십 개의 저장소(repositories)에 걸친 분산 아키텍처(distributed architectures), 그리고 수천 명의 개발자가 있는 조직의 프로덕션 환경에서 실행되고 있습니다. 이러한 환경은 모든 하위 디렉터리마다 빌드 명령어가 다르거나, 공유된 루트(root) 없이 폴더 전체에 레거시 코드가 퍼져 있는 경우처럼, 더 작고 단순한 코드베이스에서는 나타나지 않는 도전 과제들을 제시합니다.

이 기사는 대규모 환경에서 Claude Code의 성공적인 도입을 이끌어낸 우리가 관찰한 패턴들을 다룹니다. 우리는

AI 코딩 도구들은 전체 코드베이스를 임베딩 (Embedding)하고 쿼리 (Query) 시점에 관련 청크 (Chunk)를 검색하는 RAG (Retrieval-Augmented Generation) 기반 검색에 의존했습니다. 대규모 환경에서는 이러한 시스템이 실패할 수 있는데, 이는 임베딩 파이프라인 (Embedding pipeline)이 활발하게 움직이는 엔지니어링 팀의 속도를 따라잡지 못할 수 있기 때문입니다. 개발자가 인덱스 (Index)에 쿼리를 보낼 때쯤이면, 해당 인덱스는 며칠 전, 몇 주 전, 혹은 심지어 몇 시간 전의 코드베이스 상태를 반영하고 있습니다. 그러면 검색 결과로 팀이 2주 전에 이름을 변경한 함수를 반환하거나, 지난 스프린트 (Sprint)에서 삭제된 모듈을 참조하게 되며, 이 중 어느 것이 최신 상태가 아닌지에 대한 어떠한 표시도 제공하지 않습니다.

에이전틱 검색 (Agentic search)은 이러한 실패 모드 (Failure modes)를 방지합니다. 수천 명의 엔지니어가 새로운 코드를 커밋 (Commit)하는 동안 유지 관리해야 할 임베딩 파이프라인이나 중앙 집중식 인덱스가 존재하지 않기 때문입니다. 각 개발자의 인스턴스 (Instance)는 라이브 (Live) 코드베이스를 바탕으로 작동합니다.

하지만 이 접근 방식에는 트레이드오프 (Tradeoff)가 있습니다. Claude가 어디를 찾아봐야 할지 알 수 있을 만큼 충분한 시작 컨텍스트 (Starting context)를 가질 때 가장 잘 작동한다는 점입니다. 이는 Claude의 탐색 (Navigation) 품질이 코드베이스가 얼마나 잘 설정되어 있는지, 즉 CLAUDE.md 파일과 스킬 (Skills)을 통해 컨텍스트를 어떻게 계층화하느냐에 따라 결정됨을 의미합니다. 만약 10억 줄 규모의 코드베이스 전체에서 모호한 패턴의 모든 사례를 찾아달라고 요청한다면, 작업이 시작되기도 전에 컨텍스트 윈도우 (Context window) 제한에 부딪히게 될 것입니다. 코드베이스 설정에 투자하는 팀이 더 나은 결과를 얻습니다.

모델만큼이나 하네스 (Harness)도 중요합니다

Claude Code에 대한 가장 흔한 오해 중 하나는 그 능력이 오로지 사용된 모델에 의해서만 정의된다는 것입니다. 팀들은 모델의 벤치마크 (Benchmarks)와 테스트 과제에서의 성능에만 집중합니다. 하지만 실제로 모델을 중심으로 구축된 생태계, 즉 하네스 (Harness)가 모델 단독 성능보다 Claude Code의 성능을 더 크게 결정합니다.

하네스는 다섯 가지 확장 지점인 CLAUDE.md 파일, 훅 (Hooks), 스킬 (Skills), 플러그인 (Plugins), 그리고 MCP 서버 (MCP servers)로 구성되며, 각 지점은 서로 다른 기능을 수행합니다. 각 레이어는 이전 단계의 결과물 위에 구축되므로, 팀이 이를 구축하는 순서가 중요합니다. 여기에 LSP 통합 (LSP integrations)과 서브에이전트 (Subagents)라는 두 가지 추가 기능이 더해져 설정을 완성합니다. 아래에서는 각 구성 요소와 기능이 어떤 역할을 하는지 설명합니다:

CLAUDE.md 파일이 가장 우선입니다. 이 파일들은 Claude가 매 세션 시작 시 자동으로 읽어들이는 컨텍스트 (Context) 파일입니다. 루트 (Root) 파일은 전체적인 그림을 보여주고, 하위 디렉터리 파일들은 로컬 컨벤션 (Local conventions)을 보여줍니다. 이 파일들은 Claude가 어떤 작업이든 잘 수행하는 데 필요한 코드베이스 지식을 제공합니다. 작업 내용과 관계없이 매 세션마다 로드되기 때문에, 광범위하게 적용되는 내용에 집중하여 유지해야 성능 저하를 방지할 수 있습니다.

훅 (Hooks)은 설정을 스스로 개선할 수 있게 만듭니다. 대부분의 팀은 훅을 Claude가 잘못된 행동을 하지 못하게 막는 스크립트로 생각하지만, 더 가치 있는 용도는 지속적인 개선입니다. 중지 훅 (Stop hook)은 세션 중에 일어난 일을 되돌아보고, 컨텍스트가 신선할 때 CLAUDE.md 업데이트를 제안할 수 있습니다. 시작 훅 (Start hook)은 팀별 컨텍스트를 동적으로 로드하여, 모든 개발자가 수동 설정 없이도 자신의 모듈에 맞는 올바른 설정을 갖출 수 있게 합니다. 린팅 (Linting)이나 포매팅 (Formatting)과 같은 자동화된 체크의 경우, 훅은 규칙을 결정론적 (Deterministically)으로 강제하며 Claude가 지침을 기억하기를 기다리는 것보다 더 일관된 결과를 만들어냅니다.

스킬 (Skills)은 모든 세션을 비대하게 만들지 않으면서도 필요한 전문 지식을 온디맨드 (On-demand)로 사용할 수 있게 합니다. 수십 가지의 작업 유형이 있는 대규모 코드베이스에서는 모든 전문 지식이 모든 세션에 존재할 필요는 없습니다. 스킬은 점진적 공개 (Progressive disclosure)를 통해 이 문제를 해결하며, 컨텍스트 공간을 차지할 수 있는 전문화된 워크플로와 도메인 지식을 작업이 요구될 때만 로드하도록 오프로딩 (Offloading)합니다. 예를 들어, 보안 리뷰 (Security review) 스킬은 Claude가 코드의 취약점을 평가할 때 로드되며, 문서 처리 (Document processing) 스킬은 코드 변경이 발생하여 문서를 업데이트해야 할 때 로드됩니다.

스킬은 특정 경로로 범위를 제한 (Scoped)할 수도 있어 코드베이스의 관련 부분에서만 활성화되도록 할 수 있습니다. 결제 서비스를 담당하는 팀은 배포 (Deployment) 스킬을 해당 디렉터리에 바인딩할 수 있으므로, 누군가가 모노레포 (Monorepo)의 다른 곳에서 작업할 때는 절대 자동으로 로드되지 않습니다.

플러그인 (Plugins)은 검증된 방식을 전파합니다. 대규모 코드베이스 (Codebase)의 한 가지 과제는 훌륭한 설정들이 특정 집단 내에서만 공유되는 '부족주의 (Tribal)' 현상에 머물 수 있다는 점입니다. 플러그인은 스킬 (Skills), 훅 (Hooks), 그리고 MCP 설정들을 하나의 설치 가능한 패키지로 묶어줍니다. 따라서 새로운 엔지니어가 입사 첫날 해당 플러그인을 설치하면, 이미 Claude를 사용해 온 사람들과 동일한 컨텍스트 (Context)와 역량을 즉시 갖게 됩니다. 플러그인 업데이트는 관리형 마켓플레이스 (Managed marketplaces)를 통해 조직 전체에 배포될 수 있습니다.

예를 들어, 저희가 협업하는 한 대형 유통 기업은 비즈니스 분석가들이 워크플로우를 벗어나지 않고도 성과 데이터를 추출할 수 있도록 Claude를 내부 분석 플랫폼에 연결하는 스킬을 구축했습니다. 그들은 이를 비즈니스 부서에 광범위하게 배포하기 전에 플러그인 형태로 먼저 배포했습니다.

언어 서버 프로토콜 (Language Server Protocol, LSP) 통합은 개발자가 IDE에서 사용하는 것과 동일한 탐색 기능을 Claude에게 제공합니다. 대부분의 대규모 코드베이스용 IDE에는 이미 LSP가 실행되고 있으며, 이는 "정의로 이동 (Go to definition)" 및 "모든 참조 찾기 (Find all references)" 기능을 지원합니다. 이를 Claude에게 노출하면 심볼 (Symbol) 수준의 정밀도를 제공할 수 있습니다. 즉, 함수 호출을 따라 정의로 이동하고, 파일 전반에 걸쳐 참조를 추적하며, 서로 다른 언어에서 이름이 동일한 함수들을 구분할 수 있게 됩니다. LSP가 없다면 Claude는 텍스트 기반의 패턴 매칭 (Pattern-matching)을 수행하게 되어 잘못된 심볼을 선택할 수 있습니다. 저희가 협업한 한 엔터프라이즈 소프트웨어 기업은 Claude Code를 배포하기 전, 특히 대규모 환경에서 C 및 C++ 탐색의 신뢰성을 확보하기 위해 조직 전체에 LSP 통합을 먼저 적용했습니다. 다중 언어 코드베이스의 경우, 이는 가장 가치 있는 투자 중 하나입니다.

MCP 서버는 모든 것을 확장합니다. MCP 서버는 Claude가 직접 접근할 수 없는 내부 도구, 데이터 소스, 그리고 API에 연결되는 방식입니다. 가장 정교한 팀들은 구조화된 검색 (Structured search)을 Claude가 직접 호출할 수 있는 도구로 노출하는 MCP 서버를 구축했습니다. 다른 팀들은 Claude를 내부 문서, 티켓팅 시스템, 또는 분석 플랫폼에 연결합니다.

Subagents는 탐색 (exploration)과 편집 (editing)을 분리합니다. Subagent는 자체적인 컨텍스트 윈도우 (context window)를 가진 격리된 Claude 인스턴스로, 작업을 전달받아 수행한 뒤 최종 결과만을 부모 (parent)에게 반환합니다. 하네스 (harness)가 갖춰지면, 일부 팀들은 읽기 전용 (read-only) Subagent를 실행하여 서브시스템을 매핑하고 그 결과를 파일에 기록하게 한 뒤, 메인 에이전트 (main agent)가 전체 그림을 파악한 상태에서 편집하도록 합니다.

아래 표는 각 구성 요소가 무엇을 하는지, 언제 로드되는지, 그리고 각 요소에서 흔히 발생하는 실수들을 요약한 것입니다:

구성 요소	정의	로드 시점	최적의 용도	흔한 혼동 사항
CLAUDE.md	Claude가 자동으로 읽는 컨텍스트 파일 (context file)	매 세션마다	프로젝트별 컨벤션 (conventions), 코드베이스 지식	스킬 (skill)에 속해야 할 재사용 가능한 전문 지식을 여기에 사용하는 것
Skills	특정 작업 유형을 위한 패키지화된 지침 (instructions)	관련 시점에 요청 시 (on demand)	세션 및 프로젝트 전반에 걸친 재사용 가능한 전문 지식	모든 것을 CLAUDE.md에 로드하는 것
Plugins	번들링된 Skills, 훅 (hooks), MCP 설정 (configs)	설정 후 항상 사용 가능	조직 전체에 작동하는 설정을 배포하는 것	잘 구축된 설정을 특정 팀 내의 지식 (tribal knowledge)으로만 남겨두는 것
Language server protocol (LSP)*	언어별 서버를 통한 실시간 코드 인텔리전스 (code intelligence)	설정 후 항상 사용 가능	타입이 지정된 언어 (typed languages)에서의 심볼 레벨 (symbol-level) 탐색 및 자동 오류 탐지	이것이 자동으로 이루어진다고 가정하는 것
MCP servers	외부 도구 및 데이터와의 연결	설정 후 항상 사용 가능	Claude가 접근할 수 없는 내부 도구에 대한 접근 권한 부여	기본 사항이 작동하기 전에 MCP 연결을 구축하는 것
Subagents*	특정 작업을 위한 별도의 Claude 인스턴스	호출 시	탐색과 편집의 분리, 병렬 작업	동일한 세션에서 탐색과 편집을 동시에 실행하는 것

*LSP는 플러그인 (plugin) 레이어를 통해 접근합니다. Subagents는 설정된 확장 포인트 (extension point)라기보다는 위임 (delegation) 기능입니다.

성공적인 배포 사례에서 나타난 세 가지 구성 패턴

대규모 코드베이스를 위한 Claude Code의 구성 방식은 해당 코드베이스가 어떻게 구조화되어 있는지에 따라 크게 달라집니다. 그럼에도 불구하고, 우리가 관찰한 배포 사례 전반에서 세 가지 패턴이 일관되게 나타났습니다.

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

대규모 코드베이스에서 Claude가 도움을 줄 수 있는 능력은 적절한 컨텍스트 (context)를 찾는 능력에 의해 제한됩니다. 모든 세션에 너무 많은 컨텍스트를 로드하면 성능이 저하되는 반면, 컨텍스트가 너무 적으면 Claude는 앞을 보지 못한 채 탐색하게 됩니다. 가장 효과적인 배포 사례들은 Claude가 코드베이스를 읽기 쉽게 만드는 데 사전에 투자합니다. 몇 가지 패턴이 일관되게 나타납니다:

CLAUDE.md 파일을 가볍고 계층적으로 유지하기. Claude는 코드베이스를 이동하면서 이 파일들을 가산적 (additively)으로 로드합니다. 즉, 전체적인 그림을 위한 루트 (root) 파일과 로컬 컨벤션 (local conventions)을 위한 하위 디렉터리 파일이 존재합니다. 루트 파일에는 포인터 (pointers)와 중요한 주의 사항 (critical gotchas)만을 포함해야 하며, 그 외의 모든 것은 노이즈 (noise)로 변질됩니다.

리포지토리 루트가 아닌 하위 디렉터리에서 초기화하기. Claude는 작업과 실제로 관련이 있는 코드베이스 부분으로 범위 (scope)가 지정되었을 때 가장 잘 작동합니다. 모노레포 (monorepos)에서는 도구들이 흔히 루트 접근 권한을 가정하기 때문에 이것이 직관에 어긋난다고 느껴질 수 있지만, Claude는 디렉터리 트리를 자동으로 거슬러 올라가며 경로상에서 발견되는 모든 CLAUDE.md 파일을 로드하므로 루트 레벨의 컨텍스트가 결코 유실되지 않습니다.

하위 디렉터리별로 테스트 및 린트 (lint) 명령의 범위 지정하기. Claude가 단 하나의 서비스만 변경했을 때 전체 테스트 세트를 실행하면 타임아웃 (timeout)이 발생하고 무관한 출력값에 컨텍스트를 낭비하게 됩니다. 하위 디렉터리 레벨의 CLAUDE.md 파일에는 해당 코드베이스 부분에 적용되는 명령어를 명시해야 합니다. 이는 각 디렉터리가 고유한 테스트 및 빌드 명령어를 갖는 서비스 지향적 (service-oriented) 코드베이스에서 잘 작동합니다. 디렉터리 간 의존성이 깊은 컴파일 언어 기반의 모노레포에서는 하위 디렉터리별 범위 지정이 더 어려울 수 있으며, 프로젝트별 빌드 설정이 필요할 수 있습니다.

.ignore 파일을 사용하여 생성된 파일(generated files), 빌드 아티팩트(build artifacts) 및 제3자 코드(third-party code)를 제외합니다. .claude/settings.json에 permissions.deny 규칙을 커밋하면 제외 설정이 버전 관리(version-controlled)되므로, 팀의 모든 개발자가 직접 설정할 필요 없이 동일한 노이즈 감소(noise reduction) 효과를 얻을 수 있습니다. 일부 코드베이스에서는 생성된 파일 자체가 개발 작업의 대상이 되기도 합니다. 코드 생성기(code generators)를 다루는 개발자는 팀의 나머지 인원에게 영향을 주지 않으면서 자신의 로컬 설정에서 프로젝트 수준의 제외 설정을 재정의(override)할 수 있습니다.