SmallCode는 7B~20B급 로컬 LLM이 실제 코드 작업을 수행하도록 설계된 터미널 네이티브 코딩 에이전트다. Claude, GPT-5 같은 프런티어 모델을 전제로 한 도구와 달리, 작은 모델의 짧은 컨텍스트·불안정한 툴 콜·파일 재작성 오류를 아키텍처로 보완한다.
왜 필요한가
소형 로컬 모델은 개인정보 보호와 비용 면에서 매력적이지만, 코딩 에이전트로 쓰기에는 약점이 뚜렷하다.
- 컨텍스트 창이 작아 전체 파일·툴 스키마를 한 번에 넣기 어렵다.
- JSON 툴 콜 형식을 자주 틀린다.
- 긴 파일을 통째로 다시 쓰면 누락·환각·절단이 발생한다.
- 복잡한 작업을 한 번에 계획하면 중간에 목표를 잃기 쉽다.
SmallCode는 이 문제를 “더 큰 모델을 쓰라”가 아니라 “작은 모델이 버틸 수 있는 하네스를 만들자”로 푼다.
핵심 설계
| 설계 | 설명 |
|---|---|
| 컨텍스트 예산 엔진 | 툴 결과를 제한하고 오래된 결과를 요약·퇴거해 작은 컨텍스트 창을 넘지 않게 한다 |
| 2단계 툴 라우팅 | 먼저 read/write/search/run/plan 범주를 고르고, 그다음 필요한 툴 스키마만 제공한다 |
| 관대한 툴 파서 | JSON, YAML, XML, Hermes, 일반 텍스트 형식의 툴 호출을 해석하고 흔한 오류를 자동 보정한다 |
| 패치 우선 편집 | 전체 파일 쓰기보다 search-and-replace 패치를 기본 편집 단위로 쓴다 |
| TODO 기반 계획 | 복잡한 작업을 TODO 파일로 분해하고 각 단계를 lint/compile로 검증한다 |
| 조기 중단 감지 | 반복 루프, 패치 실패 루프, 컨텍스트 상실을 감지해 작업을 재정렬한다 |
| 선택적 에스컬레이션 | 로컬 모델이 실패하면 Claude, OpenAI, DeepSeek 같은 클라우드 모델로 제한적 fallback 가능 |
설치와 실행
npm install -g smallcode
cd my-project
smallcodeNode.js 없이 쓰려면 릴리스 tarball을 내려받는 설치 스크립트를 사용할 수 있다.
bash <(curl -fsSL https://raw.githubusercontent.com/Doorman11991/smallcode/master/install.sh)필수 설정은 OpenAI 호환 로컬 LLM 서버다. LM Studio, Ollama, OpenAI 호환 엔드포인트를 쓸 수 있다.
SMALLCODE_MODEL=your-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1언제 쓰면 좋은가
- 로컬 LLM로 코딩 에이전트를 실험하는 개발자: Qwen, Gemma, Kimi 계열 중소형 모델을 하네스와 함께 테스트할 수 있다.
- 프라이버시가 중요한 코드베이스: 네트워크 없이 로컬 모델과 로컬 도구만으로 작업할 수 있다.
- 에이전트 하네스 연구자: 툴 라우팅, 컨텍스트 압축, 패치 기반 편집, working memory 같은 설계를 비교하기 좋다.
반대로 대형 레거시 코드베이스에서 높은 정확도가 필요한 장시간 작업은 아직 프런티어 모델 기반 에이전트가 더 안정적일 수 있다. SmallCode의 가치는 “최고 성능”보다 “작은 모델의 실패 모드를 구조적으로 줄이는 설계”에 있다.
관련 문서
- local-slm-tips-agentic-workflows — 에이전트 워크플로에서 작은 모델을 쓰는 이유
- local-slm-tips-tool-calling-models — 에이전트 툴 콜링에 적합한 소형 언어 모델
- agent-harness — AI 에이전트 성능을 결정하는 하네스 설계
- opencode — 터미널·IDE·데스크탑에서 동작하는 오픈소스 AI 코딩 에이전트
- zerostack — Rust로 만든 8MB급 초경량 코딩 에이전트
참고 자료
- Doorman11991/smallcode — GitHub 공식 저장소