대규모 코드베이스에 Claude Code를 도입하는 엔터프라이즈 설계

전체 저장소를 읽히는 방식은 오래가지 못한다

수십만 줄 규모의 코드베이스에서는 컨텍스트 윈도우부터 한계에 닿는다. Claude가 200K 토큰의 컨텍스트 윈도우를 제공하더라도 저장소 전체를 한 번에 담을 수는 없다. 설령 가능하더라도 관련 없는 코드가 모델의 주의를 분산하므로 좋은 선택이 아니다.

핵심은 현재 작업에 필요한 코드만 정밀하게 고르는 데 있다. Anthropic의 공식 가이드도 전체 로딩보다 관련 파일을 선택하고, 작업 중 필요한 내용을 점진적으로 불러오는 방식을 권장한다.

CLAUDE.md에서 자동 인덱스까지

탐색의 첫 단서는 CLAUDE.md다. 핵심 디렉터리 구조와 주요 파일 위치, 도메인 개념이 구현된 코드의 위치를 이 파일에 기록하면 에이전트가 저장소를 훨씬 빠르게 좁혀갈 수 있다.

그다음 레이어는 자동화된 파일 인덱싱이다. AST(Abstract Syntax Tree)를 분석해 함수·클래스·모듈의 의존성 그래프를 만들고, 변경 대상과 연결된 파일을 추적한다.

class CodebaseIndexer:
    def __init__(self, root_path: str):
        self.root = root_path
        self.dependency_graph = {}
        self.symbol_index = {}

    def build_index(self):
        for filepath in self._iter_source_files():
            ast_tree = self._parse_file(filepath)
            symbols = self._extract_symbols(ast_tree)
            deps = self._extract_dependencies(ast_tree)

            for symbol in symbols:
                self.symbol_index[symbol.qualified_name] = filepath

            self.dependency_graph[filepath] = deps

    def get_relevant_files(self, task_description: str, seed_files: list[str]) -> list[str]:
        """작업 설명과 시드 파일로부터 관련 파일 집합을 확장한다."""
        relevant = set(seed_files)

        # (1) 직접 의존하는 파일 추가
        for seed in seed_files:
            relevant.update(self.dependency_graph.get(seed, []))

        # (2) 해당 파일에 의존하는 파일 추가 (역방향)
        for filepath, deps in self.dependency_graph.items():
            if any(seed in deps for seed in seed_files):
                relevant.add(filepath)

        # (3) 토큰 예산 내에서 중요도 순으로 정렬하여 반환
        return self._rank_by_relevance(list(relevant), task_description)

컨텍스트는 계층적으로 채운다

컨텍스트 예산은 비용뿐 아니라 결과 품질에도 영향을 준다. 처음부터 모든 자료를 싣는 대신 작업에 가까운 정보부터 배치한다.

항상 포함할 첫 번째 레이어에는 CLAUDE.md, 현재 수정하는 파일과 직접 의존 파일을 넣는다. 이 범위는 약 10K-30K 토큰이다. 두 번째 레이어에는 작업 성격에 맞춰 테스트 파일, 관련 인터페이스 정의와 유사 구현 예시를 추가하며 약 20K-50K 토큰을 사용한다.

세 번째 레이어는 고정하지 않는다. 에이전트가 작업 중 참조할 필요가 있다고 판단한 파일을 MCP 도구로 불러오고, 앞선 레이어가 차지한 컨텍스트를 기준으로 포함 여부를 결정한다. 에이전트가 스스로 필요한 파일을 요청할 수 있어야 이 방식이 작동한다.

도메인 언어와 코드 위치를 연결한다

파일 의존성만으로는 비즈니스 의미를 충분히 표현하기 어렵다. 여기에 도메인 개념과 코드 구조를 잇는 지식 그래프를 더할 수 있다.

가령 ‘사용자 인증’이 AuthService, JWTHelper, UserRepository, LoginController와 연결되어 있다면 인증 작업을 시작할 때 이 파일들을 시드 컨텍스트로 삼을 수 있다. CLAUDE.md에 사람이 기록한 지식과 자동 코드 분석 결과를 결합하는 방식이다.

⤢✕

엔터프라이즈 도입은 권한 모델에서 시작한다

개인 저장소에서는 에이전트가 넓은 권한을 가져도 문제가 드러나지 않을 수 있다. 여러 팀이 저장소와 민감 정보를 공유하는 환경에서는 이야기가 달라진다. 모든 개발자가 모든 코드에 같은 수준으로 에이전트를 사용할 수 있게 해서는 안 된다.

역할 기반 접근 제어에는 세 가지 원칙이 필요하다. 에이전트가 볼 수 있는 파일은 해당 개발자의 권한 범위를 넘어서는 안 된다. 보안 모듈, 결제 처리와 개인정보 처리처럼 민감한 코드에 접근할 때는 추가 승인을 거쳐야 한다. 에이전트가 만든 모든 변경은 일반 코드와 같은 리뷰 절차를 통과해야 한다.

# 엔터프라이즈 Claude Code 접근 정책 설정 예시
access_policy = ClaudeCodePolicy(
    team="backend-team",
    allowed_repos=["api-server", "shared-libs"],
    restricted_paths=[
        "/src/payment/",     # 결제 관련: 별도 승인 필요
        "/src/auth/crypto/", # 암호화 모듈: 보안팀 승인 필요
        "/config/secrets/"   # 시크릿 설정: 에이전트 접근 차단
    ],
    require_review_for_patterns=[
        "*.sql",  # SQL 변경은 반드시 DBA 리뷰
        "Dockerfile",
        "*.tf"    # Terraform 변경은 인프라팀 리뷰
    ],
    max_session_tokens=150_000,  # 세션당 토큰 상한
    daily_token_budget=500_000   # 팀원당 일일 예산
)

비용을 팀·프로젝트·개인 단위로 추적한다

Claude Code 비용은 토큰 사용량에 비례하므로 사용자가 늘어날수록 할당 기준이 필요해진다. 기본 단위는 팀, 프로젝트, 개인의 세 레벨이다. 팀에는 월간 예산을 두고, 프로젝트에는 사용할 수 있는 에이전트 비용을 배분하며, 개인 단위에서는 일일 사용량을 확인한다.

작업에 맞는 모델을 선택하는 것도 비용 관리의 일부다. 파일 검색, 코드 포맷팅과 단순 변수명 변경은 작은 모델에 맡기고, 복잡한 아키텍처 설계나 버그 분석에는 최고 품질 모델을 사용한다.

반복되는 코드베이스 컨텍스트는 캐싱 대상으로 볼 수 있다. CLAUDE.md와 핵심 인터페이스 파일처럼 여러 작업에서 공통으로 읽는 자료를 재사용하면 같은 내용을 계속 불러오는 비효율을 줄일 수 있다.

보안 검사를 배포 흐름 안에 둔다

에이전트가 만든 코드도 프로덕션에 들어가기 전 자동 보안 검사를 거쳐야 한다. CI/CD 파이프라인에 보안 게이트를 두고, 검사 결과에 따라 자동 수정이나 보안팀 검토로 분기한다.

⤢✕

AI가 만든 변경에는 추적 가능한 메타데이터를 남길 수 있다. 커밋에 Co-Authored-By: claude-code를 포함하면 감사 과정에서 AI 생성 코드를 식별할 수 있다. 금융과 의료처럼 AI 사용 내역을 보고해야 하는 규제 산업에서 필요한 기록이다.

저장소 사용법을 문서화하는 일이 먼저다

Anthropic 공식 가이드에서 가장 먼저 챙길 대상은 CLAUDE.md다. 프로젝트 구조와 코딩 관례, 도메인 용어집, 반복되는 실수와 해결책을 기록해 두면 에이전트에게 같은 배경을 매번 다시 설명하는 비용을 줄일 수 있다. 이 문서는 단순 안내 파일이 아니라 에이전트 성능을 떠받치는 기반이다.

작업 크기도 결과를 크게 바꾼다. “전체 인증 시스템을 리팩터링해줘”처럼 넓은 요청보다 결과를 검증할 수 있는 작은 단위로 나누는 편이 안정적이다.

코드를 바꾸기 전에 테스트부터 작성하는 TDD 흐름도 에이전트와 잘 맞는다. 변경 이후 기존 동작이 깨졌는지를 자동으로 확인할 수 있기 때문이다. 다만 테스트가 인간 검토를 대신하지는 않는다. 에이전트는 초안을 빠르게 만들고, 사람은 설계 판단과 보안 영향을 검토하는 역할을 맡는다.

조직 전체에 즉시 확산하기보다 작은 파일럿 팀에서 시작한다. 6-8주의 파일럿 기간에 생산성과 품질 변화를 측정하고, 그 결과를 전사 적용 계획에 반영한다. 공식 가이드의 권장사항은 CLAUDE.md에 대한 투자, 작은 작업 단위, 테스트 우선, 단계적 도입, 인간 검토 유지라는 다섯 가지로 모인다.

멀티 에이전트는 작업 경계가 선명해야 한다

대규모 작업에서는 오케스트레이터가 과업을 분리하고 전문 에이전트들이 병렬로 처리한 뒤 결과를 통합하는 패턴을 쓸 수 있다. 병렬화 자체보다 각 에이전트가 어디까지 책임지는지를 분명히 하는 일이 먼저다.

대표적인 실패는 공유 파일 충돌이다. 두 에이전트가 같은 파일을 동시에 수정하면 충돌이 생기므로 에이전트 사이에 파일 잠금(file locking) 메커니즘을 둬야 한다.

실행 시간이 길어질수록 컨텍스트 드리프트도 경계해야 한다. 에이전트가 처음 받은 지시에서 벗어나 작업 범위를 예상하지 못한 방향으로 넓힐 수 있다. 범위를 명시하고 중간 체크포인트를 두어 진행 방향을 확인한다.

도입 효과는 속도만으로 판단하지 않는다

Claude Code의 ROI는 코드 작성 속도, 버그 도입률, 개발자 만족도라는 세 가지 지표로 측정한다. 코드 작성 속도는 실제 변경이 나오기까지 걸린 시간으로, 버그 도입률은 에이전트 생성 코드의 결함 밀도로 본다. 개발자 만족도는 설문으로 확인한다.

초기 파일럿에서는 일반적으로 코드 작성 속도가 30-50% 향상되고 보일러플레이트 코드 관련 버그가 줄어든다. 반면 복잡한 비즈니스 로직에서는 에이전트를 감독하는 데 추가 시간이 필요하다.

Cursor와 GitHub Copilot이 주로 코드 완성과 제한된 에디터 통합을 제공한다면, Claude Code는 터미널 명령 실행, 파일 시스템 조작과 멀티턴 복잡 작업을 수행하는 완전 자율 에이전트라는 강점이 있다. IDE 통합 경험은 약점이다. Cursor의 에디터 내 흐름이 더 매끄럽고, 특히 코드 완성 속도는 Claude Code보다 빠르다.

대규모 코드베이스에서 Claude Code를 운영하는 일은 모델 사용법만의 문제가 아니다. 접근 권한, 비용 할당, 코드 리뷰와 보안 정책을 에이전트가 참여하는 개발 흐름에 맞춰 다시 설계해야 한다. CLAUDE.md 투자, 점진적인 작업 분할, TDD 통합과 단계적 도입이라는 네 가지 원칙이 그 설계의 출발점이다.