1. 레거시 코드베이스가 AI 에이전트를 망가뜨리는 이유
대규모 레거시 소스 코드베이스에 Claude Code 같은 AI 코딩 도구를 넣으면 매번 똑같은 문제가 터집니다. 새로운 대화 세션이 열릴 때마다 에이전트는 우리 회사의 도메인 지식, 커스텀 객체 관계 매핑, 에러 핸들링 규칙을 전혀 모른 상태로 시작합니다.
체계적인 아키텍처 제약 조건이 없는 상태에서 에이전트가 만든 코드는 사람이 직접 짠 코드보다 결함 발생률이 약 1.7배 높다는 분석 결과가 있습니다. 특히 로직 오류는 75퍼센트 늘어나고 보안 취약점 유발률도 2배까지 치솟습니다. 매번 처음부터 코드를 생성시키거나 엉뚱한 결과물을 수정하느라 토큰 비용만 날리게 됩니다.
이 문제를 해결하려면 프로젝트 디렉토리에 전용 설정 파일을 박아두어야 합니다. 프로젝트 루트에 CLAUDE.md 파일을 만들고 빌드 명령어, 테스트 명령어, 아키텍처 규칙을 직접 적어둡니다. 이 파일을 저장소에 커밋하면 에이전트가 구동될 때 자동으로 읽어 들입니다. 이 설정 하나만으로도 잘못 생성된 코드를 고치느라 날리는 시간을 주당 4시간 이상 아낄 수 있습니다.
2. 프로젝트 전용 컨벤션 파일로 문맥 고정하기
반복적인 문맥 재설명을 없애려면 계층화된 규칙 파일을 프로젝트 루트와 하위 디렉토리에 배치해야 합니다. Claude Code는 구동할 때 최상위 글로벌 설정부터 프로젝트 루트, 하위 디렉토리 순서로 설정 파일을 읽어 하나의 시스템 프롬프트로 병합합니다.
온보딩 시 자동 생성되는 3,847토큰짜리 거대한 명세서를 필수 규칙 중심의 312토큰 모듈형 구조로 줄였을 때, 지시 이행 정확도는 그대로 유지하면서 매 턴마다 소모되는 초기 토큰 비용을 91.9퍼센트 절감할 수 있습니다.
실제 설정 파일은 이렇게 만듭니다.
- 루트 디렉토리에
CLAUDE.md파일을 만들고 빌드 명령어와 데이터베이스 접근 금지 규격을 200줄 이내의 명령조로 적습니다. - 프론트엔드와 백엔드 디렉토리 경계에 하위 규칙 파일을 나누어 조건에 따라 동적으로 로드되도록 설정합니다.
- 세션 시작 시 파일이 정상적으로 합쳐지는지 확인하고 에이전트의 지시 이행 정확도를 테스트합니다.
사내 비즈니스 로직과 아키텍처 규칙을 에이전트에 영구적으로 주입하면 할루시네이션을 원천 차단할 수 있습니다.
3. 공통 라이브러리 레퍼런스 인덱스 구축하기
레거시 시스템의 데이터베이스 스키마와 공통 유틸리티 라이브러리를 에이전트에 먹일 때는 전체 소스 코드를 통째로 읽히면 안 됩니다. 불필요한 구현 상세가 컨텍스트 윈도우를 채워 토큰을 낭비하고 추론 성능을 떨어뜨립니다.
복잡한 코드베이스에 정적 인덱스와 메서드 시그니처 컨텍스트 주입 방식을 적용했을 때 컴파일 및 모듈 통합 오류가 최대 87.5퍼센트까지 줄어든다는 연구 결과가 있습니다.
정적 인덱스 디렉토리를 만드는 방법은 다음과 같습니다.
- 소스 코드에서 함수 시그니처, 클래스 정의, 타입 별칭만 뽑아내는 TypeScript 스크립트를 작성합니다.
- 추출한 결과물을
.claude/reference-index.md파일로 저장해 표준 라이브러리와 사내 구현체를 매핑하는 대조 테이블을 완성합니다. - 신규 기능을 짤 때 에이전트가 코드를 쓰기 전에 기존 심볼 테이블과 인터페이스 정의를 먼저 확인하도록 워크플로우를 고정합니다.
이 방식을 쓰면 신규 코드가 기존 모듈과 충돌하거나 중복될 확률을 80퍼센트 이상 줄일 수 있습니다.
4. 토큰 폭탄을 막는 컨텍스트 압축과 필터링
에이전트가 파일을 탐색할 때 발생하는 불필요한 토큰 소비를 막으려면 .claudeignore 파일과 모노레포 스킵 옵션인 claudeMdExcludes를 설정해야 합니다.
실세션 추적 데이터에 따르면 초기 14개 토큰으로 구성된 단문 요청의 처리 비용은 약 0.0018달러지만, 대화가 260회차까지 쌓인 상태에서는 동일한 요청 1건에 2.41달러가 소모되어 약 1,339배의 비용 인플레이션이 발생합니다.
토큰 비용을 잡으려면 세 가지를 적용합니다.
- 프로젝트 루트에
.claudeignore파일을 만들고node_modules, 빌드 아티팩트, 로그 파일, 정적 이미지 디렉토리를 탐색 대상에서 완전히 제외합니다. - 모노레포 환경의
.claude/settings.json내에claudeMdExcludes패턴을 적어 불필요한 하위 패키지의 마크다운 설정 파일 로딩을 차단합니다. - 작업 단위가 바뀔 때마다 세션을 완전 초기화하고 대형 파일 분석은 하위 에이전트에 위임해 프롬프트 캐시 효율을 유지합니다.
이 설정만 지켜도 API 토큰 비용을 최대 70퍼센트까지 아낄 수 있습니다.
5. 로컬 테스트와 정적 분석 도구 연동하기
설명 파일만으로는 에이전트의 규칙 준수율이 약 70퍼센트 수준에 머무릅니다. 강제성 있는 규칙 준수를 이끌어내려면 결정론적 셸 실행 후크 파이프라인을 붙여야 합니다.
Claude Code의 훅 시스템은 이벤트가 발생할 때 제이슨 데이터를 받아 검증 스크립트를 실행하고, 종료 코드를 통해 도구 호출 허용 여부를 결정합니다. 자동화 검증 파이프라인을 붙이면 배포 전 수동 코드 리뷰 및 디버깅 소요 시간을 절반 수준으로 줄일 수 있습니다.
자가 치유 파이프라인을 구축하는 절차는 다음과 같습니다.
.claude/settings.json설정 파일의hooks블록에PreToolUse매처를 등록해 파괴적 명령과 설정 파일 무단 수정을 차단합니다.PostToolUse이벤트에 에이전트가 파일을 고친 직후 정적 분석 린터와 단위 테스트가 바로 돌도록 훅 명령어를 설정합니다.- 테스트가 실패하면 에러 출력이 에이전트 컨텍스트로 다시 들어가도록 구성해 개발자가 직접 개입하지 않아도 코드가 스스로 고쳐지도록 피드백 루프를 완성합니다.
