코딩 에이전트 구축을 위한 8K 컨텍스트: 플래너/실행기 분할, 토큰 예산 및 병렬 실행

대부분의 AI 코딩 도구는 200k 토큰 모델을 가정하지만, Ollama, LM Studio 또는 Groq나 OpenRouter 같은 무료 티어 API를 통해 로컬 LLM을 실행하는 경우 약 8k 토큰으로 제한됩니다. 이는 전체 프로젝트에 적합하지 않으며, 큰 파일 하나도 간신히 처리할 수 있습니다. 한 개발자가 이 제약 조건에 맞춰 CLI 에이전트를 구축하는 데 몇 주를 보냈고, 실용적인 교훈을 공유했습니다.

핵심 아키텍처: 플래너/실행자 분할

에이전트는 LLM에 전체 프로젝트를 보여주지 않습니다. 대신 작업을 세 가지 역할로 분할합니다:

• 플래너: 각 폴더의 마크다운 요약(총 약 300~500 토큰)과 사용자 요청만 보고 작업 목록을 출력합니다.
• 실행자: 한 번 호출에 정확히 하나의 파일과 하나의 작업만 봅니다. 두 파일을 동시에 보지 않습니다.
• 오케스트레이터: 작업 목록에서 의존성 그래프를 만들고 병렬 실행 가능한 작업과 순차 실행이 필요한 작업을 결정하는 순수 코드(LLM 없음)입니다.

이 접근 방식은 다중 파일 리팩토링을 컨텍스트 윈도우 문제에서 스케줄링 문제로 전환합니다. 플래너는 코드를 볼 필요가 없고, 실행자는 한 번에 제한된 양의 코드만 봅니다.

코드로 적용된 토큰 예산

모든 LLM 호출은 시스템 프롬프트 + 예약된 출력 토큰 + 메모리 + 실제 코드를 측정하는 canFit() 검사를 거칩니다. 코드가 맞지 않으면 에이전트는 파일당 라인 인덱스(약 150줄 이상의 파일에 대해 한 번 생성됨)로 폴백하고 관련 섹션만 가져옵니다.

8192 토큰에 대한 예산 계산:

시스템 프롬프트 + 지시: ~1000
응답 예약: ~2000
단기 메모리(4개 항목): ~360
실제 코드에 사용 가능: ~4800 (약 140~190줄)

예산이 부족할 때는 먼저 폴더 컨텍스트를 제거한 다음 메모리를 제거하고, 마지막으로 실제 코드를 줄입니다.

속도 향상을 위한 병렬 실행

각 실행자가 하나의 파일만 보기 때문에 독립적인 편집이 여러 파일에서 동시에 실행됩니다. 5개 파일 리팩토링은 가장 긴 단일 편집 시간 정도에 완료됩니다. 의존성 그래프(플래너의 작업 목록에서 코드로 구축됨)가 순서를 결정합니다.

문제점과 해결책

• 파일을 덮어쓰는 질문 스타일 요청: "X에 몇 줄이 있나요?"라고 묻는 경우 실행자가 답변을 파일 에 쓰는 문제가 발생했습니다. 플래너 출력에 action_type: "query" 필드를 추가하고 디스크에 쓰지 않는 코드 경로로 라우팅하여 수정했습니다.
• 프로젝트 맵이 오래되어 잘못된 경로로 전달되는 문제: 사용자가 맵에 없는 이름이 변경된 파일을 언급하면 플래너가 자동으로 가장 가까운 일치 항목으로 경로를 지정했습니다. 이제 오케스트레이터가 언급된 파일 경로가 디스크에 존재하는지 확인하고 없으면 명확한 오류를 발생시킵니다.
• 실행자 출력의 마크다운 코드 블록: 작은 모델은 지시에도 불구하고 코드를 삼중 백틱으로 감쌉니다. 해결책: 프롬프트와 싸우는 대신 후처리에서 제거합니다.
• 메모리 토큰 비용: 영구 메모리는 항목당 약 80~90 토큰을 추가합니다. 예산이 부족하면 먼저 폴더 컨텍스트를 제거한 다음 메모리를 제거하고, 실제 코드를 줄입니다.

열린 질문

플래너/실행자 분할이 50개 파일 이상의 코드베이스에서 확장 가능한지 여부 — 의존성 그래프는 관리 가능하지만 프로젝트 맵이 실제 토큰을 소모하기 시작합니다. 현재는 폴더 컨텍스트를 먼저 제거하지만, 더 깊은 편집은 컨텍스트를 잃습니다. 자세히 알고 싶다면 구현이 오픈소스로 공개되어 있습니다.