컨텍스트 오염이 AI 코딩을 망친다

AI 코딩 도구를 쓰면서 이런 경험이 있을 겁니다. 분명히 요구사항을 잘 썼는데, 결과물이 이상합니다. 없는 함수를 호출하거나, 이미 바꾼 방식 대신 옛날 패턴을 따라 하거나, 전혀 관련 없는 파일의 스타일을 흉내 냅니다.

프롬프트를 잘못 쓴 게 아닙니다. AI가 참조한 정보가 오염된 겁니다.

바이브마피아클럽 뉴스레터가 이 문제를 '컨텍스트 오염Context Contamination​'이라는 이름으로 짚었습니다. AI 코딩의 신뢰도를 떨어뜨리는 가장 흔한 원인인데, 대부분의 사람이 프롬프트 쪽만 고민하고 이쪽은 신경을 안 씁니다.

프롬프트가 아니라 참조 파일이 문제입니다

AI 코딩 에이전트는 이런 순서로 작동합니다. 사용자의 요구사항을 이해하고, 관련 파일과 지침을 탐색한 다음, 구현을 시작합니다. 핵심은 두 번째 단계입니다. AI가 코드를 쓰기 전에 프로젝트 안의 파일을 뒤져서 참고 자료를 모읍니다.

이때 무관한 파일이나 잘못 구현된 파일을 참조하면, 그 정보가 컨텍스트를 오염시킵니다. 아무리 요구사항을 정교하게 썼어도, AI가 참조하는 파일에 쓰레기가 섞여 있으면 결과도 오염됩니다.

Chroma Research의 데이터가 이걸 수치로 보여줍니다. 무관한 정보가 컨텍스트에 포함되면 결과 정확도가 약 10% 하락합니다. 잘못된 정보가 포함되면 30% 이상 하락합니다. 토큰을 많이 소모하는 복잡한 작업일수록 더 심해져서, 최대 70%까지 떨어질 수 있습니다.

컨텍스트 윈도우가 아무리 커져도 소용없습니다. 창고가 크다고 좋은 게 아니라, 창고 안에 뭐가 들어 있느냐가 중요합니다.

첫 번째 원칙: AI에게 지도를 줘야 합니다

AI 에이전트는 코드베이스를 탐색할 때 모든 파일을 다 읽지 않습니다. 관련 있어 보이는 파일을 검색해서 찾아갑니다. 문제는 이 탐색이 정확하지 않다는 겁니다. 엉뚱한 파일을 참조하거나, 필요한 파일을 못 찾는 경우가 많습니다.

해결책은 폴더 구조를 문서로 정리하는 것입니다. 프로젝트 루트에 AGENTS.md(또는 CLAUDE.md) 파일을 만들어서 주요 폴더의 역할과 파일 간 관계를 적어둡니다.

단순한 폴더 목록이 아닙니다. "components 폴더에는 재사용 UI 컴포넌트가 있고, pages에서 이를 import해서 사용한다" 같은 수준의 관계 설명이 필요합니다. 사람이 새로 합류했을 때 "이 프로젝트 구조가 어떻게 되어 있어?"라고 물으면 설명해줄 내용을 글로 쓰면 됩니다.

이 문서가 AI에게 지도 역할을 합니다. 지도 없이 도시를 돌아다니면 엉뚱한 골목으로 빠지는 것처럼, 구조 문서 없이 AI가 코드베이스를 탐색하면 무관한 파일을 끌어옵니다.

두 번째 원칙: AI가 검색하는 방식을 이해해야 합니다

AI 에이전트는 내부적으로 문자열 검색을 통해 파일을 탐색합니다. 프롬프트에 적힌 단어를 기반으로 관련 파일을 찾아갑니다.

그래서 프롬프트에 실제 코드에서 사용하는 용어를 그대로 써야 합니다.

"버튼 클릭 시 동작을 변경해줘"라고 쓰면 AI는 "버튼", "클릭", "동작" 같은 일반적인 단어로 검색합니다. 관련 없는 파일까지 잔뜩 끌려옵니다. 프로젝트 안에 '버튼'이라는 단어가 포함된 파일이 수십 개일 수 있으니까요.

"SubmitButton 컴포넌트의 onClick 핸들러를 수정해줘"라고 쓰면 AI는 SubmitButton과 onClick이라는 정확한 식별자로 파일을 찾아갑니다. 탐색 범위가 좁아지고, 무관한 파일이 끼어들 확률이 급격히 줄어듭니다. 실행 속도도 빨라집니다.

변수명, 클래스명, 함수명, 파일명을 프롬프트에 직접 명시하는 습관. 이것만으로도 체감 품질이 달라집니다. AI의 검색 정확도를 높이는 가장 쉬운 방법입니다.

세 번째 원칙: 안 쓰는 코드는 반드시 지워야 합니다

실무 프로젝트에서 가장 많이 어기는 원칙입니다.

사용하지 않는 파일, 주석 처리된 옛날 코드, 라이브러리 구버전 기준으로 작성된 코드가 프로젝트에 남아 있으면 어떻게 될까요. AI는 이런 코드도 유효한 참고 자료로 인식합니다. 구버전 API 패턴을 따라 하거나, 더 이상 존재하지 않는 함수를 호출하는 코드를 생성합니다.

특히 위험한 타이밍이 있습니다. 라이브러리 메이저 업데이트 직후입니다. Next.js 14에서 15로 올렸는데 14 방식의 코드가 프로젝트에 남아 있다면, AI는 높은 확률로 14 방식을 따라 합니다. 프로젝트에 더 많이 존재하는 패턴을 참조하기 때문입니다. 빌드가 깨지거나 런타임 에러가 나고, 수정하느라 시간을 허비합니다.

"나중에 쓸 수 있으니까 남겨두자"는 AI 시대에 가장 비싼 습관입니다. Git에 이력이 전부 남아 있습니다. 지금 사용하지 않는 코드는 과감하게 삭제해야 합니다.

사람에게 좋은 코드가 AI에게도 좋습니다

세 가지 원칙을 다시 정리하면 이렇습니다.

폴더 구조를 문서화해서 AI에게 지도를 줍니다. 프롬프트에 실제 코드 용어를 써서 AI의 검색 정확도를 높입니다. 미사용 코드를 삭제해서 AI가 참조할 쓰레기를 없앱니다.

결국 AI가 길을 잃지 않고, 잘못된 정보를 밟지 않도록 하는 것입니다.

흥미로운 건, 이 원칙들이 AI 이전에도 좋은 개발 관행이었다는 점입니다. 폴더 구조 문서화는 신규 팀원 온보딩을 위해 원래 해야 하는 일이었습니다. 명확한 네이밍은 코드 리뷰에서 늘 강조되던 것이었습니다. 미사용 코드 삭제는 기술 부채 관리의 기본이었습니다.

AI 도구를 도입한다고 해서 새로운 규칙이 필요한 게 아닙니다. 원래 지켜야 했던 규칙이 AI 시대에 더 중요해진 겁니다. 사람이 읽기 좋은 코드베이스가 AI도 잘 읽습니다. 사람이 헷갈리는 코드베이스에서 AI도 헷갈립니다.

AI를 잘 쓰고 싶다면, 에이전트 세팅이나 프롬프트 기법을 파기 전에 코드베이스부터 정돈해야 합니다. 가장 단순하고, 가장 효과가 큰 방법입니다.