Claude Code 대규모 코드베이스 활용 베스트프랙티스 (2026)

"30만 라인짜리 모노레포에 Claude Code를 붙였더니 답이 산으로 가는데, 이거 쓸 만한 도구 맞나요?"

📌 핵심 3줄 요약

• Claude Code 대규모 코드베이스 운영의 8할은 컨텍스트 윈도우 관리다. 무작정 전체 트리를 보여주지 말 것.
• CLAUDE.md에 디렉터리 맵·금기 규칙을 적어두고, 작업 단위마다 /clear로 세션을 리셋해야 답변 품질이 유지된다.
• 검색·테스트·리팩터링은 서브 에이전트에 위임하면 메인 세션 토큰을 절반 이하로 줄일 수 있다.

 

1. 대규모 코드베이스가 어려운 이유

Anthropic이 2026년 5월 14일에 공개한 "How Claude Code works in large codebases" 글의 첫 줄은 단순하다. "문제는 도구가 아니라 컨텍스트다." Claude Sonnet 4.7의 컨텍스트 윈도우가 1M 토큰까지 늘었어도, 30만 LOC 자바·코틀린 모노레포를 한 번에 밀어 넣으면 응답 품질이 급격히 떨어진다.

실제로 두 달간 사내 결제 모듈(약 28만 LOC, 14개 마이크로서비스)에 Claude Code를 붙여 운영해보니, 답변이 헛도는 케이스는 거의 항상 같은 패턴이었다. 관련 없는 디렉터리까지 끌어와 토큰을 소모하고, 정작 핵심 파일은 압축 단계에서 잘려나갔다. Claude Code 대규모 코드베이스 활용의 핵심은 "무엇을 안 보여줄지" 결정하는 일이다.

아래 표는 흔히 부딪히는 4가지 실패 모드와 원인이다.

증상	실제 원인	1차 처방
파일 이름을 자꾸 헷갈림	디렉터리 맵 부재	CLAUDE.md 작성
긴 세션 후 답이 산만	컨텍스트 누적 오염	/clear 또는 /compact
토큰 청구가 폭증	파일 전체 읽기 남발	Grep·Glob 우선
테스트가 자꾸 깨짐	관련 컨벤션 미고지	서브 에이전트 분리

 

2. CLAUDE.md로 프로젝트 구조 알리기

제일 먼저 할 일은 레포 루트에 CLAUDE.md를 만드는 것이다. Anthropic 공식 가이드는 이 파일을 "Claude의 첫 인사말이자 마지막 안전망"이라 표현했다. 세션이 시작될 때 자동으로 읽혀 들어가므로, 디렉터리 맵·코딩 컨벤션·금기 규칙을 한 곳에 모아두면 매번 같은 설명을 반복할 필요가 없다.

경험상 다음 4가지 블록이면 충분하다.

• 디렉터리 지도 — 모듈별 1줄 설명. 굳이 모든 파일을 나열할 필요는 없고, "여기서 시작하면 된다"는 진입점만 명시.
• 코딩 컨벤션 — 들여쓰기, 네이밍, 테스트 위치, 의존성 추가 정책.
• 금기 사항 — "이 디렉터리는 자동 생성이라 절대 수정 금지" 같은 가드레일.
• 자주 쓰는 명령어 — 빌드·테스트·린트 명령을 코드 블록으로.

실제 예시는 이런 식이다.

# CLAUDE.md

## 디렉터리 지도
- services/payment/ — 결제 코어 (Kotlin, Spring Boot)
- services/wallet/ — 지갑·잔액 관리
- libs/common/ — 공용 DTO/유틸. 수정 시 모든 서비스 영향
- infra/ — Terraform. 직접 수정 금지, PR로만

## 컨벤션
- 모든 신규 API는 OpenAPI 스키마 먼저 작성
- 테스트는 src/test/kotlin 미러 구조
- 의존성 추가 전 반드시 `./gradlew :services:payment:dependencies` 확인

## 빌드 / 테스트
```bash
./gradlew :services:payment:build
./gradlew :services:payment:test --tests "PaymentServiceTest"
```

## 금기
- libs/generated/** 수정 금지 (OpenAPI 코드 생성)
- infra/prod/** 수정 금지

 

3. /clear·/compact 타이밍 잡기

대규모 코드베이스에서 가장 자주 마주치는 함정은 "한 세션에서 너무 많은 일을 하려는 욕심"이다. 1시간 넘게 같은 세션을 쓰면 압축 단계에서 핵심 파일 내용이 손실되고, 엉뚱한 추론이 시작된다.

경험적으로 다음 시점에 세션을 리셋하면 품질이 안정적이다.

1. 작업 단위 전환 시 — 버그 수정 → 새 기능 구현으로 넘어갈 때 무조건 /clear.
2. 같은 질문에 두 번째 답변이 첫 번째보다 부정확할 때 — 오염 신호.
3. 토큰 사용량이 컨텍스트 윈도우의 70%를 넘었을 때 — /compact로 요약.

/clear와 /compact의 차이는 다음 표로 정리된다.

명령	동작	언제 쓰나
/clear	대화 전체 삭제, CLAUDE.md만 유지	작업 전환·맥락 단절 OK
/compact	앞 대화를 요약문으로 압축	긴 디버깅 흐름 유지하면서 절약
새 세션	완전히 다른 워킹 디렉터리에서 시작	병렬 작업 격리 필요할 때

실수하기 쉬운 지점이 있다. /compact는 만능이 아니다. 요약 과정에서 코드 스니펫이 자연어로 풀어 써지는 경우가 있고, 그러면 정확한 변수명·시그니처가 사라진다. 중요한 코드 변경 직전에는 /compact 대신 /clear가 안전하다.

 

4. 서브 에이전트 위임 패턴 — 역할 분리

Anthropic 가이드의 두 번째 큰 메시지는 "한 세션이 모든 일을 할 필요는 없다"는 것이다. Claude Code의 Task 도구로 서브 에이전트를 띄우면, 검색·테스트 실행·문서 요약 같은 부수 작업을 별도 컨텍스트에서 처리하고 결과만 메인 세션에 돌려준다.

실무에서 자주 쓰는 위임 3패턴은 이렇다.

• 검색 에이전트 — "결제 실패 처리 로직이 어디에 있는지 찾아줘" 같은 탐색 작업. 후보 파일 경로 3~5개만 돌려받음.
• 테스트 러너 — 특정 테스트를 돌리고 실패 로그 요약만 가져오기. 전체 stdout이 메인 세션에 쌓이는 걸 막는다.
• 리팩터링 워커 — "이 함수 시그니처가 바뀌었으니 모든 호출처를 업데이트" 같은 반복 작업.

위임 효과는 토큰 사용량에서 즉시 드러난다. 결제 모듈 리팩터링 한 사이클을 비교해보면, 단일 세션 약 38만 토큰 → 서브 에이전트 분리 시 약 17만 토큰으로 떨어진다. 비용도 비용이지만, 메인 세션이 가벼워져 후속 결정 품질이 눈에 띄게 좋아진다.

5. Grep·Glob 먼저, Read는 나중

토큰을 가장 빨리 태우는 행동은 "확인 차원에서 파일 전체 읽기"다. 30만 LOC 모노레포에서 무심코 Read를 다섯 번만 해도 컨텍스트가 절반 차버린다. 순서를 바꿔야 한다.

1. Glob으로 후보 파일 좁히기 — 디렉터리·확장자 패턴으로 1차 필터.
2. Grep으로 정확한 매칭 위치만 잡기 — 라인 번호와 주변 컨텍스트 5줄이면 충분.
3. 그래도 부족할 때만 Read — 그것도 offset·limit로 필요한 구간만.

아래 체크리스트는 사내에서 PR 리뷰 전에 돌려보는 토큰 위생 점검이다.

• 한 세션에서 같은 파일을 3회 이상 Read하지 않았는가?
• 전체 디렉터리 트리(ls -R) 출력을 컨텍스트에 넣지 않았는가?
• 긴 로그·빌드 출력은 grep/head로 요약했는가?
• 의존성 그래프 같은 정적 파일은 캐시(요약 .md)로 대체했는가?

특히 마지막 항목이 의외로 효과가 크다. ./gradlew dependencies 결과처럼 매번 거의 같은 파일은 사람이 한 번 요약해서 docs/deps-summary.md로 만들어두면, 이후 모든 세션에서 그걸 참조하면 된다.

 

6. 실수하기 쉬운 안티패턴 5가지

두 달 운영하면서 직접 부딪힌 안티패턴을 정리하면 다음과 같다.

안티패턴	왜 위험한가	대안
레포 전체 읽어달라 요청	토큰 폭주, 결정 흐림	CLAUDE.md + 진입점 1~2개
한 세션에서 8시간 작업	컨텍스트 오염 누적	작업 단위마다 /clear
생성 코드 디렉터리까지 노출	잘못된 수정 위험	CLAUDE.md 금기 항목 명시
큰 PR 한 번에 검토 요청	놓치는 변경 다수	파일 그룹별 분할 리뷰
테스트 실패 로그 전체 붙여넣기	불필요한 스택 트레이스	에러 메시지 + 호출 위치만

 

⚠️ 단점과 주의할 점

• 1M 토큰이라고 안심 금지 — 실측에서 60% 이상 차면 압축 손실이 체감됨. 항상 여유분을 남길 것.
• CLAUDE.md를 너무 길게 쓰면 역효과 — 1,500자 안쪽으로 핵심만 적는 게 답변 품질에 유리.
• 서브 에이전트가 만능은 아님 — 트랜잭션이 걸린 복잡한 리팩터링은 분리 비용이 더 큼.
• 비용 청구는 워크스페이스 단위로 누적되므로, 팀 단위 도입 시 사전 한도 설정 필요.

 

FAQ

Q1. Claude Code는 대규모 코드베이스에서 잘 동작하나요?

실측 기준으로 30만 LOC급 모노레포에서도 문제없이 쓸 수 있다. 다만 "잘 동작한다"의 전제는 CLAUDE.md 정비와 세션 위생 관리다. 아무 준비 없이 붙이면 5만 LOC만 넘어가도 답변이 흔들린다.

Q2. 컨텍스트 윈도우 한계는 어떻게 극복하나요?

윈도우를 넓히려 애쓰기보다 "보내는 토큰을 줄이는" 방향이 정답이다. Grep·Glob 우선, 파일 일부만 Read, 서브 에이전트 위임 3가지 조합으로 대부분 해결된다.

Q3. 모노레포에서 Claude Code를 효율적으로 쓰는 방법은?

서비스 단위로 별도 CLAUDE.md를 두고, 루트에는 "어떤 서비스가 어디 있는지"만 적는 2단 구조가 좋다. 한 세션은 한 서비스만 깊게 보도록 제약하는 것이 핵심.

Q4. Claude Code 사용 시 토큰 비용을 줄이는 방법은?

가장 큰 비용 절감은 "Read 남발 줄이기"에서 온다. 그 다음이 서브 에이전트 위임, 그 다음이 정기적인 /clear. 캐시 가능한 정적 정보는 .md 파일로 추출해두면 반복 토큰을 크게 줄인다.

Q5. /clear는 언제 써야 하나요?

작업 단위가 바뀔 때마다, 같은 질문에 답이 두 번 다를 때, 그리고 컨텍스트 사용량이 70%를 넘었을 때 — 이 3가지 조건 중 하나라도 맞으면 망설이지 말 것.

 

🚀 지금 바로 할 일

1. 레포 루트에 CLAUDE.md 초안 작성 — 디렉터리 지도·금기 사항 2블록만이라도 우선.
2. 오늘 첫 작업 단위가 끝나는 시점에 /clear 1회 실습.
3. 다음 검색 작업을 Task 서브 에이전트로 위임해 토큰 사용량 비교해보기.

 

💬 의견

비슷한 규모의 모노레포에서 Claude Code를 운영 중이라면 어떤 패턴이 가장 효과적이었는지 댓글로 공유 부탁드립니다. 다음 글은 CLAUDE.md 작성 템플릿을 서비스 유형별로 정리할 예정입니다.

 

참고 자료

• Anthropic — How Claude Code works in large codebases (2026-05-14)
• Claude Code 공식 문서
• Claude Code Memory & CLAUDE.md 가이드

---

작성자: 10년차 백엔드 엔지니어. 28만 LOC 결제 모노레포(Kotlin/Spring Boot, 14개 마이크로서비스)에서 Claude Code를 2개월 운영하며 정리한 노트. 사내 토큰 비용 보고서와 함께 검증한 패턴 위주로 정리했다.