10만 줄 이상의 대규모 코드베이스에서 Claude Code를 효과적으로 사용하는 점진적 탐색·선택적 로드·서브에이전트 분산 전략.
대규모 코드베이스 — 크기가 문제가 되지 않게
코드베이스가 커질수록 Claude Code의 한계가 드러납니다. 10만 줄 이상의 프로젝트에서 "전체를 이해해줘"라고 하면 컨텍스트 윈도우를 가득 채워도 부족합니다. 대규모 코드베이스를 다루는 방법은 "더 큰 컨텍스트를 주는 것"이 아니라 필요한 것만 정확히 전달하는 것입니다.
점진적 탐색 패턴
전체를 한 번에 이해시키려 하지 말고, 작업에 필요한 부분만 단계적으로 로드합니다.
# ❌ 비효율적 — 전체 읽기
"전체 프로젝트 구조를 이해해줘"
→ 수백 개 파일을 읽어 컨텍스트 소모
# ✅ 효율적 — 관련 부분만
"결제 관련 기능을 수정해야 해.
먼저 'payment' 또는 'checkout'이 포함된 파일 목록만 보여줘.
전체를 읽지 말고 파일 이름만."
→ Claude가 Glob/Grep으로 관련 파일 목록만 파악
→ 실제 수정할 파일만 Read
→ 컨텍스트 90% 절약CLAUDE.md로 탐색 가이드 제공
대규모 프로젝트일수록 CLAUDE.md의 경로 정보가 중요합니다. Claude가 어디서 무엇을 찾아야 하는지 알면 불필요한 탐색을 줄입니다.
# CLAUDE.md 대규모 프로젝트용 섹션
## 기능별 위치 가이드
인증/권한: app/actions/auth.ts, utils/admin-auth.ts
결제: app/actions/payment.ts, app/api/webhook/
알림: app/actions/notification.ts, components/NotificationBell.tsx
파일 업로드: utils/upload-policy.ts, app/api/upload/
이메일 발송: utils/email.ts (Resend 사용)
SMS 발송: utils/sms.ts (알리고 사용)
## 절대 건드리지 말 것
types/supabase.ts (자동생성)
middleware.ts (Supabase 세션)
.env.local (로컬만, git 제외)서브에이전트로 코드베이스 분할 탐색
"전체 코드베이스에서 deprecated된 패턴을 찾아줘.
범위가 넓으니 서브에이전트로 분할해서:
서브에이전트 1: app/[locale]/ — 공개 페이지
서브에이전트 2: app/admin/ — 어드민 페이지
서브에이전트 3: components/ — 컴포넌트
서브에이전트 4: app/actions/ — Server Actions
각 에이전트가 찾을 것:
- fetch() 직접 사용 (Server Action으로 대체 필요)
- useEffect 안의 데이터 패칭 (React Query/SWR 고려)
- any 타입 사용 (Supabase 제외)
결과를 deprecated-patterns.md로 취합."선택적 파일 로드 전략
# 특정 기능 수정 전 관련 파일만 선택적으로 로드
"사용자 프로필 업데이트 기능에 버그가 있어.
다음 파일들만 읽고 원인 파악해줘 (다른 파일은 읽지 마):
- app/actions/profile.ts
- app/[locale]/profile/edit/page.tsx
- types/supabase.ts (profiles 테이블 타입만)
이 세 파일 범위에서 버그를 찾아줘."대규모 리팩터링 — 마이그레이션 전략
# 전체를 한 번에 바꾸지 않는 점진적 전략
"전체 프로젝트의 fetch 호출을 Server Action으로 마이그레이션해야 해.
파일이 50개라 한 번에 못 함.
전략:
1. 서브에이전트로 모든 fetch 사용처 목록 작성 (분석만)
2. 우선순위 분류:
High: 보안 민감 (인증, 결제)
Medium: 데이터 변경 (POST/PUT/DELETE)
Low: 데이터 조회 (GET)
3. High 우선 처리 (5개씩 배치)
4. 각 배치 완료 후 빌드·테스트 검증
오늘은 High 우선순위만 처리해줘."코드베이스 문서화 자동화
"현재 문서화가 부족한 복잡한 함수들을 찾아줘.
기준: 30줄 이상, JSDoc 없음, 외부에서 3개 이상 import
대상 파일: app/actions/*.ts, utils/*.ts
발견된 함수들에:
1. 함수 목적 (1줄)
2. 파라미터 설명
3. 반환값 설명
4. 예외 케이스 (있으면)
형식: JSDoc 스타일로 추가"대규모 코드베이스에서 Claude Code를 잘 쓰는 비결은 "AI가 필요한 것을 스스로 찾게 하지 말고, 개발자가 관련 파일을 지정해주는 것"입니다. CLAUDE.md의 "기능별 위치 가이드"가 이 역할을 합니다. AI의 탐색 능력보다 개발자의 코드베이스 이해가 더 중요한 영역입니다.
핵심 정리
- "전체 읽어줘" 금지 — Glob/Grep으로 관련 파일 목록 파악 후 필요한 파일만 선택적 로드, 컨텍스트 90% 절약
- CLAUDE.md 기능별 위치 가이드 — 어디서 무엇을 찾을지 명시해 불필요한 탐색 제거
- 대규모 마이그레이션은 우선순위 배치 처리 — 보안 민감도 순으로 분류 후 5개씩 처리, 각 배치마다 검증
관련 검색어 · 클로드 코드 대규모 프로젝트 · Claude Code 코드베이스 · AI 레거시 코드 · 클로드 코드 완벽 마스터 · 대규모 리팩터링 전략