API 비용 제로, 유출 리스크 제로, 온보딩 1시간 ── 「어디부터 읽어야 하지?」를 완전 로컬 AI + RAG로 해결한 이야기【2,247개

이전 기사의 진화점을 포함한 최신 버전 LocalForge의 완전 가이드입니다.

RAG 대응 · tree-sitter 심볼 추출 · 의존 관계 그래프 · 차분 편집(diff editing) 등 기능이 크게 강화되었습니다.

새로운 프로젝트에 배정되었을 때, 이런 경험이 있지 않으신가요?

리포지토리를 클론(clone)하고 ls를 쳤더니 디렉토리가 20개.

파일 수를 확인하니 2,000개 초과.

문서는 절반이 낡았고, 나머지 절반은 영어.

어디부터 읽어야 할지 몰라 하루를 꼬박 보내고 나서야 겨우 "이 파일이 입구 같네"라고 깨닫는——

그러한 코드 온보딩(code onboarding)의 비효율성은 경력 연수와 상관없이 누구나 느끼는 과제입니다.

이 기사에서는 이러한 상황을 타파한 **완전 로컬 동작 AI 코드 분석 도구 「LocalForge」**의 최신 버전을 소개합니다. 이전에 공개한 초기 버전으로부터 아키텍처를 대폭 혁신하여 속도, 정밀도, 사용 편의성이 모두 향상되었습니다.

LocalForge는 Ollama를 백엔드로 사용한 완전 로컬 AI 구동 코드 분석 IDE입니다.

클라우드 API를 일절 사용하지 않기 때문에:

API 비용이 제로
코드가 외부로 전송되지 않음 (사내 코드 및 업무 로직도 안심)
오프라인 환경에서도 동작함

주요 기능은 3가지 모드로 집약되어 있습니다.

모드	할 수 있는 것
Generate	AI가 프로젝트 구성을 제안하고 파일을 처음부터 생성. SEARCH/REPLACE 차분 편집에도 대응
Resume	기존 프로젝트(외부 제작물도 가능)의 계속 수행 · 확장 · Q&A 지속
Explain	코드베이스를 통째로 분석하여 11개 섹션의 리포트를 생성. RAG 대응 Q&A도 가능

이번에 포커스를 맞출 것은 Explain 모드입니다.

이전 기사에서 소개한 버전으로부터 다음과 같은 점이 크게 진화했습니다.

1. 3단계 분류(3-tier classification) 도입
이전 버전에서는 파일 요약 생성에 LLM을 다용했습니다. 신버전에서는 3단계 분류를 도입하여 LLM 호출을 거의 제로로 줄였습니다.

Tier-0: 경로와 크기만으로 판정 (파일을 열지 않음)
└── .lock, .json, .svg, 테스트 파일... → 즉시 확정
Tier-1: 내용을 읽고 휴리스틱(heuristic) 판정
...

2,000개 파일이라도 LLM이 실제로 개입하는 것은 Q&A와 리포트 생성뿐이라는 설계로 되어 있습니다.

2. 고속 벡터화 (Fast Vectorization)
sentence-transformers/all-MiniLM-L6-v2 (프로세스 내 실행, Ollama로의 요청 불필요)를 사용하여 파일 요약을 ChromaDB에 벡터화합니다.

Q&A에서는 "질문과 의미적으로 가까운 파일"을 자동으로 선별하여 LLM에 전달하기 때문에, 2,000개 파일이 있어도 엉뚱한 답변이 나오지 않도록 했습니다. RAG를 사용할 수 없는 환경에서는 BM25 키워드 검색으로 자동 폴백(fallback)합니다.

3. 의존 관계 그래프 (Dependency Graph)
Python의 import 문, JS/TS의 import/require 문을 정적 분석하여 파일 간의 의존 관계를 자동 구축합니다. Q&A에서는 "이 파일이 무엇을 임포트하고 있는가", "어디로부터 임포트되고 있는가"가 LLM의 컨텍스트(context)에 포함되어 답변의 정밀도가 향상되었습니다.

4. 차분 편집 (Diff Editing)
Generate 모드에서는 기존 파일의 차분(diff)만을 생성 · 적용하는 방식으로 혁신되었습니다. 파일 전체를 다시 쓰는 구 방식과 비교하여 토큰 소비가 대폭 절감되었습니다. 적용 실패 시에는 자동 재시도 및 백업으로부터의 롤백(rollback)도 수행합니다.

5. 워크스페이스 기능 (Workspace Functionality)
여러 프로젝트를 횡단하여 참조할 수 있는 워크스페이스 기능을 추가했습니다. "이 프로젝트가 의존하고 있는 다른 리포지토리"도 Q&A의 컨텍스트에 포함할 수 있습니다.

6. 오피스 문서 지원 (Office Document Support)
.pdf / .docx / .xlsx / .pptx 등의 오피스 문서도 인덱스 대상으로 포함되었습니다. 사양서 · 설계서가 혼재하는 프로젝트에서도 코드와 함께 분석할 수 있습니다.

다음 구성의 프로젝트를 CPU만 사용(RAM 32GB), 모델 qwen3-coder:30b로 분석했습니다.

총 파일 수: 2,247개 파일 (모두 인덱스 완료)
언어 구성:
Python: 597개 파일
...

인덱스 구축: 약 20초 👈 이 부분이 크게 줄었습니다.

리포트 생성: 15분 정도 👈 qwen3-coder:30b는 18GB이므로 32GB RAM으로도 대응 가능합니다 (가성비가 좋습니다).

이후의 Q&A: 수십 분 정도 소요됩니다 👈 컨텍스트(Context)가 크기 때문에 LLM 처리 시간이 걸리지만, 좋은 답변을 얻을 수 있었습니다.

1시간 후에는 프로젝트 전체의 구조, 데이터 흐름(Data Flow), 의존 관계(Dependency), 잠재적인 기술 부채(Technical Debt)까지 파악할 수 있었습니다.

Explain 모드로 생성되는 리포트는 11개 섹션으로 고정되어 있습니다.

#	섹션명	내용
1	Project Overview	프로젝트의 개요·목적·규모
...	...	...

첫날에 알고 싶은 모든 정보가 여기에 모여 있습니다.

# 1. Ollama를 설치합니다
# https://ollama.com 에서 OS용 패키지를 다운로드하세요
ollama pull qwen3-coder:30b # 원하는 모델을 가져옵니다
...

pywebview를 사용할 수 있는 환경에서는 네이티브 윈도우(Native Window)가 열립니다.

Docker 또는 헤드리스(Headless) 환경에서는 브라우저에서 http://localhost:7331을 열기만 하면 됩니다.

LAN 상의 다른 디바이스(태블릿·스마트폰)에서도 접속할 수 있습니다.

헤더의 「📁 폴더 열기」에서 분석하고 싶은 프로젝트 폴더를 선택합니다.

코드가 들어 있는 폴더를 선택하면 Explain 모드가 자동 감지됩니다.

「⚙ 인덱스 구축」 버튼을 누르면 처리가 시작됩니다.

처리 흐름:
① Tier-0/1에서 락(Lock)·설정·테스트 파일을 고속 처리
② Tier-2에서 소스 코드를 tree-sitter로 심볼(Symbol) 추출
...

상태 표시줄에 인덱스 구축 중: src/main.py (1024/2247)와 같이 진행 상황이 표시됩니다.

2회차부터는 변경된 파일만 재처리되므로 몇 초 만에 완료됩니다.

「✦ 리포트 생성」 버튼을 누르면, 11개 섹션의 리포트가 스트리밍(Streaming) 방식으로 생성됩니다.

오른쪽의 「Ollama 라이브 출력」 패널에서 중간 출력을 실시간으로 확인할 수 있습니다.

리포트 완성 후, 채팅창을 통해 자유롭게 질문할 수 있습니다.

질문 예시:
"인증 플로우(Authentication Flow)는 어느 파일에 구현되어 있나요?"
"데이터베이스의 스키마(Schema) 설계를 설명해 주세요"
...

RAG가 활성화되어 있다면, 벡터 검색(Vector Search) → 의존 관계 확장(BFS 5-hop) → 컨텍스트 구성 → LLM 생성이라는 흐름을 통해 관련된 파일만 자동으로 선택됩니다.

파일 트리 상단의 「📎」 버튼을 누르면 핀 고정(Pinning) 모드로 들어갑니다.

체크박스로 파일이나 폴더를 선택하면, 이후의 Q&A에서는 해당 파일이 컨텍스트에 반드시 포함됩니다.

"이 모듈만 깊게 묻고 싶다"라거나 "설계서와 대응하는 코드를 함께 분석하고 싶다"라는 상황에서 유용합니다.

qwen3-coder:30b와 같은 대형 모델을 CPU로 구동할 때의 팁을 정리합니다.

① CPU 스레드 수 조정

우측 사이드바의 「CPU 스레드」 슬라이더를 사용하여 사용 스레드 수를 조정할 수 있습니다.
다른 작업과 병행할 경우에는 절반 정도로 제한하면 안정적입니다.

② RAG 임베딩 비활성화 (초고속 모드)

config.json에서 "enable_rag": false를 설정하면 벡터 임베딩(Vector Embedding)을 건너뛰어 인덱스 구축 속도가 대폭 빨라집니다. Q&A는 BM25 검색으로 동작합니다.

③ 모델 언로드 (Unload)

헤더의 「⏏ 해제」 버튼으로 현재 모델을 RAM에서 해제할 수 있습니다.
다른 모델로 전환할 때나 메모리를 비우고 싶을 때 사용합니다.

④ 백그라운드 프리로드 (Background Preload)

Q&A 버튼을 누르는 순간부터 컨텍스트 구성과 병행하여 모델의 RAM 로드가 시작됩니다. 첫 응답까지의 대기 시간이 체감상 크게 개선되었습니다.

Ollama에서 구동되는 임의의 모델을 사용할 수 있습니다.

모델	특징	CPU 32GB에서의 동작
qwen3-coder:30b	코드 이해에 특화, 고정밀	◎ 실적 있음
gemma4:4b	경량·범용	◎ 쾌적
gemma4:26b	사고 과정(Thinking Process) 시각화 대응	△ 무거움
qwen3.6:27b	사고 과정(Thinking Process) 시각화 대응	△ 무거움
qwen2.5-coder:7b	코드 이해에 특화, 경량	◎ 빠름

Gemma와 같은 「싱킹 모델(Thinking Model)」은 <think>

태그 내의 추론 토큰(Reasoning Token)을 Ollama 라이브 패널에 분리하여 표시하는 기능도 갖추고 있습니다.

과제	LocalForge를 통한 해결
대규모 코드의 전체상을 파악하기 어려움	11개 섹션의 AI 리포트를 자동 생성
...
"코드를 읽기 전에 먼저 AI에게 개요를 물어보는" 온보딩(Onboarding) 스타일은 초보자뿐만 아니라, 오랜만에 다시 접하는 프로젝트로 돌아온 베테랑에게도 유효합니다.

완전 로컬(Fully Local)로 동작하기 때문에 업무용 코드라도 부담 없이 사용할 수 있습니다. 꼭 한번 시도해 보세요.

• Ollama 공식 사이트

• LocalForge 리포지토리 (Repository):

• 임베딩 모델 (Embedding Model):
  nomic-embed-text:latest

, sentence-transformers/all-MiniLM-L6-v2

• 사용 모델 예시:
  qwen3-coder:30b

, gemma4:26b

, gemma4:e4b

, qwen2.5-coder:7b