LLM 코드베이스 드리프트는 모델이 기존 아키텍처, 네이밍, 테스트 전략, 운영 제약을 잊고 그럴듯하지만 낯선 코드를 추가하는 문제다. 프로덕션 코드에서는 “동작하는 코드”보다 “기존 시스템 안에서 유지보수 가능한 코드”가 중요하므로 드리프트 방지 장치가 필요하다.

실전 원칙

첫째, 프로젝트 규칙을 한곳에 둔다. CLAUDE.md, AGENTS.md, skills, repo docs처럼 에이전트가 매번 읽는 파일에 금지 패턴, 테스트 명령, 설계 의도를 적는다.

둘째, 작업 단위를 줄인다. 큰 기능을 한 번에 맡기면 모델은 빈칸을 상상으로 채운다. 파일 범위, 성공 조건, 변경하지 말아야 할 영역을 좁게 준다.

셋째, 검증을 출력이 아니라 명령으로 고정한다. lint, typecheck, unit test, screenshot, API smoke test처럼 재현 가능한 검증을 끝 조건으로 삼아야 한다.

넷째, 코드베이스 탐색을 먼저 시킨다. “비슷한 패턴을 찾아서 그대로 따르라”는 지시가 추상적 선호보다 강하다.

팀에서 적용할 때

드리프트 방지는 프롬프트 기술만으로 해결되지 않는다. PR 템플릿, 코드리뷰 체크리스트, 테스트 커버리지, 에이전트용 문서가 함께 있어야 한다. 특히 코드 생성 에이전트를 장기간 쓰는 팀은 “왜 이 패턴을 쓰는지”를 문서화해야 새 세션에서도 같은 판단을 반복할 수 있다.

관련 문서

• context-engineering-tutorial-python-codebases — Python 코드베이스에서 에이전트 컨텍스트 관리하기
• claude-code-tips-steering — CLAUDE.md·Rules·Skills·Subagents·Hooks로 동작 제어하기
• verification-driven-tooling-tips — 검증 가능한 도구 사용으로 에이전트 실패 줄이기

참고 자료

• How I Stop LLMs Drifting In Production Codebases — Scott Spence (2026-06)