SmallCode: 7B~20B 소형 로컬 LLM에 맞춰 설계된 터미널 코딩 에이전트

9bow · 5월 20, 2026, 3:30오전

SmallCode 소개

SmallCode는 20B 파라미터 이하의 소형 로컬 LLM에서 실용적인 코딩 작업을 끌어내는 데 초점을 둔 터미널 네이티브 코딩 에이전트입니다. OpenCode나 Claude Code 같은 도구가 프런티어 모델(Frontier model) 의 128K 이상 컨텍스트와 안정적인 도구 호출(tool calling)을 전제로 만들어진 것과 달리, SmallCode는 처음부터 7B~20B 모델이 동작하는 소비자용 하드웨어에서 어떻게 안정적인 작업을 뽑아낼지를 고민한 결과물입니다. LM Studio, Ollama, 그리고 OpenAI 호환 API를 띄울 수 있는 모든 로컬 LLM 서버와 함께 동작하며, 네트워크 호출 없이 완전히 로컬에서 돌릴 수 있다는 점이 특징입니다.

소형 모델에는 일반적으로 잘 알려진 약점이 있습니다. 컨텍스트가 좁아 큰 파일을 그대로 적재할 수 없고, 도구 호출 JSON이 자주 어긋나며, 한 번의 추론에서 여러 단계를 정확히 풀어내기 어렵습니다. SmallCode는 이러한 제약을 모델을 바꿔서 해결하는 대신 주변 인프라 로 보정합니다. 컨텍스트 예산을 자동으로 관리해 절대 윈도우를 넘기지 않고, 도구 호출은 JSON·YAML·XML·Hermes·일반 텍스트 등 어떤 형식으로 와도 받아들이는 관대한 파서로 해석합니다. 복잡한 작업은 TODO 파일 기반으로 잘게 분해해서 한 단계씩 실행하고, 파일은 전체를 다시 쓰는 대신 검색-치환(patch) 방식으로 수정합니다. 본 게시물에서는 SmallCode가 소형 LLM을 위해 어떤 설계 선택을 했는지, 그리고 설치와 기본 사용법은 어떤지 정리합니다.

SmallCode는 자체 의존성으로 BoneScript 와 budget-aware-mcp 를 함께 묶어 배포합니다. BoneScript는 단일 .bone 파일을 라우트, 인증, 데이터베이스, 이벤트, 마이그레이션, SDK, 관리 패널, Docker, CI까지 갖춘 풀스택 백엔드 프로젝트로 컴파일하는 DSL이고, 소형 모델이 8~15번에 걸쳐 호출했을 도구 호출을 1~2회로 줄이는 데 사용됩니다.

SmallCode와 OpenCode의 설계 차이

소형 모델이 제대로 작동하도록 만들기 위해, SmallCode는 OpenCode 같은 프런티어 중심 에이전트와 정반대 결정을 여러 곳에서 내립니다. 두 도구의 차이를 한 번에 비교하면 다음과 같습니다.

항목	OpenCode	SmallCode
타깃 모델	프런티어 모델(Claude, GPT-4 등)	7B~20B 로컬 모델
컨텍스트	전체 적재	예산 기반 관리, 요약 적재
도구 호출	안정적인 JSON 가정	다중 포맷 파서로 관대하게 해석
계획	단일 호출	TODO 파일 기반 단계 분해
편집	전체 파일 재작성	검색-치환 patch
프라이버시	클라우드 API 호출	완전 로컬, 네트워크 불필요

이 표가 단순한 마케팅 비교가 아닌 이유는, 각 항목이 소형 모델의 실제 실패 모드와 직접 연결되어 있기 때문입니다. 컨텍스트 예산 엔진은 8~16K 윈도우를 가진 모델이 컨텍스트 오버플로로 무너지는 것을 막고, 관대한 도구 호출 파서는 모델이 매개변수 이름이나 타입을 어긋나게 출력해도 자동으로 보정합니다. TODO 기반 계획은 깊은 추론을 한 번에 해내기 어려운 모델에게 단계마다 지금 어디에 있는지 를 다시 알려 주는 기억 보조 장치 역할을 합니다.

SmallCode의 핵심 기능

SmallCode가 소형 모델 환경에서 도움이 되는 부분은 결국 다음과 같은 기능들에 압축되어 있습니다. 각 기능은 단순한 옵션이 아니라, 모델이 잘 못 하는 것을 대신 처리하기 위한 보조 장치입니다.

BoneScript 통합: Node.js / TypeScript 백엔드의 경우 하나의 .bone 파일에서 라우트, 인증, DB, 이벤트, 마이그레이션, SDK, 관리 패널, Docker, CI까지 한 번에 컴파일하므로, 소형 모델이 같은 작업을 위해 호출해야 할 도구 횟수가 크게 줄어듭니다.
모델 에스컬레이션: 로컬 모델이 재시도와 분해 후에도 hard fail 한다면, 선택적으로 Claude(Sonnet 4.5 / 4.6, Haiku 4.5), GPT-5.4 Mini / Nano, DeepSeek V4 계열 같은 클라우드 모델에 에스컬레이트할 수 있습니다. 사용자가 API 키를 명시적으로 등록해야만 켜지고, 세션 단위 사용량 제한이 걸려 있어 비용 폭주를 막습니다.
컨텍스트 예산 엔진: 모델의 컨텍스트 윈도우를 넘기지 않도록 큰 파일을 시그니처 수준으로 자동 요약하고, 오래된 메시지를 축출(evict)하며, 토큰 사용량을 실시간으로 추적합니다.
2단계 도구 라우팅: 첫 단계에서 read / write / search / run / plan 같은 카테고리를 고른 뒤 두 번째 단계에서 해당 카테고리의 도구 스키마만 모델에 노출해, 스키마가 컨텍스트를 잡아먹는 비용을 줄입니다.
관대한 도구 호출 파서: JSON, YAML, XML, Hermes 포맷, 일반 텍스트로 출력된 도구 호출을 모두 해석하고, 매개변수 이름 오타나 타입 불일치 같은 흔한 실수를 자동 보정합니다.
TODO 기반 분해 계획: 복잡한 과제를 원자 단계로 분해하고, 매 턴마다 모델이 TODO 파일을 읽어 현재 위치를 인지하도록 만듭니다. 각 단계가 lint나 컴파일을 통과해야 다음으로 넘어갑니다.
patch 우선 편집: 전체 파일을 다시 쓰는 대신 검색-치환을 기본 편집 단위로 사용해, 소형 모델이 큰 파일을 환각이나 잘림 없이 다루도록 돕습니다.
조기 종료 감지: 동일 출력의 반복 루프나 폭주 출력을 감지해 토큰과 시간을 아낍니다.
모델 프로파일: 모델별로 컨텍스트 길이, 도구 포맷(native / hermes / json / xml / text), 채팅 템플릿, 강점과 약점을 정의해 프롬프팅 전략을 자동 조정합니다.
워킹 메모리: 턴을 넘어 유지되는 영구 스크래치패드를 제공해, 추론 깊이가 부족한 모델이 자기 자신에게 메모를 남길 수 있도록 합니다.

SmallCode의 설치와 기본 사용법

설치는 npm 글로벌 설치 또는 npx 실행 한 줄로 끝납니다. SmallCode는 LM Studio, Ollama 등 OpenAI 호환 엔드포인트를 띄운 환경이면 어디서나 동작하며, Node.js 18 이상이 필요합니다.

# 전역 설치
npm install -g smallcode

# 또는 즉시 실행
npx smallcode

# 프로젝트 디렉토리에서 시작
cd my-project
smallcode

설정은 프로젝트 루트의 .env 파일로 합니다. 모델 이름과 로컬 LLM 서버의 베이스 URL을 지정하고, 필요할 때만 에스컬레이션용 클라우드 API 키를 추가하면 됩니다.

# 필수
SMALLCODE_MODEL=your-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1

# 선택: hard fail 시 클라우드 모델로 자동 폴백
# ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# DEEPSEEK_API_KEY=sk-...

내장 도구로는 코드 그래프 검색(graph_search), 심볼 설명(explain_symbol), 파일 읽기·쓰기·패치, ripgrep 기반 정규식 검색(search), 글로브 파일 검색(find_files), 메모리 적재·저장(memory_load, memory_remember), 그리고 BoneScript 컴파일(bone_compile) 등이 제공됩니다. 필요하면 Playwright 기반의 스텔스 웹 브라우징(web_search, web_fetch)도 환경 변수 SMALLCODE_WEB_BROWSE=true 로 활성화할 수 있는데, 이는 20B급 이상의 중대형 모델에서만 권장됩니다. TUI에서는 /quit, /clear, /stats, /memory, /plan, /model, /skill, /plugin, /sessions, /help 같은 슬래시 명령으로 세션 흐름을 조작할 수 있습니다.

SmallCode의 라이선스

SmallCode는 MIT 라이선스로 공개되어 있어 개인 및 상업적 용도로 자유롭게 사용·수정·재배포할 수 있습니다. 함께 동작하는 BoneScript와 budget-aware-mcp 도 동일 저자의 의존 패키지로 묶여 배포되므로, 사내 도구로 도입할 때도 부담이 적습니다.

SmallCode 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~