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

Claude Code는 중앙 인덱스를 업로드하지 않고 개발자 머신에서 직접 파일 시스템을 순회하며 grep과 참조 추적으로 살아 있는 코드베이스를 읽는다.

성능은 모델보다 하네스에 더 크게 좌우된다. 핵심 구성요소는 CLAUDE.md, hooks, skills, plugins, MCP 서버이며, skills는 온디맨드로 로드되고 plugins는 설정을 묶어 배포한다.

대규모 저장소에서는 다음 패턴을 권한다.

• 루트 CLAUDE.md는 얇게 유지하고, 하위 디렉터리 파일로 로컬 규칙을 분리한다.
• 저장소 루트보다 실제 작업 디렉터리에서 시작해 관련 맥락만 먼저 읽게 한다.
• 테스트·lint 명령도 디렉터리별로 범위를 좁히고, 생성물·빌드 산출물·서드파티 코드는 제외 규칙으로 걸러낸다.
• 디렉터리 구조가 복잡하면 루트 Markdown 맵을 두고, 단순한 경우에는 @ 멘션으로 필요한 파일만 지정한다.

정밀한 탐색이 필요하면 LSP 통합으로 문자열 검색 대신 정의·참조 추적을 쓰고, 내부 도구와 데이터는 MCP 서버로 연결한다. 읽기와 편집은 subagents로 분리해 병렬 탐색과 편집을 나눌 수 있다.

도입이 커질수록 거버넌스가 중요해진다. 승인된 skills·plugins 범위, 코드 리뷰 절차, 권한 정책을 정하고, 설정을 관리·갱신할 DRI 또는 agent manager를 둬야 하며, 모델이 발전할수록 과거 한계용 규칙은 오히려 제약이 될 수 있어 3~6개월마다 하네스를 재검토하라고 권고한다.