컨텍스트 블로트 줄이는 법: AI 에이전트가 필요한 파일만 읽게 만드는 실무 운영법

AI 에이전트가 레포를 다 읽으면 더 잘할 것 같지만, 실제로는 반대인 경우가 많습니다. 불필요한 파일, 오래된 문서, 중복된 로그, 관련 없는 테스트 결과가 컨텍스트에 섞이면 모델은 중요한 신호를 놓칩니다. 이 문제를 흔히 컨텍스트 블로트라고 부릅니다.

컨텍스트 블로트는 단순히 토큰 비용 문제만이 아닙니다. 잘못된 파일을 근거로 수정 계획을 세우고, 이미 폐기된 API를 최신 규칙처럼 믿고, 서브에이전트 로그를 사실로 착각하는 문제가 생깁니다. AI 코딩 도구를 팀에 넣을수록 “무엇을 넣을지”보다 “무엇을 빼야 할지”가 중요해집니다.

이 글은 실무 개발팀이 컨텍스트 블로트를 줄이는 방법을 정리합니다. 핵심은 파일 읽기 정책, 스키마 프루닝, 작업 메모리 분리, 서브에이전트 로그 관리입니다.

컨텍스트에 많이 넣는다고 정확도가 올라가지 않습니다

모델은 컨텍스트 안의 모든 정보를 같은 방식으로 검증하지 않습니다. 관련 없는 정보가 많아지면 중요한 제약 조건이 묻힙니다. 예를 들어 결제 webhook 버그를 고치는데 2년 전 마이그레이션 문서, 다른 서비스의 결제 코드, 실패한 실험 로그까지 들어가면 모델은 어느 것이 현재 사실인지 헷갈릴 수 있습니다.

좋은 컨텍스트는 많은 컨텍스트가 아니라 선별된 컨텍스트입니다. 작업에 필요한 현재 파일, 관련 테스트, 최근 변경 이력, 명시적 제약 조건만 우선 넣어야 합니다. 나머지는 필요할 때 검색하게 하면 됩니다.

팀에서는 AI 작업 시작 전에 다음 질문을 던지면 좋습니다.

이 작업의 진짜 대상 파일은 무엇인가
현재 동작을 검증하는 테스트는 어디에 있는가
오래된 문서와 최신 문서를 구분할 수 있는가
모델이 절대 바꾸면 안 되는 파일은 무엇인가
실패 로그 중 재현 가능한 로그만 남겼는가

이 질문 없이 “전체 레포 읽고 고쳐줘”라고 하면 결과가 흔들립니다.

파일 읽기 정책을 명시합니다

AI 에이전트에게 파일 읽기를 맡길 때는 정책이 있어야 합니다. 사람이 코드 리뷰할 때도 모든 파일을 같은 깊이로 보지 않습니다. 에이전트도 마찬가지입니다.

스키마 프루닝으로 도구 응답을 줄입니다

MCP 서버나 내부 API를 AI에 붙이면 응답이 너무 커지는 문제가 생깁니다. 이슈 하나를 조회했는데 댓글, 이벤트, 라벨, 작성자 프로필, 첨부 파일 메타데이터까지 모두 들어오면 모델은 정작 필요한 제목과 재현 단계에 집중하기 어렵습니다.

스키마 프루닝은 도구 응답에서 필요한 필드만 남기는 방식입니다. 예를 들어 이슈 분류 작업이라면 필요한 필드는 title, body, labels, createdAt, linkedPR 정도일 수 있습니다. 사용자 프로필 전체나 모든 이벤트 히스토리는 필요 없습니다.

실무 기준은 다음처럼 잡습니다.

도구별 기본 응답 필드를 최소화합니다.
상세 정보는 별도 도구로 늦게 가져옵니다.
긴 본문은 요약본과 원문 링크를 분리합니다.
배열은 기본 20개 이하로 제한합니다.
모델이 쓸 수 없는 메타데이터는 제거합니다.
개인정보와 토큰은 응답 전에 마스킹합니다.

프루닝은 정확도와 보안을 동시에 개선합니다. 모델이 볼 필요 없는 정보는 애초에 주지 않는 것이 가장 안전합니다.

서브에이전트 로그를 사실과 의견으로 나눕니다

여러 AI 에이전트를 쓰면 서브에이전트 로그가 쌓입니다. 문제는 이 로그가 사실, 추정, 실패한 가설, 임시 계획을 섞어 담는다는 점입니다. 메인 에이전트가 이 로그를 그대로 믿으면 잘못된 전제를 이어받을 수 있습니다.

서브에이전트 결과는 최소한 네 칸으로 나눠 받아야 합니다.

확인한 사실: 파일, 명령, 응답처럼 검증 가능한 내용
추정: 근거는 있지만 아직 확인하지 않은 판단
변경 사항: 실제로 수정한 파일과 이유
남은 리스크: 테스트 미실행, 접근 불가, 불확실한 부분

이렇게 나누면 메인 에이전트가 “확인된 정보”만 근거로 다음 작업을 할 수 있습니다. 특히 긴 작업에서는 working buffer와 최종 보고를 분리하는 것이 좋습니다. 작업 중 생각을 모두 최종 컨텍스트에 넣으면 블로트가 생깁니다.

컨텍스트 예산을 운영 지표로 봅니다

토큰 수를 비용 지표로만 보면 아쉽습니다. 컨텍스트 예산은 품질 지표이기도 합니다. 같은 작업을 해결하는 데 매번 거대한 컨텍스트가 필요하다면 레포 구조나 문서 구조가 정리되지 않았다는 신호일 수 있습니다.

팀에서 볼 만한 지표는 다음과 같습니다.

작업당 읽은 파일 수
실제 수정한 파일 대비 읽은 파일 비율
실패한 가설 수
오래된 문서 때문에 생긴 수정 회수
도구 응답 평균 크기
서브에이전트 결과 중 검증 불가 항목 수

이 지표를 엄격하게 자동화할 필요는 없습니다. 큰 작업이 끝난 뒤 “이번 작업에서 불필요하게 읽은 파일은 무엇이었나”만 기록해도 다음 작업 품질이 올라갑니다.

실행 체크리스트

컨텍스트 블로트를 줄이는 목적은 모델을 굶기는 것이 아닙니다. 필요한 정보를 더 선명하게 주기 위한 것입니다. 오늘 할 수 있는 가장 쉬운 조치는 레포 루트에 AI 작업용 컨텍스트 가이드를 만들고, 읽기 우선순위와 제외 폴더를 적는 것입니다.

마지막 체크리스트입니다.

AI 작업 시작 시 대상 파일, 테스트, 제약 조건을 먼저 정의하는가
엔트리 파일, 직접 의존 파일, 검증 파일 순서로 읽게 하는가
generated, build, backup, lock 파일을 기본 제외하는가
MCP 도구 응답에서 필요한 필드만 남기는가
긴 배열과 로그에 기본 제한을 두는가
서브에이전트 결과를 사실, 추정, 변경, 리스크로 나누는가
오래된 문서와 최신 문서를 구분하는 표시가 있는가
작업 후 불필요하게 읽은 파일을 기록하는가