3줄 요약
- Anthropic Applied AI 팀이 자사 Claude Code를 엔터프라이즈급 코드베이스에 배포하며 관찰한 모범 사례를 정리한 글이다. 새 시리즈 Claude Code at scale의 1편이고, 후속 글이 예고되어 있다.
- 핵심 진단은 두 가지다 — Claude Code는 RAG 인덱스 없이 라이브 코드베이스를 직접 탐색하므로 인덱스 stale 문제가 구조적으로 없으나, 시작 컨텍스트가 부실하면 컨텍스트 윈도우가 먼저 터진다. 그리고 성능을 좌우하는 것은 모델이 아니라 그 주변에 쌓이는 harness(CLAUDE.md, hooks, skills, plugins, MCP, LSP, subagents)다.
- 처방은 세 가지다. (1) 코드베이스를 Claude가 읽을 수 있게 만들고, (2) 모델 진화에 맞춰 CLAUDE.md를 적극 정비하고, (3) 전담 오너십(최소 DRI)을 둔다. 규제 산업은 cross-functional working group으로 거버넌스를 일찍 정의한다.
Agentic search — 라이브 코드베이스 직접 탐색
Claude Code는 소프트웨어 엔지니어가 그러하듯 코드베이스를 탐색한다 — 파일 시스템을 traverse하고, 파일을 읽고, grep으로 필요한 것을 찾고, 레퍼런스를 따라 코드베이스를 가로지른다. 개발자의 로컬 머신에서 동작하며, 서버에 인덱스를 빌드·유지·업로드할 필요가 없다.
RAG 기반 AI 코딩 도구는 코드베이스 전체를 임베딩한 뒤 질의 시점에 관련 chunk를 retrieval하는 방식이다. 대규모에서 이 패턴은 깨진다 — 임베딩 파이프라인이 활성 팀의 커밋 속도를 따라잡지 못하기 때문이다. 개발자가 인덱스에 질의하는 순간, 인덱스는 몇 주·며칠·몇 시간 전의 코드베이스를 비추고 있다. retrieval은 2주 전에 리네임된 함수나 직전 스프린트에서 삭제된 모듈을 반환하면서, 그것이 outdated라는 표시조차 함께 주지 않는다.
Agentic search는 이 failure mode를 구조적으로 피한다. 유지해야 할 임베딩 파이프라인도, 중앙화된 인덱스도 없다. 각 개발자 인스턴스가 라이브 코드베이스에서 작동한다.
다만 트레이드오프가 있다 — Claude가 어디를 봐야 할지 알 만큼의 시작 컨텍스트가 있을 때 가장 잘 작동한다. 즉 탐색 품질은 코드베이스가 얼마나 잘 셋업되어 있느냐 — CLAUDE.md와 skill로 컨텍스트를 어떻게 층층이 쌓아두었느냐 — 에 의해 결정된다. 십억 줄 코드베이스에서 모호한 패턴의 모든 인스턴스를 찾으라고 하면, 작업이 시작되기도 전에 컨텍스트 윈도우 한계에 부딪힌다. 코드베이스 셋업에 투자한 팀이 더 나은 결과를 본다.
Harness — 모델보다 중요한 생태계
Claude Code에 관한 가장 흔한 오해 중 하나는 그 능력이 사용된 모델만으로 정해진다는 생각이다. 팀들은 모델의 벤치마크와 테스트 작업에서의 성능에 집중한다. 실제로는 모델 주변에 만들어진 생태계 — harness — 가 모델 단독보다 Claude Code의 성능을 더 많이 결정한다.
harness는 5개의 확장 지점 — CLAUDE.md, hooks, skills, plugins, MCP servers — 으로 만들어진다. 각 층이 그 앞의 층 위에 빌드되므로 쌓는 순서가 중요하다. 여기에 2개의 보조 능력 — LSP integration, subagents — 가 더해진다.
CLAUDE.md가 먼저 온다
이것은 Claude가 모든 세션 시작 시 자동으로 읽는 컨텍스트 파일이다. 루트 파일은 큰 그림을, 서브디렉토리 파일은 로컬 컨벤션을 담는다. 모든 세션에 무조건 로드되므로, 광범위하게 적용되는 내용에만 초점을 맞춰야 성능 드래그가 되지 않는다.
Hooks가 셋업을 self-improving하게 만든다
대부분의 팀은 hooks를 Claude의 잘못된 행동을 막는 스크립트로 본다. 더 가치 있는 용도는 지속적 개선이다. stop hook은 세션 중 일어난 일을 회고하며 컨텍스트가 신선한 동안 CLAUDE.md 업데이트를 제안할 수 있다. start hook은 팀별 컨텍스트를 동적으로 로드해, 매번 수동 설정 없이도 개발자가 자기 모듈에 맞는 셋업을 받게 한다. 린팅·포매팅 같은 자동 검사에서는 hooks가 결정론적이라 Claude가 지시를 ‘기억’하는 것보다 일관성이 높다.
Skills는 적시 적소의 전문성을 살린다
수십 가지 작업 유형이 있는 대규모 코드베이스에서, 모든 전문성이 매 세션에 들어 있을 필요는 없다. Skills는 progressive disclosure로 이를 해결한다 — 컨텍스트 공간을 놓고 경쟁할 전문 워크플로우와 도메인 지식을 빼두었다가 작업이 요구할 때만 로드한다. 예를 들어 보안 리뷰 skill은 Claude가 코드를 취약점 관점에서 평가할 때 로드되고, 문서 처리 skill은 코드 변경 후 문서를 갱신해야 할 때 로드된다.
Skills는 경로 스코핑도 가능하므로 코드베이스의 관련 영역에서만 자동 활성화된다. 결제 서비스를 소유한 팀이 자기들 deploy skill을 해당 디렉토리에 묶어 두면, 같은 모노레포의 다른 곳에서 일할 때는 자동 로드되지 않는다.
Plugins는 통하는 셋업을 배포한다
대규모 코드베이스의 문제 하나는 좋은 셋업이 부족적(tribal)으로 머문다는 점이다. 플러그인은 skills, hooks, MCP 구성을 하나의 설치 가능한 패키지로 묶어, 새 엔지니어가 첫날 그것을 설치하는 순간 기존 사용자와 동일한 컨텍스트·능력을 갖게 한다. managed marketplace를 통해 플러그인 업데이트를 조직 전체에 배포할 수 있다.
예시: Anthropic과 일한 한 대형 리테일 조직은 비즈니스 분석가가 자기 워크플로우를 떠나지 않고 성과 데이터를 끌어올 수 있도록 내부 애널리틱스 플랫폼에 Claude를 연결하는 skill을 만들었다. 광범위 롤아웃 전에 플러그인 형태로 비즈니스에 배포했다.
LSP integration은 IDE 수준의 탐색력을 준다
대부분의 대규모 코드베이스 IDE는 이미 LSP를 돌려 ‘go to definition’과 ‘find all references’를 제공한다. 이를 Claude에 노출하면 심볼 단위 정확도가 생긴다 — 함수 호출을 정의로 따라가고, 파일을 가로지르며 레퍼런스를 추적하고, 다른 언어의 동일 이름 함수를 구분한다. LSP 없이 Claude는 텍스트 패턴 매칭에 의존하므로 잘못된 심볼에 도달할 수 있다. Anthropic과 일한 한 엔터프라이즈 소프트웨어 회사는 Claude Code 롤아웃 전에 LSP integration을 조직 전반에 배포했다 — C와 C++ 탐색을 대규모에서도 신뢰할 수 있게 만들기 위해서다. 다언어 코드베이스에서는 가장 ROI가 높은 투자 중 하나다.
MCP servers는 모든 것을 확장한다
MCP 서버는 Claude를 그 외 방법으로는 닿을 수 없는 사내 도구·데이터 소스·API에 연결하는 방식이다. 가장 정교한 팀은 structured search를 Claude가 직접 호출할 수 있는 도구로 노출하는 MCP 서버를 만들었다. 다른 팀들은 사내 문서, 티켓팅 시스템, 애널리틱스 플랫폼에 Claude를 연결한다.
Subagents는 탐색과 편집을 분리한다
서브에이전트는 자기 컨텍스트 윈도우를 가진 격리된 Claude 인스턴스로, 작업을 받아 수행한 뒤 최종 결과만 부모에게 돌려준다. harness가 자리 잡고 나면, 일부 팀은 read-only 서브에이전트를 띄워 서브시스템을 매핑하고 결과를 파일로 쓰게 한 뒤, 메인 에이전트가 그 전체 그림으로 편집하게 한다.
Component Overview Table
| Component | What it is | When it loads | Best for | Common confusion |
|---|---|---|---|---|
| CLAUDE.md | Claude가 자동으로 읽는 컨텍스트 파일 | 모든 세션 | 프로젝트별 컨벤션, 코드베이스 지식 | skill에 들어가야 할 재사용 가능한 전문성을 여기에 넣기 |
| Hooks | 핵심 시점에 실행되는 스크립트 | 이벤트로 트리거 | 일관된 동작 자동화, 세션 학습 캡처 | 자동 실행되어야 할 것을 프롬프트에 넣기 |
| Skills | 특정 작업 유형용 패키지 명령 | 관련 시 on-demand | 세션·프로젝트 전반의 재사용 전문성 | 대신 모든 것을 CLAUDE.md에 몰아넣기 |
| Plugins | 묶인 skills, hooks, MCP 구성 | 구성 후 항상 사용 가능 | 조직 전반에 작동하는 셋업 배포 | 좋은 셋업을 부족적으로 두기 |
| LSP | 언어별 서버를 통한 실시간 코드 인텔리전스 | 구성 후 항상 사용 가능 | 타입 언어의 심볼 단위 탐색과 자동 오류 감지 | 자동이라고 가정하기 |
| MCP servers | 외부 도구·데이터 연결 | 구성 후 항상 사용 가능 | 다른 방법으로는 닿을 수 없는 사내 도구를 Claude에 노출 | 기본기가 작동하기 전에 MCP 연결부터 만들기 |
| Subagents | 특정 작업용 별도 Claude 인스턴스 | 호출 시 | 탐색과 편집의 분리, 병렬 작업 | 같은 세션에서 탐색과 편집을 함께 돌리기 |
성공적 배포의 세 가지 패턴
대규모 코드베이스용 Claude Code 구성은 코드베이스 구조에 크게 의존한다. 그럼에도 Anthropic이 관찰한 배포에서 세 가지 패턴이 일관되게 나타났다.
패턴 1 — 코드베이스의 가독성 확보
Claude가 대규모 코드베이스에서 도움이 될 수 있는 능력은 적절한 컨텍스트를 찾는 능력에 의해 제한된다. 매 세션에 너무 많은 컨텍스트를 로드하면 성능이 떨어지고, 너무 적으면 Claude가 눈을 가리고 탐색하게 된다. 가장 효과적인 배포는 코드베이스를 Claude가 읽을 수 있게(legible) 만드는 데 선투자한다.
- CLAUDE.md를 lean & layered하게 유지. Claude는 코드베이스를 이동하며 이들을 가산적으로 로드한다 — 루트 파일은 큰 그림, 서브디렉토리 파일은 로컬 컨벤션. 루트 파일은 포인터와 critical gotcha만 담는다. 그 외는 노이즈로 흘러든다.
- 레포 루트가 아니라 서브디렉토리에서 초기화. Claude는 작업과 실제로 관련된 코드베이스 영역에 스코핑되어 있을 때 가장 잘 동작한다. 모노레포에서는 직관에 반할 수 있지만 — 툴링이 종종 루트 접근을 가정하기 때문에 — Claude는 자동으로 디렉토리 트리를 거슬러 올라가며 만나는 모든 CLAUDE.md를 로드하므로 루트 컨텍스트는 결코 잃지 않는다.
- test·lint 명령을 서브디렉토리별로 스코핑. Claude가 한 서비스만 바꿨는데 전체 스위트를 돌리면 타임아웃이 나고 무관한 출력에 컨텍스트가 낭비된다. 서브디렉토리 CLAUDE.md는 그 영역에 적용되는 명령을 명시해야 한다. 서비스 지향 코드베이스에서 잘 통한다. 컴파일 언어 모노레포에서 깊은 cross-directory 의존성이 있으면 서브디렉토리 단위 스코핑이 어려워 프로젝트별 빌드 구성이 필요할 수 있다.
.claudeignore로 generated/build/3rd-party 코드 제외..claude/settings.json의permissions.deny규칙을 커밋하면 제외가 버전 컨트롤되므로, 팀의 모든 개발자가 동일한 노이즈 감소를 별도 설정 없이 얻는다. generated 파일 자체가 개발 대상인 코드베이스에서는 개발자가 로컬 설정에서 프로젝트 수준 제외를 오버라이드할 수 있다.- 디렉토리 구조가 일을 하지 못하면 코드베이스 맵을 둔다. 코드가 관례적 디렉토리 구조로 정리되지 않은 조직에서는, 레포 루트에 각 최상위 폴더와 한 줄 설명을 적은 가벼운 마크다운 파일이 Claude에게 파일을 열기 전 스캔할 수 있는 목차가 된다. 최상위 폴더가 수백 개인 코드베이스에서는 계층 접근이 잘 통한다 — 루트 파일은 최상위 구조만, 서브디렉토리 CLAUDE.md가 다음 단계 디테일을 담는다. 더 단순한 경우에는 특정 파일·디렉토리를
@-mention하는 것으로 같은 일을 할 수 있다. - LSP 서버를 띄워 Claude가 문자열이 아니라 심볼로 검색하게 한다. 대규모 코드베이스에서 흔한 함수명에 grep을 걸면 수천 건의 매치가 나오고, 어느 것이 중요한지 알아내려고 파일을 여느라 컨텍스트가 탄다. LSP는 같은 심볼을 가리키는 레퍼런스만 반환하므로 필터링이 Claude가 읽기 전에 일어난다.
한 가지 단서: 계층적 CLAUDE.md 접근조차 깨지는 edge case가 있다 — 수십만 폴더·수백만 파일의 코드베이스, 비-git VCS 위의 레거시 시스템. 이들의 도전은 시리즈의 후속 글에서 다룬다고 본문은 예고한다.
패턴 2 — 모델 진화에 맞춰 CLAUDE.md 적극 정비
모델이 진화하면, 현재 모델용으로 쓴 지시가 미래 모델에는 역작용할 수 있다. Claude가 과거에 어려워하던 패턴을 우회하기 위해 적은 CLAUDE.md 규칙은, 다음 모델이 출시되면 불필요해지거나 오히려 제약이 된다. 예를 들어 “모든 리팩터를 단일 파일 변경으로 쪼개라"는 CLAUDE.md 규칙은 이전 모델이 트랙을 유지하는 데 도움이 됐을 수 있지만, 새 모델이 잘 다루는 cross-file 편집을 막아 버린다.
특정 모델 한계를 보상하려고 만든 skill과 hook도 — 모델 추론이든 Claude Code 자체 툴링이든 — 그 한계가 사라지면 오버헤드가 된다. Perforce 코드베이스에서 p4 edit을 강제하려고 파일 쓰기를 가로채던 hook은 Claude Code가 네이티브 Perforce 모드를 추가한 뒤 redundant가 됐다.
팀은 3~6개월마다 의미 있는 구성 재검토를 기대해야 하며, 메이저 모델 릴리스 후 성능이 plateau된 것처럼 느껴질 때도 즉시 한다.
패턴 3 — Claude Code 관리·도입에 오너십을 배정
기술 구성만으로는 도입이 일어나지 않는다. 잘 굴러간 조직은 조직 레이어에도 투자했다.
가장 빠르게 퍼진 롤아웃은 광범위한 접근 이전에 dedicated infra 투자가 있었다. 작은 팀 — 때로는 한 사람 — 이 툴링을 미리 깔아두어, 개발자가 처음 Claude를 만질 때 이미 개발자 워크플로우에 들어맞도록 했다. 한 회사에서는 엔지니어 둘이 첫날에 사용 가능한 plugin과 MCP 스위트를 만들어두었다. 또 다른 회사에서는 AI 코딩 도구 관리에 집중하는 한 팀 전체가 롤아웃이 시작되기 전에 인프라를 갖춰두었다. 두 경우 모두 개발자의 첫 경험이 짜증스럽지 않고 생산적이었고, 도입은 거기서부터 퍼졌다.
오늘 이 일을 하는 팀은 developer experience나 developer productivity 산하에 있는 경향이 있다 — 보통 새 엔지니어 온보딩과 개발자 툴링을 맡는 기능이다. 여러 조직에서 떠오르는 새 역할은 agent manager다 — Claude Code 생태계 관리에 전담하는 PM·엔지니어 하이브리드 직무. 전담 팀이 없는 조직이라면 최소 viable 버전은 DRI 한 명이다 — Claude Code 구성, 설정·권한 정책·플러그인 마켓플레이스·CLAUDE.md 컨벤션에 대한 결정 권한과 그것들을 최신으로 유지할 책임을 가진 사람.
bottoms-up 도입은 열정을 만들지만, 통하는 것을 중앙화할 누군가가 없으면 파편화된다. 표준화된 CLAUDE.md 계층이나 큐레이션된 skill·plugin 세트 같은 Claude Code 컨벤션을 모으고 전도할 개인이나 팀이 있어야 한다. 그 일이 없으면 지식은 부족적으로 머무르고 도입은 plateau한다.
거버넌스 — 대조직과 규제 산업
큰 조직, 특히 규제 산업에서는 거버넌스 질문이 일찍 나온다 — 어떤 skill과 plugin이 사용 가능한지 누가 통제하는가, 수천 명의 엔지니어가 같은 것을 독립적으로 다시 만드는 것을 어떻게 막는가, AI 생성 코드가 사람 생성 코드와 같은 리뷰 프로세스를 거치도록 어떻게 보장하는가. 본문은 이 문제들에 일찍 대응하기 위해 승인된 skill 세트, 필수 코드 리뷰 프로세스, 제한된 초기 접근에서 시작해 신뢰가 쌓이며 확장하라고 권한다.
Anthropic이 관찰한 가장 매끄러운 배포는 엔지니어링, 정보보안, 거버넌스 대표자를 모아 요구사항을 함께 정의하고 롤아웃 로드맵을 만드는 cross-functional working group을 일찍 세운 조직에서 나왔다.
적용 한계
Claude Code는 conventional software engineering 환경 — 엔지니어가 코드베이스의 주된 기여자, 레포는 Git, 코드는 표준 디렉토리 구조 — 을 가정해 설계됐다. 대부분의 대규모 코드베이스가 이 틀에 맞지만, 비전통적 셋업은 추가 구성 작업을 요구한다 — 큰 바이너리 자산을 가진 게임 엔진, 비관례적 버전 컨트롤 환경, 비엔지니어가 코드베이스에 기여하는 경우 등. 본문은 이런 케이스에 대해 “여기서는 판단이 코드베이스·툴링·조직 고유의 요구사항에 맞춰져야 하고, Anthropic Applied AI 팀이 직접 작업하는 영역"이라고 마무리한다.
가장 흥미로운 지점
이 글에서 가장 흥미로운 것은 모델 진화에 맞춰 CLAUDE.md를 정비하라는 패턴 2다. 다른 두 패턴(가독성 확보, 오너십 배정)은 어느 정도 직관적이지만, 패턴 2는 한 단계 더 들어간 통찰을 담고 있다 — 현재 모델의 한계를 보상하려고 쌓아둔 보조 인프라(skill·hook·CLAUDE.md 규칙)는 모델이 좋아지면 부채로 전환된다.
이건 단순한 obsolescence가 아니다. 모델은 아무 일도 하지 않았는데, 어제까지의 자산이 오늘의 제약이 된다. “리팩터를 단일 파일로 쪼개라"는 CLAUDE.md 규칙이 cross-file 편집을 잘 하는 새 모델을 막는 식이다. 시스템 진화에 맞춰 어제의 가드레일을 능동적으로 거둬내야 한다는 운영 원리는, AI 코딩 도구의 운영뿐 아니라 모든 자기 보강 시스템(self-improving system) 운영에 일반화될 여지가 있다고 보였다.
출처
- 발행: Anthropic Blog
- 저자: Anthropic Applied AI team (개별 바이라인 없음). Alon Krifcher, Charmaine Lee, Chris Concannon, Harsh Patel, Henrique Savelli, Jason Schwartz, Jonah Dueck, Kirby Kohlmorgen이 기여, Zoox의 Amit Navindgi가 피드백을 제공.
- 발표일: 2026-05-14
- 시리즈: Claude Code at scale (1편). 후속 글이 예고되어 있다.
- 원문: https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start
(원문은 한 장의 Component Overview Table 외에 본문 이미지가 없는 텍스트 중심 글이라 이미지는 인용하지 않았다.)