AI 코딩 에이전트의 블랙박스를 해결하는 로컬 프록시 도구: Preflight Context

실용적 조언

에이전트의 API 엔드포인트를 localhost:3131로 변경하면 즉시 요청 검토 모드를 활성화할 수 있다.
토큰 카운트가 급격히 올라갈 때 대시보드에서 불필요한 파일 블록을 삭제하여 비용을 절감하라.

섹션별 상세

작성자는 코딩 에이전트가 사용자의 의도와 무관하게 무분별하게 파일을 전송하거나 토큰을 과다 소비하는 문제를 지적했다. 이를 해결하기 위해 에이전트와 API 서버(Anthropic, OpenAI) 사이에 위치하여 요청을 가로채는 로컬 프록시 서버를 구축했다. 사용자는 localhost:3131로 엔드포인트를 설정하여 에이전트의 출력을 제어할 수 있다. 이 도구는 에이전트가 보이지 않는 곳에서 수행하는 작업을 투명하게 공개하는 데 목적이 있다.

프록시 서버는 요청을 가로챈 후 전용 브라우저 대시보드 UI를 통해 상세 정보를 노출한다. 사용자는 이 UI에서 포함된 모든 파일 블록과 프롬프트를 확인하고, 예상 토큰 수와 비용을 실시간으로 파악할 수 있다. 불필요한 컨텍스트를 삭제하거나 내용을 직접 편집한 뒤 전송 버튼을 누르면 그제야 실제 API로 요청이 전달된다. 에이전트는 중간에 개입이 있었다는 사실을 인지하지 못한 채 정상적으로 동작을 이어간다.

도구는 특정 조건에서 요청을 자동으로 일시 중지하여 사용자의 검토를 유도한다. 요청에 도구 호출(Tool use)이 포함되어 있지 않거나 토큰 수가 설정된 임계치를 넘었을 때 이를 '최종 응답 생성 직전'으로 판단하고 프로세스를 멈춘다. 이러한 메커니즘을 통해 사용자는 모델이 최종 답변을 내놓기 전 입력 데이터의 품질을 마지막으로 점검할 수 있다.

실제 사용 결과, 에이전트가 때때로 작업과 전혀 상관없는 파일을 컨텍스트에 집어넣는 사례가 빈번함이 확인됐다. 지저분한 컨텍스트는 모델의 '나쁜 답변'으로 이어지는 핵심 원인이 되며, 이를 시각화하는 것만으로도 디버깅 효율이 상승한다. 또한 인증 헤더를 그대로 유지하고 응답 스트리밍을 지원하여 기존 워크플로우를 해치지 않으면서도 비용 최적화가 가능하다.

용어 해설

컨텍스트 윈도우(Context Window): — LLM이 한 번의 추론 과정에서 처리할 수 있는 입력 데이터의 총량입니다. 에이전트가 불필요한 파일이나 긴 대화 기록을 포함하면 윈도우가 가득 차서 비용이 급증하고 모델의 추론 성능이 저하될 수 있습니다.
토큰 사용량(Token Usage): — AI 모델이 텍스트를 처리하는 기본 단위인 토큰의 소비량입니다. 코딩 에이전트는 수많은 파일을 컨텍스트에 포함하므로 토큰 사용량이 급격히 늘어나며, 이는 곧 API 호출 비용과 직결됩니다.
API 프록시(API Proxy): — 클라이언트와 서버 사이에서 통신을 중계하는 중간 서버입니다. 이 프로젝트에서는 에이전트와 LLM API 사이에서 요청을 가로채 사용자가 내용을 검토하고 수정할 수 있는 인터페이스를 제공합니다.

언급된 도구

Preflight Context추천링크

LLM API 요청 전 컨텍스트 검토 및 편집 프록시

언급된 리소스

GitHubPreflight Context GitHub Repository