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

📖 전체 소스 읽기: r/LocalLLaMA