대규모 코드베이스에서 Claude Code 작동 방식 - 하네스, CLAUDE.md, Skill, LSP 모범 사례
목차
개요
Anthropic이 Claude Code가 수백만 라인 모노레포, 레거시 시스템, 분산 아키텍처에서 작동하는 방식과 모범 사례를 공식 블로그에 정리했다. 핵심 메시지는 배포 성공이 모델 능력 단독이 아니라 코드베이스 구조와 구성 방식에 달려 있다는 것이다.
이 글은 Claude Code의 검색 메커니즘, 5가지 하네스 확장 포인트, 그리고 조직 차원의 도입 패턴을 다룬다. 한국 커뮤니티에서는 이 가이드의 적용 현실성에 대해 활발한 논쟁이 진행되고 있다.
Claude Code가 코드베이스를 탐색하는 방식
Claude Code는 RAG 기반 도구들과 달리 전체 코드베이스를 임베딩하지 않는다. 대신 에이전트형 검색을 사용한다. 파일시스템을 순회하고, 파일을 읽고, 참조를 따라가는 로컬 작업이다.
이 접근법은 오래된 인덱스를 피할 수 있다. 각 개발자의 인스턴스는 임베딩이 아닌 라이브 코드베이스에서 작동하므로 항상 최신 정보를 보장한다. 대신 전략적인 컨텍스트 설정이 필수다.
한국 커뮤니티 비판 중 일부는 이 방식이 실제 엔지니어 워크플로우와 다르다고 지적한다. 엔지니어는 IDE 인덱싱(LSP), 근육 기억, 코드 회상을 사용하는데, Claude Code가 변경되지 않은 코드를 반복적으로 순회하면 토큰 낭비가 심하다는 우려다.
하네스의 5가지 확장 포인트
모델 단독을 넘어 하네스가 성능에 결정적 영향을 미친다. Anthropic은 다섯 가지 확장 포인트를 제시한다.
CLAUDE.md 파일
매 세션마다 로드되는 컨텍스트 파일이다. 루트 파일은 큰 그림 컨텍스트를 담고, 하위 디렉터리 파일은 로컬 컨벤션을 담는다.
| 위치 | 역할 |
|---|---|
| 저장소 루트 | 프로젝트 전체 컨텍스트 |
| 하위 디렉터리 | 해당 영역의 로컬 컨벤션 |
| 사용자 글로벌 | 개인 선호도와 워크플로우 |
성능 저하를 피하려면 파일을 가볍고 집중되게 유지해야 한다. 모든 세션에서 로드되기 때문에 무겁게 두면 토큰 비용이 누적된다.
Skill과 Plugin
훅(Hook)은 이벤트 트리거로, 일관된 동작을 자동화하고 결정론적 규칙(린팅, 포매팅)을 강제한다. 스킬(Skill)은 필요할 때만 로드되는 전문 지식이다. 컨텍스트 비대화를 방지하며 특정 디렉터리 경로로 범위를 한정할 수 있다.
플러그인(Plugin)은 항상 사용 가능한 형태로 스킬, 훅, 구성을 설치 가능한 패키지로 묶는다. 팀 전반 설정 표준화와 관리되는 마켓플레이스를 통한 배포가 가능하다.
LSP(Language Server Protocol)는 심볼 수준 탐색 정밀도를 제공한다. 정확한 “go to definition”과 참조 추적을 가능하게 하고, 대규모 코드베이스에서 텍스트 매칭 오류를 방지한다.
추가로 MCP 서버는 Claude를 내부 도구, API, 데이터 소스에 연결하며, 서브에이전트는 별도 인스턴스가 탐색 후 결과를 부모에게 반환한다.
세 가지 구성 패턴
대규모 코드베이스 적용에는 세 가지 운영 패턴이 핵심이다. 구성, 유지보수, 조직적 책임이라는 축으로 나뉜다.
규모에 맞게 코드베이스를 탐색 가능하게 만들기는 첫 번째 패턴이다. CLAUDE.md 파일을 계층적이고 가볍게 유지하고, 저장소 루트가 아닌 하위 디렉터리에서 초기화한다. 테스트와 린트 명령을 디렉터리별로 범위 지정하고, .claude/settings.json을 사용해 생성된 파일을 버전 컨트롤 가능한 형태로 제외한다.
| 권장 사항 | 효과 |
|---|---|
| 비전통적 구조에 코드베이스 맵 작성 | 탐색 시간 단축 |
| LSP 서버 배포 | 심볼 기반 검색 정확도 향상 |
| 생성 파일 제외 설정 | 컨텍스트 노이즈 감소 |
구성을 능동적으로 유지보수하기가 두 번째 패턴이다. 모델이 진화함에 따라 구성도 검토가 필요하다. 이전 모델을 위한 규칙이 새 버전을 제약할 수 있다. 주요 모델 출시 이후 특히 3-6개월마다 의미 있는 리뷰를 진행한다.
조직적 소유권 할당이 세 번째 패턴이다. 성공적인 롤아웃은 광범위 접근 전에 인프라 투자를 집중한다. 전담 팀이 도구를 연결해 Claude가 워크플로우에 즉시 맞도록 한다. 인프라 우선 접근으로 첫날부터 생산성을 경험하게 한다.
시작하기 체크리스트
Anthropic이 제시한 도입 순서다.
| 단계 | 작업 |
|---|---|
| 1 | CLAUDE.md 계층 구조 수립 |
| 2 | 주력 언어용 LSP 구성 |
| 3 | 내부 도구 기본 MCP 연결 설정 |
| 4 | 스킬과 플러그인 승인 프로세스 정의 |
| 5 | 구성 관리 담당자/팀 지정 |
| 6 | 초기 플러그인 배포 전략 작성 |
| 7 | AI 생성 코드 코드리뷰 요건 수립 |
규제 산업에서는 승인된 스킬/플러그인 목록, 필수 코드 리뷰, 제한된 초기 접근, 교차 기능 워킹그룹(엔지니어링, 보안, 거버넌스) 같은 거버넌스 고려 사항이 추가된다.
결론
Claude Code의 대규모 코드베이스 성공은 모델 선택보다 하네스 구성에 달려 있다. 얇고 계층적인 CLAUDE.md, 적시 로드 스킬, LSP 통합, MCP 연결, 그리고 명확한 거버넌스가 핵심이다. 한국 커뮤니티의 회의적 시각(컨텍스트 낭비, 지시 무시율, 인덱싱 비효율)은 여전히 유효한 비판이지만, 동시에 명확한 소유권 모델과 구체적 예시에 대한 수요가 크다는 것도 드러난다. 이 글은 “조직적으로 어떻게 배포할 것인가”에 대한 첫 공식 가이드라는 점에서 의미가 있다.