claude-code는 대규모 코드베이스를 중앙 인덱스 없이 로컬 파일시스템, grep, 참조 탐색으로 읽는다. 이 방식은 stale embedding index 문제를 피하지만, 처음 어디를 봐야 하는지 알려주는 코드베이스 맥락이 부족하면 금방 컨텍스트를 낭비한다.
RAG 인덱스보다 라이브 코드베이스 탐색
대규모 모노레포에서 RAG 기반 코딩 도구는 인덱스가 실제 코드보다 늦어지는 문제가 생긴다. Claude Code는 현재 checkout을 직접 읽기 때문에 방금 rename된 함수나 삭제된 모듈을 그대로 반영한다. 대신 팀은 코드베이스를 Claude가 탐색하기 쉽게 정리해야 한다.
설정 순서
| 순서 | 구성 | 역할 |
|---|---|---|
| 1 | CLAUDE.md | 프로젝트 전체 구조, 금지 사항, 빌드·테스트 진입점을 짧게 제공 |
| 2 | Hooks | lint/test/format, 위험 명령 차단, 세션 후 학습 반영을 자동화 |
| 3 | Skills | 보안 리뷰, 배포, 문서 처리처럼 필요할 때만 로드되는 전문 워크플로 |
| 4 | Plugins | 팀에서 검증한 skills/hooks/MCP 설정을 조직 전체에 배포 |
| 5 | LSP | grep이 아니라 symbol 단위로 정의·참조를 따라가게 한다 |
| 6 | MCP | 내부 문서, 티켓, 분석 시스템 같은 외부 도구 연결 |
| 7 | Subagents | 탐색과 편집을 분리하고 큰 시스템 조사를 별도 컨텍스트에서 수행 |
대규모 코드베이스 패턴
- 루트
CLAUDE.md는 길게 쓰지 말고 최상위 지도와 치명적 규칙만 둔다 - 서비스·패키지 하위 디렉터리에 지역별
CLAUDE.md를 둔다 - 각 하위 디렉터리에는 해당 범위의 test/lint/build 명령만 명시한다
- generated files, build artifacts, third-party code는 ignore와 permission deny로 제외한다
- 디렉터리 구조가 낡았으면 top-level folder map을 Markdown으로 만든다
- C/C++/Java/C# 같은 큰 코드베이스는 LSP를 먼저 붙인다
조직 운영 포인트
성공한 도입 사례는 대개 한 명 이상의 DRI가 Claude Code 설정을 소유한다. 개별 개발자가 각자 CLAUDE.md, hooks, skills를 만들게 두면 좋은 설정이 팀 지식으로 퍼지지 않는다. 최소한 다음 소유권은 정해야 한다.
- 표준
CLAUDE.md계층 구조 - 허용·금지 permission 정책
- 조직 공통 skills/plugins 목록
- 코드 리뷰와 보안 검토 기준
- 모델 업데이트 후 설정 재검토 주기
관련 문서
- claude-code — Claude Code 개요
- agent-harness — 하네스 엔지니어링
- claude-code-tips-project-structure — 프로젝트 구조화 팁
- claude-code-tips-development-governance — AI 보조 개발 거버넌스
참고 자료
- How Claude Code works in large codebases: Best practices and where to start — Claude Blog (2026-05-14)