SmallCode: 7B~20B 로컬 LLM으로 터미널 코딩 에이전트를 돌리는 설계법

클라우드로 코드를 보내지 않는다는 선택

클라우드 AI 코딩 서비스의 보안 우려와 비용 부담이 커지면서 온디바이스 소형 LLM 기반 터미널 코딩 에이전트 SmallCode가 주목받고 있다. 7B~20B 파라미터 규모의 소형 모델에 최적화된 도구 호출·에러 복구·원자적 태스크 분해 아키텍처를 갖춰, 클라우드 의존 없이 코드와 컨텍스트가 디바이스 밖으로 나가지 않는 완전한 온디바이스 프라이버시를 실현한다. LM Studio, Ollama 등 OpenAI 호환 엔드포인트와 연동되어 Qwen2.5-Coder, DeepSeek-Coder-V2 등 오픈웨이트 모델과 함께 쓸 수 있으며, 2026년 들어 소비자 GPU에서 70B 모델 양자화 실행이 실용적 수준에 도달했다.

모델을 키우는 대신 에이전트를 설계한다

대형 LLM(GPT-4o, Claude Sonnet 등)은 복잡한 다단계 코딩 태스크를 한 번에 처리할 수 있지만, 7B~20B 소형 모델은 컨텍스트 이해, 도구 호출 정확도, 다단계 추론에서 한계를 보인다. SmallCode는 이 한계를 모델 크기 확장이 아니라 에이전트 아키텍처 최적화로 극복하는 쪽을 택한다.

태스크 원자화: 복잡한 태스크를 단순한 원자적 단계로 분해해 소형 모델이 각 단계를 안정적으로 처리하게 한다
진행 추적: 에이전트가 매 턴마다 TODO 파일을 읽어 현재 단계를 파악하고 다음 액션을 결정한다
도구 호출 자동복구: JSON, YAML, XML, Hermes 포맷 및 평문 텍스트에서 도구 호출을 파싱하고 잘못된 파라미터명·타입 불일치를 자동 수정한다
편집 원시 연산: 전체 파일 재작성 대신 검색-치환을 기본 편집 단위로 써서 컨텍스트 효율을 끌어올린다

이런 설계로 SmallCode는 4B 활성 파라미터 모델(MoE 아키텍처 기준)로 87% 코딩 벤치마크를 달성했다. 순수 모델 성능보다 에이전트 아키텍처 설계의 기여가 크다는 뜻이다. 각 단계를 컴파일·린팅으로 검증하는 단계별 유효성 검사가 오류 누적을 막고, 자동복구 도구 파서가 소형 모델의 도구 호출 포맷 불일치를 흡수한다.

온디바이스 추론: 양자화와 레이어 오프로딩

GGUF(GPT-Generated Unified Format)는 llama.cpp 프로젝트가 개발한 파일 포맷으로, 모델 가중치·아키텍처 메타데이터·토크나이저를 단일 파일에 패키징한다. Ollama, LM Studio, llama.cpp가 기본 지원해 로컬 LLM 생태계의 사실상 표준이 됐다.

양자화	크기 감소	품질 손실	권장 사용
Q4_K_M	73%	소	대부분의 개발 환경 (최적 균형)
Q5_K_M	67%	극소	품질 우선, VRAM 여유 있을 때
Q8_0	50%	거의 없음	고품질 필요, 충분한 VRAM
Q2_K	82%	대	극도의 메모리 제약 환경만

Q4_K_M이 73% 압축률과 소폭의 품질 손실이라는 트레이드오프로 대부분의 개발 환경에서 최적이다. 다만 양자화는 코딩·STEM 태스크에서 일반 대화보다 품질 저하가 더 두드러지므로, 정밀도가 중요한 알고리즘 구현에는 Q5_K_M 이상을 권장한다.

2026년 기준 로컬 코딩에 추천되는 모델로는 EvalPlus·LiveCodeBench·BigCodeBench에서 오픈소스 SOTA 수준을 보이며 FIM(Fill-in-the-Middle)을 지원하는 Qwen2.5-Coder-7B/14B, 코드 생성·디버깅에 특화되고 한국어·영어·중국어를 지원하는 DeepSeek-Coder-V2-Lite(16B), FIM 훈련과 16K 컨텍스트 윈도우로 파인튜닝에 강한 StarCoder2-15B, Google이 개발해 4비트 양자화 시 약 9GB VRAM으로 실행 가능한 CodeGemma-7B가 꼽힌다.

7B~~20B 모델을 소비자급 GPU(8~~16GB VRAM)에서 실행할 때 전체 모델을 VRAM에 올리기 어려우면, 일부 레이어를 CPU RAM에 배치하는 레이어 오프로딩으로 하이브리드 실행이 가능하다.

⤢✕

llama.cpp/Ollama 기준 주요 성능 파라미터는 다음과 같다.

n_gpu_layers: GPU에 올릴 레이어 수. 전체(-1) 또는 부분 지정
n_ctx: 컨텍스트 윈도우 크기. 4096~32768. 클수록 VRAM 소모 증가
n_batch: 배치 크기. 512가 대부분의 환경에서 최적
use_mmap: 메모리 맵 파일 활성화로 모델 로딩 속도 향상
use_mlock: 스왑 방지를 위한 메모리 잠금

터미널 에이전트: 파일시스템 접근부터 디버깅 루프까지

SmallCode는 로컬 파일시스템과 쉘에 직접 접근하는 에이전트다. 도구 호출 인터페이스를 통해 파일 읽기·쓰기·검색, 쉘 명령 실행, 코드 린팅·컴파일 결과 피드백을 수행한다.

⤢✕

로컬 LLM 에이전트가 파일시스템과 쉘에 접근할 때는 보안 경계 설정이 중요하다. SmallCode는 작업 디렉토리를 프로젝트 루트로 제한하고, 허용 쉘 명령 목록(allowlist)을 설정해 시스템 전역 파일 접근을 막는다. 권장 보안 설정은 작업 디렉토리를 --workdir /path/to/project로 제한하고, 네트워크 접근은 기본 비활성화 후 필요 시 명시적으로 허용하며, rm -rf·sudo·curl 등 위험 명령을 필터링하고, .env 파일의 시크릿은 에이전트 컨텍스트에서 마스킹하는 것이다.

소형 모델의 한계를 보완하는 핵심 설계는 각 단계 후 컴파일·린팅 결과를 즉시 피드백으로 주입하는 반복 루프다. 에이전트가 코드 변경을 생성하면 파일시스템에 검색-치환을 적용하고, 린터(ESLint, Pylint, rustfmt 등)를 자동 실행한 뒤 컴파일러 또는 인터프리터로 구문을 검증한다. 오류가 나면 오류 메시지와 컨텍스트를 다음 프롬프트에 포함하고, 성공하면 TODO 파일의 해당 단계를 완료로 표시하고 다음 단계로 넘어간다. 이 루프 덕분에 소형 모델이 한 번에 완벽한 코드를 생성하지 못해도 오류 피드백을 통해 점진적으로 수렴하는 자가 교정이 가능해진다.

어디까지 믿고 맡길 수 있나

2026년 기준 7B~20B 소형 모델로 실용적인 코딩 에이전트를 운용하는 것은 가능하지만 한계는 명확하다. 단일 파일 또는 소규모 모듈 코드 생성·수정, 알려진 패턴과 보일러플레이트, 정규 표현식·SQL·쉘 스크립트 등 상대적으로 단순한 도메인, 코드 포맷팅·주석 추가·변수명 리팩토링은 강점이다. 반면 대규모 코드베이스 전반의 리팩토링, 복잡한 알고리즘 설계와 아키텍처 결정, 여러 파일에 걸친 복잡한 의존관계 추론, 최신 프레임워크·라이브러리 지식(훈련 데이터 컷오프 한계)은 약점으로 남는다.

항목	로컬 LLM (SmallCode)	클라우드 에이전트
프라이버시	완전 온디바이스	코드가 서버로 전송
비용	초기 하드웨어 후 무료	토큰 기반 과금
속도	하드웨어 의존	일관된 고성능
코드 품질	7B~20B 수준	GPT-4o/Claude 수준
오프라인	완전 지원	인터넷 필수
최신 지식	모델 컷오프 한계	최신 정보 가능

Apple Silicon M4 Pro(16GB 통합 메모리) 기준 Qwen2.5-Coder-14B Q4_K_M 모델을 실행하면 초당 약 25~35토큰의 생성 속도로 코딩 에이전트를 운용할 수 있다. 클라우드 API 대비 월 수만 원 수준의 비용 절감이 가능하다는 것이 TCO(Total Cost of Ownership) 측면의 매력이다.

금융·의료·방산 등 규제 산업에서는 소형 로컬 LLM 코딩 에이전트의 기업 내부망 적용이 실용적 대안으로 떠오르고 있다. Ollama 또는 vLLM을 내부 GPU 서버에 배포해 OpenAI 호환 API 엔드포인트로 노출하고, SmallCode CLI를 개발자 워크스테이션에서 내부 엔드포인트로 지정해 실행하면 모든 코드 컨텍스트가 기업 네트워크 경계 내에서만 처리된다. 내부 코드베이스·도메인 언어·코딩 컨벤션으로 LoRA/QLoRA 파인튜닝한 모델은 일반 오픈웨이트 모델보다 기업 환경에서 더 높은 효율을 보인다.