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

• Claude Code는 인덱스를 업로드하지 않고 개발자 머신에서 파일 시스템 탐색과 grep, 참조 추적으로 라이브 코드베이스를 직접 읽음
• 성능은 모델만이 아니라 CLAUDE.md, hooks, skills, plugins, MCP 서버로 이뤄진 하네스와 구축 순서에 크게 좌우됨
• 대규모 저장소에서는 얇고 계층적인 CLAUDE.md, 하위 디렉터리 시작, 범위 지정 테스트·린트, 제외 규칙이 탐색 효율을 높임
• LSP 통합은 문자열 검색 대신 심볼 기준 정의·참조 추적을 제공해, 다중 언어·대규모 코드베이스에서 잘못된 탐색을 줄임
• 성공적인 도입에는 3~6개월마다 설정을 검토하고, plugin·권한·규칙을 관리할 DRI 또는 agent manager가 필요함

대규모 코드베이스에서 Claude Code가 탐색하는 방식

• Claude Code는 소프트웨어 엔지니어처럼 파일 시스템을 순회하고, 파일을 읽고, grep으로 필요한 내용을 찾고, 코드베이스 전반의 참조를 따라감
• 개발자 머신에서 로컬로 동작하며, 코드베이스 인덱스를 빌드하거나 유지하거나 서버에 업로드할 필요가 없음
• RAG 기반 AI 코딩 도구는 전체 코드베이스를 임베딩하고 질의 시점에 관련 청크를 가져오지만, 대규모 환경에서는 임베딩 파이프라인이 활발한 개발 속도를 따라가지 못할 수 있음
• 인덱스가 몇 주, 며칠, 몇 시간 전 상태를 반영하면 이미 이름이 바뀐 함수나 지난 스프린트에서 삭제된 모듈을 반환할 수 있고, 해당 정보가 오래됐다는 신호도 없을 수 있음
• Claude Code의 에이전트형 검색은 임베딩 파이프라인이나 중앙 인덱스 없이 각 개발자 인스턴스가 살아 있는 코드베이스를 기준으로 작업하게 해줌
• 단점도 있음: Claude가 어디를 봐야 할지 알 수 있는 시작 문맥이 충분할 때 가장 잘 작동함
• 모호한 패턴의 모든 인스턴스를 10억 줄 코드베이스에서 찾으라고 하면 작업이 시작되기도 전에 컨텍스트 창 한계에 부딪힐 수 있음
• 코드베이스를 잘 설정하고 CLAUDE.md 파일과 skills로 문맥을 계층화한 팀일수록 더 좋은 결과를 얻음

모델만큼 중요한 하네스

• Claude Code의 성능은 모델 자체보다 모델 주변에 구축된 하네스(harness) 에 크게 좌우됨
• 하네스는 CLAUDE.md, hooks, skills, plugins, MCP 서버라는 다섯 확장 지점으로 구성됨
• 각 계층은 앞선 계층 위에 쌓이므로 팀이 구축하는 순서도 중요함
• LSP 통합과 subagents는 이 설정을 보완하는 추가 역량으로 작동함

• CLAUDE.md 파일

  • CLAUDE.md는 Claude가 모든 세션 시작 시 자동으로 읽는 문맥 파일임
  • 루트 파일은 큰 그림을 담고, 하위 디렉터리 파일은 로컬 규칙을 담음
  • 모든 세션에 로드되므로 광범위하게 적용되는 내용에 집중해야 성능 저하를 막을 수 있음

• Hooks

  • Hooks는 Claude의 잘못된 행동을 막는 스크립트에 그치지 않고, 설정을 지속적으로 개선하는 데 더 큰 가치가 있음
  • stop hook은 세션 중 일어난 일을 되돌아보고 문맥이 신선할 때 CLAUDE.md 업데이트를 제안할 수 있음
  • start hook은 팀별 문맥을 동적으로 로드해 개발자가 수동 설정 없이도 자신의 모듈에 맞는 설정을 받게 함
  • 린팅과 포매팅 같은 자동 검사는 Claude가 지시를 기억하게 하는 것보다 hook으로 규칙을 결정적으로 강제할 때 더 일관된 결과를 냄

• Skills

  • Skills는 모든 세션을 비대하게 만들지 않으면서 필요한 전문성을 온디맨드로 유지하게 함
  • 대규모 코드베이스에는 수십 가지 작업 유형이 있을 수 있지만, 모든 전문성이 모든 세션에 들어갈 필요는 없음
  • Skills는 점진적 공개(progressive disclosure)를 통해 특화 워크플로와 도메인 지식을 컨텍스트 공간 밖에 두고, 필요할 때만 로드함
  • 보안 리뷰 skill은 Claude가 취약점을 평가할 때 로드되고, 문서 처리 skill은 코드 변경 뒤 문서를 업데이트해야 할 때 로드되는 식으로 동작함
  • Skills는 특정 경로에 범위를 지정할 수 있어, 결제 서비스 팀의 배포 skill이 해당 디렉터리에만 바인딩되고 모노레포의 다른 영역 작업에는 자동 로드되지 않게 할 수 있음

• Plugins

  • Plugins는 잘 작동하는 설정이 부족 지식으로 남지 않게 배포하는 수단임
  • plugin은 skills, hooks, MCP 설정을 하나의 설치 가능한 패키지로 묶음
  • 새 엔지니어가 첫날 plugin을 설치하면 이미 Claude를 쓰던 사람들과 같은 문맥과 기능을 즉시 갖게 됨
  • plugin 업데이트는 managed marketplaces를 통해 조직 전체에 배포될 수 있음
  • 한 대형 리테일 조직은 Claude를 내부 분석 플랫폼에 연결하는 skill을 만들어 비즈니스 분석가가 워크플로를 떠나지 않고 성과 데이터를 가져오게 했고, 비즈니스 전체 롤아웃 전에 이를 plugin으로 배포함

• Language Server Protocol 통합

  • Language Server Protocol(LSP) 통합은 Claude가 개발자의 IDE와 같은 코드 탐색 능력을 갖게 함
  • 대규모 코드베이스용 IDE 대부분은 이미 “go to definition”과 “find all references”를 구동하는 LSP를 실행하고 있음
  • Claude에 이를 노출하면 함수 호출을 정의로 따라가고, 파일 전반의 참조를 추적하며, 서로 다른 언어의 같은 이름 함수를 구분하는 심볼 수준 정밀도를 얻음
  • LSP가 없으면 Claude는 텍스트 패턴 매칭에 의존해 잘못된 심볼에 도달할 수 있음
  • 한 엔터프라이즈 소프트웨어 회사는 C와 C++ 탐색을 대규모 환경에서 안정화하기 위해 Claude Code 롤아웃 전에 LSP 통합을 조직 전체에 배포함
  • 다중 언어 코드베이스에서는 가장 가치가 높은 투자 중 하나임

• MCP 서버

  • MCP 서버는 Claude가 직접 도달할 수 없는 내부 도구, 데이터 소스, API에 연결하는 방식임
  • 가장 성숙한 팀은 Claude가 직접 호출할 수 있는 도구로 구조화 검색을 노출하는 MCP 서버를 구축함
  • 다른 팀은 Claude를 내부 문서, 티켓 시스템, 분석 플랫폼에 연결함

• Subagents

  • Subagents는 탐색과 편집을 분리함
  • subagent는 자체 컨텍스트 창을 가진 격리된 Claude 인스턴스로, 작업을 받아 수행한 뒤 최종 결과만 부모에게 반환함
  • 하네스가 갖춰진 뒤 일부 팀은 읽기 전용 subagent를 띄워 서브시스템을 매핑하고 결과를 파일에 쓰게 한 다음, 메인 에이전트가 전체 그림을 바탕으로 편집하게 함

• 구성요소별 역할과 흔한 혼동

  • CLAUDE.md: Claude가 자동으로 읽는 문맥 파일이며 모든 세션에 로드됨. 프로젝트별 규칙과 코드베이스 지식에 적합하고, skill에 들어가야 할 재사용 전문성을 넣기 쉬움
  • Hooks: 핵심 시점에 실행되는 스크립트이며 이벤트로 트리거됨. 일관된 동작 자동화와 세션 학습 포착에 적합하고, 자동 실행돼야 할 일을 프롬프트로 처리하기 쉬움
  • Skills: 특정 작업 유형을 위한 패키지화된 지시이며 관련 있을 때 온디맨드로 로드됨. 세션과 프로젝트 전반에서 재사용되는 전문성에 적합하고, 모든 내용을 CLAUDE.md에 넣기 쉬움
  • Plugins: skills, hooks, MCP 설정 번들이며 설정 후 항상 사용 가능함. 조직 전체에 작동하는 설정을 배포하는 데 적합하고, 좋은 설정을 부족 지식으로 남겨두기 쉬움
  • LSP: 언어별 서버를 통한 실시간 코드 인텔리전스이며 설정 후 항상 사용 가능함. 타입 언어의 심볼 수준 탐색과 자동 오류 감지에 적합하고, 자동으로 된다고 가정하기 쉬움
  • MCP 서버: 외부 도구와 데이터 연결이며 설정 후 항상 사용 가능함. Claude가 직접 접근할 수 없는 내부 도구 접근에 적합하고, 기본이 작동하기 전에 MCP 연결부터 만들기 쉬움
  • Subagents: 특정 작업용 별도 Claude 인스턴스이며 호출 시 실행됨. 탐색과 편집 분리, 병렬 작업에 적합하고, 탐색과 편집을 같은 세션에서 처리하기 쉬움
  • LSP는 plugin 계층을 통해 접근되며, subagents는 설정된 확장 지점이 아니라 위임 역량임

성공적인 배포에서 반복된 세 가지 설정 패턴

• 대규모에서도 탐색 가능한 코드베이스 만들기

  • Claude가 대규모 코드베이스에서 도움을 줄 수 있는 범위는 올바른 문맥을 찾는 능력에 의해 제한됨
  • 모든 세션에 너무 많은 문맥을 로드하면 성능이 떨어지고, 너무 적은 문맥은 Claude가 눈먼 상태로 탐색하게 만듦
  • 효과적인 배포는 초기에 코드베이스를 Claude가 읽기 쉽게 만드는 데 투자함

  • CLAUDE.md 파일은 얇고 계층적으로 유지

    • Claude는 코드베이스를 이동하면서 CLAUDE.md 파일을 가산적으로 로드함
    • 루트 파일은 큰 그림을, 하위 디렉터리 파일은 로컬 규칙을 맡음
    • 루트 파일은 포인터와 치명적인 주의사항만 담아야 하며, 그 밖의 내용은 잡음이 되기 쉬움

  • 저장소 루트가 아니라 하위 디렉터리에서 시작

    • Claude는 작업과 실제로 관련 있는 코드베이스 부분으로 범위가 제한될 때 가장 잘 작동함
    • 모노레포에서는 도구가 루트 접근을 전제로 하는 경우가 많아 직관에 반할 수 있음
    • Claude는 디렉터리 트리를 자동으로 위로 올라가며 발견한 모든 CLAUDE.md 파일을 로드하므로 루트 수준 문맥은 사라지지 않음

  • 테스트와 린트 명령은 하위 디렉터리별로 범위 지정

    • Claude가 한 서비스만 바꿨는데 전체 테스트 스위트를 실행하면 타임아웃이 나고 관련 없는 출력에 컨텍스트를 낭비함
    • 하위 디렉터리의 CLAUDE.md 파일은 코드베이스의 해당 부분에 적용되는 명령을 명시해야 함
    • 각 디렉터리가 자체 테스트와 빌드 명령을 가진 서비스 지향 코드베이스에서 잘 작동함
    • 깊은 교차 디렉터리 의존성을 가진 컴파일 언어 모노레포에서는 하위 디렉터리별 범위 지정이 더 어렵고 프로젝트별 빌드 설정이 필요할 수 있음

  • .ignore 파일로 생성 파일, 빌드 산출물, 서드파티 코드 제외

    • .claude/settings.json에 permissions.deny 규칙을 커밋하면 제외 규칙이 버전 관리됨
    • 팀의 모든 개발자가 별도 설정 없이 같은 노이즈 감소 효과를 얻음
    • 일부 코드베이스에서는 생성 파일 자체가 개발 대상일 수 있음
    • 코드 생성기를 다루는 개발자는 프로젝트 수준 제외 규칙을 로컬 설정에서 재정의할 수 있고, 나머지 팀에는 영향을 주지 않음

  • 디렉터리 구조가 충분하지 않으면 코드베이스 맵 구축

    • 코드가 일반적인 디렉터리 구조로 통합돼 있지 않은 조직에서는 루트의 가벼운 Markdown 파일이 도움이 됨
    • 각 최상위 폴더와 그 안에 무엇이 있는지 한 줄 설명을 적으면 Claude가 파일을 열기 전에 훑을 수 있는 목차가 됨
    • 최상위 폴더가 수백 개라면 루트 파일은 최고 수준 구조만 설명하고, 하위 디렉터리 CLAUDE.md가 다음 수준 세부 정보를 온디맨드로 제공하는 계층형 접근이 가장 잘 작동함
    • 더 단순한 경우에는 Claude가 참조해야 할 특정 파일이나 디렉터리를 @로 멘션하는 것으로 같은 역할을 할 수 있음

  • LSP 서버로 문자열이 아니라 심볼 기준 검색

    • 대규모 코드베이스에서 흔한 함수 이름을 grep하면 수천 개 매치가 나오고, Claude는 무엇이 중요한지 판단하려고 파일을 열며 컨텍스트를 소모함
    • LSP는 같은 심볼을 가리키는 참조만 반환하므로, Claude가 아무것도 읽기 전에 필터링이 이뤄짐
    • 설정하려면 언어용 code intelligence plugin과 해당 language server 바이너리를 설치해야 함
    • Claude Code 문서에는 사용 가능한 plugin과 문제 해결 방법이 포함됨

  • 예외

    • 계층형 CLAUDE.md 접근도 깨지는 엣지 케이스가 있음
    • 수십만 개 폴더와 수백만 개 파일을 가진 코드베이스, Git이 아닌 버전 관리에 있는 레거시 시스템이 이에 해당함

• 모델 지능 변화에 맞춰 CLAUDE.md 파일 유지보수

  • 모델이 발전하면 현재 모델을 위해 작성한 지시가 미래 모델에는 방해가 될 수 있음
  • Claude가 과거에 어려워하던 패턴을 안내하던 CLAUDE.md 규칙은 새 모델에서 불필요해지거나 오히려 제약이 될 수 있음
  • 예를 들어 모든 리팩터링을 단일 파일 변경으로 나누라는 규칙은 이전 모델이 흐름을 유지하는 데 도움이 됐을 수 있지만, 새 모델이 잘 처리하는 조정된 다중 파일 편집을 막을 수 있음
  • 모델 추론이나 Claude Code 도구의 특정 한계를 보완하려고 만든 skills와 hooks는 그 한계가 사라지면 오버헤드가 됨
  • Perforce 코드베이스에서 p4 edit을 강제하기 위해 파일 쓰기를 가로채던 hook은 Claude Code가 네이티브 Perforce 모드를 추가한 뒤 중복이 됨
  • 팀은 3~6개월마다 의미 있는 설정 검토를 예상해야 함
  • 주요 모델 릴리스 뒤 성능이 정체된 것처럼 느껴질 때도 설정 검토를 할 가치가 있음

• Claude Code 관리와 도입의 소유권 지정

  • 기술 설정만으로는 도입이 일어나지 않음
  • 가장 빠르게 퍼진 롤아웃은 광범위한 접근 전에 인프라 투자가 있었음
  • 작은 팀, 때로는 한 사람이 도구를 연결해 개발자가 처음 Claude를 만졌을 때 이미 워크플로에 맞게 작동하도록 만들었음
  • 한 회사에서는 엔지니어 몇 명이 첫날부터 사용할 수 있는 plugin과 MCP 묶음을 구축함
  • 다른 회사에서는 AI 코딩 도구 관리를 전담하는 팀이 롤아웃 전에 인프라를 준비함
  • 이 작업은 보통 신규 엔지니어 온보딩과 개발자 도구 구축을 맡는 개발자 경험 또는 개발자 생산성 조직 아래에 있음
  • 여러 조직에서는 Claude Code 생태계를 관리하는 하이브리드 PM/엔지니어 역할인 agent manager가 등장하고 있음
  • 전담 팀이 없다면 최소 실행 가능한 형태는 DRI 한 명임
  • 이 DRI는 Claude Code 설정, 설정값 판단, 권한 정책, plugin marketplace, CLAUDE.md 규칙의 소유권과 최신 상태 유지 책임을 가져야 함
  • 상향식 도입은 열의를 만들지만, 효과 있는 것들을 중앙화할 사람이 없으면 파편화될 수 있음
  • 표준화된 CLAUDE.md 계층이나 선별된 skills와 plugins 같은 Claude Code 규칙을 모으고 전파할 개인 또는 팀이 필요함
  • 이 작업이 없으면 지식은 부족 지식으로 남고 도입은 정체됨

거버넌스와 롤아웃

• 대규모 조직, 특히 규제 산업에서는 거버넌스 질문이 일찍 등장함
• 어떤 skills와 plugins를 사용할 수 있는지 누가 통제하는지, 수천 명의 엔지니어가 같은 것을 독립적으로 다시 만들지 않게 하는 방법, AI 생성 코드가 사람이 만든 코드와 같은 리뷰 절차를 거치게 하는 방법이 주요 쟁점임
• 초기에는 승인된 skills의 정의된 집합, 필수 코드 리뷰 절차, 제한된 초기 접근으로 시작하고 신뢰가 쌓이면 확장하는 접근이 권장됨
• 가장 매끄러운 배포는 초기에 엔지니어링, 정보보안, 거버넌스 대표가 함께 참여하는 교차 기능 워킹그룹을 만들고 요구사항과 롤아웃 로드맵을 함께 정의한 조직에서 나옴

조직에 적용할 때의 전제와 한계

• Claude Code는 엔지니어가 주요 코드베이스 기여자이고, 저장소가 Git을 사용하며, 코드가 표준 디렉터리 구조를 따르는 전통적 소프트웨어 엔지니어링 환경을 중심으로 설계됨
• 대부분의 대규모 코드베이스는 이 틀에 맞지만, 큰 바이너리 자산을 가진 게임 엔진, 비전통적 버전 관리 환경, 비엔지니어가 코드베이스에 기여하는 환경은 추가 설정 작업이 필요함
• 제시된 패턴은 전통적 설정을 전제로 하며 여러 고객 환경에서 작동함
• 남은 복잡성은 각 조직의 코드베이스, 도구, 조직 구조에 맞게 판단해야 함
• Anthropic의 Applied AI 팀은 이런 패턴을 조직의 구체적 요구사항으로 옮기기 위해 엔지니어링 팀과 직접 협업함