Claude Code가 수백만 줄짜리 모노레포와 수십 년 된 레거시 시스템에서 실제로 운영되고 있습니다. 그런데 같은 모델을 써도 팀마다 결과가 크게 다르다면, 차이를 만드는 건 모델이 아닐 수도 있습니다.

Anthropic이 대규모 코드베이스에서 Claude Code를 성공적으로 배포한 팀들의 공통 패턴을 공식 블로그를 통해 공개했습니다. 핵심 발견은 하나입니다. 모델의 벤치마크 성능보다 모델 주변에 구축한 생태계, 즉 ‘하네스(harness)’가 실제 성능을 더 크게 좌우한다는 것입니다.

출처: How Claude Code works in large codebases: Best practices and where to start – Anthropic Blog

대규모 코드베이스를 탐색하는 방식부터 다르다

먼저 Claude Code가 코드베이스를 어떻게 이해하는지부터 살펴봐야 합니다. 많은 AI 코딩 도구가 RAG(Retrieval-Augmented Generation) 방식을 씁니다. 코드베이스 전체를 임베딩해두고, 쿼리가 들어오면 관련 청크를 꺼내오는 방식이죠.

문제는 대규모 팀에서 이 방식이 무너진다는 겁니다. 수천 명의 엔지니어가 매일 코드를 커밋하는 환경에서, 임베딩 파이프라인은 항상 현재를 따라잡지 못합니다. 2주 전에 이름이 바뀐 함수를, 지난 스프린트에서 삭제된 모듈을 반환하면서도 아무런 경고가 없습니다.

Claude Code는 다른 방식을 택했습니다. 에이전틱 탐색, 즉 소프트웨어 엔지니어처럼 직접 파일 시스템을 탐색하고, 파일을 읽고, grep으로 필요한 것을 찾는 방식입니다. 별도의 인덱스 없이 개발자 로컬 머신의 살아있는 코드베이스를 그대로 씁니다.

단, 트레이드오프가 있습니다. 어디를 봐야 할지 출발점 컨텍스트가 충분히 주어질 때 잘 작동합니다. 10억 줄짜리 코드베이스에서 모호한 패턴을 찾으라고 하면 컨텍스트 윈도우 한계에 먼저 부딪힙니다. 코드베이스 설정에 투자하는 팀이 더 나은 결과를 보는 이유가 여기에 있습니다.

하네스: 모델을 둘러싼 생태계

Anthropic이 말하는 ‘하네스’는 다섯 가지 확장 포인트로 구성됩니다.

CLAUDE.md 파일이 가장 먼저입니다. 매 세션 시작 시 Claude가 자동으로 읽는 컨텍스트 파일로, 루트 파일은 전체 그림을, 하위 디렉토리 파일은 로컬 컨벤션을 담습니다. 모든 세션에 로드되는 만큼 범용적으로 적용되는 내용만 유지해야 성능 저하를 막을 수 있습니다.

Hooks는 설정을 자가개선하게 만드는 장치입니다. 많은 팀이 hooks를 “Claude가 잘못된 일을 하지 못하게 막는 스크립트” 정도로 생각하지만, 더 가치 있는 활용은 지속적 개선입니다. 세션 종료 시 hooks가 작업 내용을 반성하고 CLAUDE.md 업데이트를 제안하게 하거나, 세션 시작 시 팀별 컨텍스트를 동적으로 로드해 개발자마다 최적의 설정을 자동으로 갖출 수 있습니다.

Skills는 모든 세션을 무겁게 만들지 않고 필요할 때만 전문 지식을 불러오는 방식입니다. 보안 리뷰 skill은 취약점을 점검할 때만, 문서 처리 skill은 코드 변경 후 문서를 업데이트할 때만 로드됩니다. 특정 경로에 스코프를 지정해 결제 서비스 팀의 배포 skill이 모노레포의 다른 영역에서는 자동으로 불리지 않도록 바인딩하는 것도 가능합니다.

Plugins는 잘 작동하는 설정을 조직 전체에 배포합니다. 한 팀이 발견한 좋은 설정이 그 팀만의 암묵적 지식으로 남는 문제를 해결합니다. Skill, hooks, MCP 설정을 하나의 설치 가능한 패키지로 묶어 신입 엔지니어도 첫날부터 기존 팀원과 동일한 컨텍스트와 기능을 가질 수 있습니다.

LSP 통합은 개발자가 IDE에서 갖는 것과 동일한 코드 탐색 능력을 Claude에게 줍니다. “go to definition”이나 “find all references”처럼요. LSP 없이는 Claude가 텍스트 패턴 매칭에 의존해 같은 이름의 다른 함수를 잘못 참조할 수 있습니다. 한 엔터프라이즈 소프트웨어 회사는 Claude Code 롤아웃 전에 조직 전체에 LSP를 배포해 C, C++ 탐색 신뢰성을 먼저 확보했습니다.

MCP 서버는 Claude가 접근할 수 없는 내부 도구, 데이터 소스, API와 연결합니다. 정교한 팀들은 구조화된 검색을 Claude가 직접 호출할 수 있는 도구로 노출하는 MCP 서버를 구축하기도 했습니다.

마지막으로 서브에이전트는 탐색과 편집을 분리합니다. 읽기 전용 서브에이전트가 서브시스템을 파악해 결과를 파일에 기록하면, 메인 에이전트가 완전한 그림을 가지고 편집을 진행하는 방식입니다.

이 설계가 시사하는 것

Anthropic의 관찰은 AI 코딩 도구를 잘 쓰는 일이 프롬프트 작성의 문제가 아니라는 점을 보여줍니다. 환경 설계의 문제입니다.

하네스 구조는 컨텍스트 관리를 핵심 문제로 설정합니다. 모든 세션에 모든 것을 로드하면 성능이 저하되고, 너무 적으면 Claude가 눈 감고 탐색하게 됩니다. CLAUDE.md의 계층 구조, Skills의 점진적 공개(progressive disclosure), Hooks의 동적 로딩은 모두 이 균형을 맞추기 위한 설계입니다.

모델이 진화할수록 이 하네스도 함께 진화해야 한다는 점도 주목할 만합니다. 예전 모델의 한계를 보완하기 위해 만든 CLAUDE.md 규칙이 새 모델에서는 오히려 제약이 될 수 있습니다. 3~6개월 주기의 구성 검토를 권장하는 이유입니다.

원문에는 코드베이스를 탐색 가능하게 만드는 구체적인 구성 패턴과 성공적인 롤아웃 사례들이 더 담겨 있습니다.