Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
CodeSage는 Ollama를 활용하여 100% 로컬에서 구동되는 오픈 웨이트 AI 모델 기반의 CLI 코드 리뷰 도구입니다. 이 도구는 코드를 외부 서버로 전송하지 않아 NDA가 필요한 프리랜서 개발자에게 최적화되어 있습니다. 무제한 사용과 제로 클라우드 의존성을 제공하여 실질적인 가치를 제시합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기요약 — 저는 CodeSage를 만들었습니다. 이는 Ollama를 통해 100% 로컬에서 구동되는 오픈 웨이트(open-weight) AI 모델을 사용하여 코드를 검토하는 CLI 도구입니다. API 키가 필요 없고, 어떤 서버에도 데이터가 전송되지 않습니다. 완전히 개인적이며(private), 프리랜서 개발자들이 기꺼이 비용을 지불할 만한 종류의 도구입니다.
GitHub Repository: https://github.com/Nobody-KnowsBetter/code-sage
모든 프리랜서 개발자는 이런 상황을 겪어봤을 겁니다. 코드를 작성했는데, 뭔가 좀 이상한 것 같은데, 당장 상급 개발자(senior dev)에게 물어볼 사람이 없는 경우입니다. GitHub Copilot의 리뷰 기능을 사용하거나 ChatGPT에 코드를 붙여넣을 수 있습니다... 하지만 잠깐만요 — 이것은 다음을 의미합니다:
프리랜서와 소규모 컨설팅 회사에게 이것은 실제 문제입니다. 클라이언트의 NDA(비밀유지협약)는 제3자 AI API와 결합하기 어렵습니다. 게다가 AI 리뷰 서비스에 매월 $20을 지불하는 것은 마진을 깎아 먹습니다.
만약 AI 코드 리뷰어가 사용자의 노트북에서 전적으로 작동하고, 언제든 사용할 수 있으며, 구동 비용이 정확히 $0이고, 코드가 파일 시스템을 벗어나는 것을 절대 보지 않는다면 어떨까요?
그것이 CodeSage입니다. 그리고 이것은 누군가가 실제로 돈을 지불할 만한 가치 제안(value proposition)을 가지고 있기 때문에, 사람들이 기꺼이 비용을 지불할 도구입니다: 무제한 AI 코드 리뷰, 제로 클라우드 의존성, 제로 지속 비용.
CodeSage는 네 가지 핵심 명령어를 가진 터미널 기반의 AI 코드 리뷰 어시스턴트입니다:
# 전체 AI 분석으로 파일 검토하기
codesage review auth.py
...
리뷰 결과는 일반적인 조언이 아니라 구조화되고 실행 가능한 형태입니다:
## 🎯 요약 (Summary)
JWT 토큰을 검증하는 인증 핸들러(...)
...
이것은 제가 내린 가장 의도적인 아키텍처 결정이었습니다. 이 도구에 있어 '오픈'이 왜 중요한지 알려드리겠습니다:
프리랜서가 NDA(비밀유지협약)를 맺은 클라이언트 프로젝트 작업을 할 때, 코드는 기밀입니다. 이를 제3자 AI API로 전송하는 것은 '데이터로 학습하지 않겠다'는 약속이 있더라도 실제적인 법적 및 보안 위험을 초래합니다. 이는 가설이 아니라, 프리랜서들이 가장 중요한 작업에 대부분의 AI 리뷰 도구를 사용할 수 없는 이유입니다.
Ollama를 통해 로컬에서 구동되는 오픈 웨이트 모델(open-weight models)을 사용하면, 코드는 개발자 기계를 절대 벗어나지 않습니다. 끝. 이것은 있으면 좋은 기능이 아니라, 가장 필요로 하는 사람들에게 CodeSage가 실행 가능하게 만드는 핵심 기능입니다.
클라우드 LLM API는 토큰당 요금을 부과합니다. 하루에 코드를 50번 리뷰하는 프리랜서라면 API 크레딧을 빠르게 소진할 것입니다. Gemma 3와 같은 모델을 이용한 로컬 추론(Local inference)은 하드웨어만 갖추면 리뷰 한 번당 비용이 $0입니다. 프리랜서에게 판매할 도구의 경우, 운영 비용을 제로로 유지하는 것이 청구하는 가격 전체를 순 마진으로 만드는 비결입니다.
비행기. 와이파이가 없는 카페. 엄격한 외부 전송 규칙(egress rules)을 가진 기업 환경. 위성 연결을 사용하는 해외 개발자. CodeSage는 Ollama가 실행되는 모든 곳에서 작동합니다.
클로즈드 소스 코드 리뷰어는 제품입니다. 오픈 소스인 것은 플랫폼입니다. 사람들은 자신만의 프롬프트 템플릿을 추가하고, 자신의 코드베이스 패턴으로 학습하며, 오늘이든 5년 후든 Ollama가 지원하는 모든 모델을 연결할 수 있습니다.
CodeSage는 다음과 같이 구조화되어 있습니다:
┌─────────────────────────────────────────────────────────────┐
│ 개발자 터미널(Developer Terminal) │
└───────────────────────┬─────────────────────────────────────┘
...
좋고, 일관성 있는 리뷰를 얻는 데 가장 중요한 부분은 시스템 프롬프트입니다. prompts.py의 핵심 섹션은 다음과 같습니다:
사용자 경험(UX)을 가장 빨리 망치는 것은 터미널에서 30초 동안 아무것도 보지 못하고 기다리는 것입니다. CodeSage는 Ollama로부터 토큰이 도착하는 즉시 스트리밍합니다:
async def stream(self, prompt: str, system: str = "") -> AsyncIterator[str]:
"""Stream tokens from Ollama one chunk at a time."""
async with self._client.stream("POST", "/api/generate", json=payload) as resp:
...
Rich의 Live 디스플레이와 결합하여, 모델이 생각하는 동안 리뷰가 실시간으로 업데이트되는 뷰를 제공합니다. 터미널이 전체 응답을 기다리게 하는 대신 단어 단위로 채워집니다. 이 하나의 기능 덕분에 동료들과 테스트했을 때 이 도구의 느낌이 "고장 난 것 같다"에서 "살아있는 것 같다"로 바뀌었습니다.
개발자 도구를 출시하면서 배운 한 가지는 다음과 같습니다: 최적의 경로(happy path)를 따르지 않을 것이라고 가정하라입니다. 만약 사용자가 Ollama 시작을 잊었다면:
async def _ensure_model_available(self) -> None:
try:
resp = await self._client.get("/api/tags")
...
사용자는 원시적인 트레이스백(raw traceback)이 아닌, 명확하고 실행 가능한 오류 메시지를 받게 됩니다.
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh
...
# Gemma 3 — Google의 최신 오픈 모델로, 코드에 탁월함
olllama pull gemma3
...
git clone https://github.com/Nobody-KnowsBetter/code-sage.git
cd code-sage
bash setup.sh # 일회성 작업: venv 생성, 의존성 설치, .env 설정
...
# 다른 터미널에서 (또는 백그라운드 서비스로):
ollama serve
...
1. 프롬프트 엔지니어링이 모델 선택보다 중요하다.
시스템 프롬프트에 구조화된 출력 형식을 지정한 것이 다양한 모델 간 전환하는 것보다 검토 품질에 더 큰 영향을 미쳤습니다. 제약 조건이 잘 설정된 Gemma 3가 제약 없는 CodeLlama보다 우수했습니다.
2. 스트리밍 UX는 LLM 도구에 선택 사항이 아니다.
동료들과 비스트리밍 버전을 테스트했을 때, 대기하는 동안 "작동하지 않는 느낌"이라는 의견이 지배적이었습니다. 스트리밍은 이 도구를 살아있는 것처럼 느끼게 했습니다.
3. 오픈 웨이트 모델은 코드 작업에서 진정으로 경쟁력이 있다.
Gemma 3는 제가 테스트한 코드에서 GPT-4가 발견했던 것과 동일한 보안 문제를 포착했습니다. 코드 검토에 있어 오픈 모델과 클로즈드 모델 간의 격차는 상당히 줄었습니다.
4. Ollama API는 매우 간단하다.
JSON 본체를 사용하는 POST /api/generate. 기본적으로 이것이 전부입니다. 가장 어려웠던 부분은 스트리밍 NDJSON 파싱이었는데, 이는 약 10줄로 해결되었습니다.
5. Python 3.14가 macOS에서 .pth 파일 로딩을 깨뜨린다.
재미있는 디버깅 세션이었습니다: Python 3.14 + macOS는 pip에 의해 다운로드되거나 생성된 파일을 UF_HIDDEN 플래그를 사용하여 "숨김"으로 표시하며, 새로운 site.py가 편집 가능한 설치(editable installs)를 처리할 때 이를 건너뜁니다. 해결책은 chflags -R 0 .venv입니다. 이것이야말로 실제로 무언가를 구축해 봐야만 만날 수 있는 현실적인 난관입니다.
그렇다고 생각합니다. 그리고 그 이유는 다음과 같습니다:
동료가 실제 클라이언트 프로젝트에서 테스트해보고는 이렇게 말했습니다: "VS Code 확장 기능만 있다면 월 $5를 지불할 의향이 있다." 이것이 로드맵입니다.
마우스 오른쪽 클릭 → CodeSage Review.codesage.yml — 프로젝트별 설정 (언어, 선호 모델, 사용자 지정 규칙)모든 PR(Pull Request)을 환영합니다! 초보자용 이슈:
--since 플래그를 추가하여 git 참조 이후 변경된 파일만 리뷰# 테스트 스위트 실행 (실제 Ollama 필요 없음 — 모두 목업됨)
pytest --cov=codesage
| 구성 요소 | 기술 | 이유 |
|---|---|---|
| AI 런타임 | Ollama | 로컬 추론, 클라우드 사용 없음 |
| ... |
❤️를 담아 Hacktoberfest 2026 DEV Challenge를 위해 제작되었습니다. 이 코드가 버그 배포를 막는 데 도움이 되었다면, GitHub에서 별점(⭐)을 남겨주세요!