본문으로 건너뛰기

대규모 코드베이스

코드베이스가 커질수록 Claude Code를 다루는 방식이 달라져야 합니다. 수만 줄, 수백 개의 파일로 이루어진 프로젝트에서 Claude Code를 효율적으로 활용하는 전략을 알아봅시다.

대규모 코드베이스의 도전​

작은 프로젝트와 달리 대규모 코드베이스에서는:

  1. 컨텍스트 한계 — 모든 파일을 한 번에 읽을 수 없음
  2. 코드 탐색 비용 — 관련 파일을 찾는 데 시간이 걸림
  3. 의도치 않은 영향 — 변경이 예상치 못한 곳에 영향을 줄 수 있음
  4. 일관성 유지 — 수백 개 파일에 걸쳐 패턴을 일관되게 유지해야 함

핵심 전략 1: CLAUDE.md로 길 안내​

대규모 프로젝트일수록 CLAUDE.md가 더욱 중요합니다. Claude가 매번 코드베이스를 탐색하지 않아도 되도록 핵심 정보를 제공합니다:

# 프로젝트 구조

## 핵심 디렉토리
- src/domain/    — 비즈니스 로직 (핵심)
- src/api/       — Express 라우터
- src/infra/     — DB, 외부 서비스 어댑터
- src/shared/    — 공용 유틸리티

## 절대 수정 금지 파일
- src/infra/database/migrations/ (자동 생성)
- src/shared/generated/ (코드 생성 결과물)

## 아키텍처 패턴
- 클린 아키텍처 (domain → application → infrastructure)
- 의존성 방향: 안쪽으로만 (infra → app → domain)
- 에러 처리: src/shared/errors/AppError.ts 사용

## 주요 엔트리포인트
- 새 기능 추가: src/domain/[기능명]/ 부터 시작
- 새 API: src/api/routes/[기능명].routes.ts

핵심 전략 2: 스코프 좁히기​

광범위한 요청 대신 구체적인 범위를 지정합니다:

# 나쁜 예 (전체 코드베이스 탐색)
> 성능 문제 찾아줘

# 좋은 예 (범위 한정)
> src/domain/order/ 디렉토리에서 N+1 쿼리 문제 찾아줘

# 더 좋은 예 (파일 지정)
> src/domain/order/order.repository.ts 에서
  쿼리 최적화할 부분 찾아줘

핵심 전략 3: 단계별 탐색​

낯선 대규모 코드베이스를 이해할 때:

# 1단계: 전체 구조 파악
> 이 프로젝트의 전체 디렉토리 구조를 설명해줘.
  핵심 모듈들의 역할을 요약해줘.

# 2단계: 특정 도메인 이해
> src/payment/ 모듈이 어떻게 동작하는지 설명해줘.
  주요 클래스들과 데이터 흐름을 중심으로.

# 3단계: 구체적인 작업
> PaymentService.processRefund() 메서드에 환불 한도 검증 로직 추가해줘.

핵심 전략 4: git 활용​

변경 범위를 git으로 추적합니다:

# 작업 전 스냅샷
git add . && git commit -m "chore: 작업 시작 스냅샷"

# Claude Code로 작업
claude "Order 모듈 전체 리팩토링해줘"

# 변경 범위 확인
git diff --stat        # 변경된 파일 목록
git diff               # 실제 변경 내용

# 의도치 않은 변경 발견 시 복구
git checkout src/config/  # 특정 디렉토리 복구

레거시 코드 현대화​

점진적 접근법​

레거시 코드는 한 번에 전부 바꾸지 말고 단계별로:

# 1단계: 이해
> src/legacy/order-processor.js 를 분석해줘.
  이 코드가 뭘 하는지, 어떤 패턴을 쓰는지 설명해줘.

# 2단계: 테스트 먼저
> 현재 동작을 보존하는 테스트 코드를 먼저 작성해줘.
  (리팩토링 전 안전망 확보)

# 3단계: 점진적 현대화
> ES5 문법을 ES2022로 업그레이드해줘.
  동작은 변경하지 말고, 문법만 현대화해줘.

# 4단계: 패턴 개선
> 콜백 지옥을 async/await로 변환해줘.
  테스트가 통과하는지 확인하면서 진행해줘.

타입 추가 (JavaScript → TypeScript)​

> src/services/cart.js 를 TypeScript로 변환해줘.
  any 타입은 최소화하고, 정확한 타입을 추론해줘.
  기존 동작은 변경하지 마.

코드베이스 분석 요청​

아키텍처 분석​

> 이 코드베이스의 아키텍처 다이어그램을 Mermaid 형식으로 그려줘.
  주요 모듈 간 의존성을 보여줘.
> 순환 의존성(circular dependency)이 있는 모듈 찾아줘.
  어떻게 해결할지 제안해줘.

코드 품질 분석​

> 중복 코드(코드 스멜)가 심한 파일 찾아줘.
  상위 5개 파일을 리팩토링 우선순위 순으로 알려줘.
> 이 프로젝트에서 가장 복잡한 함수 10개 찾아줘.
  복잡도 기준으로 정렬해줘.

보안 감사​

> 이 코드베이스에서 SQL 인젝션 취약점이 있을 수 있는 곳 찾아줘.
  raw query를 사용하는 모든 파일을 확인해줘.
> 환경변수 없이 하드코딩된 시크릿이 있는지 검사해줘.
  API 키, 비밀번호, 토큰 등을 찾아줘.

대규모 리팩토링 전략​

전사적 명칭 변경​

> 프로젝트 전체에서 "customerId"를 "clientId"로 변경해줘.
  DB 스키마, 타입 정의, API, 테스트 모두 포함.
  단, 외부 API와 통신하는 파일(src/integrations/)은 제외.

패턴 일관성 적용​

> src/api/ 디렉토리의 모든 라우터를 확인해줘.
  에러 처리 방식이 통일되지 않은 곳을 찾아서
  src/api/users/users.router.ts 의 패턴으로 통일해줘.

의존성 업그레이드​

> package.json에서 deprecated 패키지 확인해줘.
  대체 패키지를 제안하고, 마이그레이션 계획을 세워줘.

효율적인 작업 습관​

이미지 활용​

UI 관련 작업이면 스크린샷을 제공하세요. Claude Code는 이미지를 이해합니다:

> 이 스크린샷처럼 대시보드 레이아웃을 구현해줘

체크리스트 패턴​

복잡한 작업을 체크리스트로 분해하면 Claude가 빠뜨리지 않습니다:

> 인증 모듈 리팩토링:
  - [ ] 기존 테스트가 통과하는지 확인
  - [ ] 세션 기반 → JWT 토큰으로 변환
  - [ ] 미들웨어 업데이트
  - [ ] 테스트 추가
  - [ ] 마이그레이션 가이드 작성

검증 기준 미리 제공​

> getUserById 함수를 최적화해줘.
  성공 기준: 기존 테스트 모두 통과 + 응답시간 50% 단축

서브에이전트 활용​

복잡한 대규모 작업은 서브에이전트로 병렬 처리합니다:

> 다음 세 모듈을 독립적으로 리팩토링해줘:
  1. src/payment/ — 결제 로직 정리
  2. src/notification/ — 알림 시스템 개선
  3. src/reporting/ — 리포팅 모듈 최적화

  각 모듈이 서로 의존하지 않으므로 병렬로 진행해줘.

대규모 프로젝트 CLAUDE.md 템플릿​

# [프로젝트명]

## 빠른 참조
- 새 기능 추가: [경로] 참조
- 버그 수정: [경로] 참조
- DB 변경: 마이그레이션 실행 필수

## 금지 사항
- /src/generated/ 직접 수정 금지
- /config/production.* 수정 금지
- 외부 API 키 코드에 하드코딩 금지

## 코드 규칙
- [규칙 1]
- [규칙 2]

## 테스트 실행
- 단위: npm run test:unit
- 통합: npm run test:integration
- 전체: npm test

## 배포 전 체크리스트
- [ ] 테스트 통과
- [ ] 타입 체크 통과
- [ ] 린트 통과
- [ ] 마이그레이션 파일 포함 여부 확인

이 챕터를 완료하셨나요?

학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.