미리 알려드립니다. Anthropic / Claude는 사용자가 트래픽을 해당 기업의 CLI 도구로 라우팅하여 토큰 사용 비용 (token usage cost)을 회피하는 것을 좋아하지 않는다는 사실이 밝혀졌습니다. 제가 월 200달러 플랜을 사용하던 중, 이로 인해 플랫폼에서 섀도우 밴 (shadow banned)을 당했습니다. 수개월 동안 항소 (appeal)를 제출했음에도 그들은 응답을 거부하고 있으며, 제가 작업한 어떤 프로젝트도 그들의 이용 약관 (Terms)의 어떤 측면도 위반하지 않았습니다. 조사 결과, 유사한 사례로 밴을 당한 많은 사람들을 확인했습니다. 주의하시기 바랍니다.

Multi-Agent Framework 통합을 통한 Claude Code용 로컬 검색 증강 생성 (RAG) 시스템.

ChromaDB 벡터 임베딩 (vector embeddings)을 지능적인 문서 검색 및 Multi-Agent Framework (MAF) 오케스트레이션 (orchestration)과 결합하여 문맥 인식 개발 지원을 제공하는 프로덕션 준비 완료 (production-ready) Claude Code 플러그인입니다.

현재 버전: 2.0.0
상태: 프로덕션 준비 완료 (KNOWN_ISSUES.md에 알려진 제한 사항 문서화됨)

주요 기능:

• HNSW 인덱싱을 포함한 ChromaDB 기반 벡터 저장소
• 의미론적 (semantic) 매칭과 키워드 매칭을 결합한 하이브리드 검색
• 지능형 쿼리 라우팅을 위한 Multi-Agent Framework
• 문서 처리를 위한 외부 API 비용 제로
• 포괄적인 플러그인 시스템 (hooks, MCP 서버, 슬래시 명령어)

대안 프로젝트: 확장된 기능을 갖춘 독립형 CLI 경험을 원하신다면 dt-cli를 참조하세요. 두 프로젝트 모두 활발히 유지 관리되고 있으며 함께 사용할 수 있습니다.

RAG-CLI는 프로젝트 문서, 코드베이스 문맥 (codebase context) 및 외부 리소스에 대한 즉각적인 액세스를 제공하여 개발 워크플로우를 향상시키는 프로덕션 준비 완료된 로컬 검색 증강 생성 (Retrieval-Augmented Generation) 시스템입니다. Claude Code와 네이티브 플러그인으로서 원활하게 작동하며, 기업급 보안 및 성능으로 문서를 로컬에서 처리하는 동안 외부 API 호출의 필요성을 제거합니다.

API 오버헤드 제로 (Zero API Overhead): API 비용 발생 없이 로컬에서 문서를 처리합니다.
즉각적인 컨텍스트 (Instant Context): 수동 검색 대신 밀리초(ms) 단위로 관련 문서를 가져옵니다.
코드 품질 향상 (Improved Code Quality): 컨텍스트 인식 (Context-aware) 지원을 통해 더 나은 의사결정을 내립니다.
완전한 개인정보 보호 (Complete Privacy): 모든 문서 처리는 사용자의 기기 내에서만 이루어집니다.
개발자 중심 (Developer Focused): 개발 워크플로 및 Claude Code 통합에 최적화되어 있습니다.

로컬 우선 아키텍처 (Local-First Architecture): Claude API 호출을 제외한 모든 기능이 로컬에서 실행됩니다.
빠른 성능 (Fast Performance): 100ms 미만의 벡터 검색 (Vector search), 5초 미만의 엔드 투 엔드 (End-to-end) 응답 속도.
하이브리드 검색 (Hybrid Search): 시맨틱 벡터 검색 (Semantic vector search)과 키워드 매칭 (Keyword matching)을 결합하여 탁월한 정확도를 제공합니다.
Claude Code 통합 (Claude Code Integration): 향상된 개발 워크플로를 위한 원활한 플러그인 지원.
다중 포맷 지원 (Multi-Format Support): MD, PDF, DOCX, HTML, TXT 파일을 처리합니다.
실시간 모니터링 (Real-Time Monitoring): 시스템 관측성 (Observability)을 위한 PowerShell 인터페이스를 갖춘 TCP 서버.
백그라운드 파일 감시 (Background File Watching): watchdog 라이브러리를 사용한 자동 문서 인덱싱 (Debounced events 적용).
멀티 에이전트 오케스트레이션 (Multi-Agent Orchestration): RAG 에이전트와 코드 분석 에이전트 간의 지능형 라우팅.
프로덕션 준비 완료 (Production Ready): 포괄적인 에러 핸들링 (Error handling), 로깅 (Logging) 및 모니터링 제공.

Python: 3.8 이상 (3.13에서 테스트 완료)
RAM: 최소 4GB (대규모 문서 세트의 경우 8GB 권장)
디스크 공간 (Disk Space): 종속성(Dependencies)을 위한 2GB + 문서 벡터를 위한 공간
Claude Code: 최신 버전 (플러그인 모드용)
Anthropic API Key: 선택 사항 (스탠드얼론 (Standalone) 모드에서만 필요)

RAG-CLI는 다음 환경에서 효율적으로 실행됩니다:

• Windows 10+ / macOS / Linux
• 리소스가 제한된 노트북 (유연하게 확장 가능)
• 클라우드 인스턴스 및 Docker 컨테이너
• CI/CD 파이프라인

RAG-CLI를 Claude Code 플러그인으로 사용하는 가장 쉬운 방법:

# Claude Code 터미널에서
/plugin marketplace add https://github.com/ItMeDiaTech/rag-cli.git
/plugin install rag-cli

그 후 Claude Code를 재시작하세요. 플러그인은 별도의 설정 없이 자동으로 활성화됩니다.

이점 (Benefits):

• 모든 의존성 (dependencies) 자동 설치
• 플러그인이 자체적인 라이프사이클 (lifecycle) 관리
• API 키 불필요 (Claude Code를 내부적으로 사용)
• /plugin update rag-cli 명령어를 통한 원클릭 업데이트

개발, 테스트 또는 사용자 정의 설정 (custom configuration)의 경우:

# 저장소 복제 (Clone)
git clone https://github.com/ItMeDiaTech/rag-cli.git
cd rag-cli
...

RAG-CLI에 기여 (contributing)하려면:

# 수정 가능한 모드 (editable mode)로 복제 및 설치
git clone https://github.com/ItMeDiaTech/rag-cli.git
cd rag-cli
...

기여자 주의 사항: configure_mcp.py 스크립트는 사용자의 시스템에 맞는 절대 경로를 포함한 .mcp.json 파일을 생성합니다. 이 파일은 gitignored 처리되어 있으며, 사용자가 이미 설정한 다른 MCP 서버들을 보존합니다. 프로젝트 경로가 변경되면 언제든지 스크립트를 다시 실행할 수 있습니다.

수동으로 설치했으며 이를 Claude Code 플러그인으로 사용하고 싶은 경우:

# RAG-CLI 디렉토리에서 실행
python scripts/sync_plugin.py
# 이 명령은 필요한 파일들을 다음 위치로 복사합니다:
...

별도의 설정이 필요하지 않습니다. RAG-CLI는 Claude Code 환경을 자동으로 감지합니다:

# 최초 설정: 문서 인덱싱 (Index)
/rag-project
# 또는 수동 인덱싱
...

Claude Code 외부에서 개발 또는 테스트를 하는 경우:

# 환경 변수 (environment variables) 설정
export ANTHROPIC_API_KEY="sk-ant-..."
export RAG_CLI_MODE="standalone"
...

사용자 정의 설정을 위해 config/default.yaml을 편집하세요:

# 모델 선택 (Model selection)
embeddings:
model_name: sentence-transformers/all-MiniLM-L6-v2 # 빠름, 384-dim
...

# 플러그인 설치 테스트
/plugin
# 다음과 같이 표시되어야 합니다: RAG-CLI plugin is installed and loaded
...

가장 쉬운 설정을 위해 방법 1 (Marketplace)을 사용하세요.

문서들을 준비하세요:

# documents 디렉토리 생성
mkdir -p data/documents
# 파일 복사
...

지원되는 형식: Markdown, PDF, DOCX, HTML, TXT

Claude Code 또는 터미널에서:

# 옵션 1: Claude Code 플러그인으로 사용 (가장 쉬움)
/rag-project # 현재 프로젝트를 자동 인덱싱
# 옵션 2: 수동 인덱싱
...

Claude Code에게 문서에 관한 질문을 하세요:

Claude Code에서

/search "인증(authentication)은 어떻게 구성하나요?"

또는 Claude에게 직접 질문

...

# Claude Code에서
/rag-enable
# 이제 모든 질문에 문서 컨텍스트 (context)가 자동으로 포함됩니다

비활성화: /rag-disable

기존 워크플로 (Traditional workflow):

• 문서 검색 (브라우저, 도움말 파일)
• 관련 섹션 복사/붙여넣기
• Claude에게 문제에 대해 질문
• 소요 시간: 질문당 2-5분

RAG-CLI 사용 시:

• Claude에게 직접 질문
• RAG-CLI가 관련 문서를 자동으로 검색 (retrieves)
• Claude가 컨텍스트 (context)를 바탕으로 답변
• 소요 시간: 질문당 5초 미만

실제 영향: 세션당 10배 더 많은 질문을 처리할 수 있습니다.

RAG-CLI는 Claude에게 실제 문서, 코드 패턴, 그리고 프로젝트 컨벤션 (conventions)을 제공합니다:

RAG-CLI 미사용 시:

• Claude가 일반적인 가정을 함
• 권장 사항이 사용자의 패턴과 충돌할 수 있음
• 조언을 코드베이스 (codebase)와 대조하여 수동으로 검증해야 함

RAG-CLI 사용 시:

• Claude가 사용자의 정확한 요구사항을 파악함
• 권장 사항이 사용자의 컨벤션 (conventions)과 일치함
• 프로젝트에 특화된 컨텍스트 인식 (context-aware) 솔루션 제공

다음 사항들을 머릿속으로 추적하는 것을 중단하세요:

• API 문서 상세 내용
• 코드 구조 및 패턴
• 설정 요구사항
• 프로젝트를 위한 베스트 프랙티스 (best practices)

RAG-CLI가 이러한 컨텍스트 (context)를 자동으로 제공하여, 사용자가 실제 문제 해결에만 집중할 수 있도록 돕습니다.

API 사용:

• Claude Code 모드: 문서 검색을 위한 별도의 API 호출 없음
• 방대한 문서를 가진 대규모 프로젝트에서 비용 ($$) 절감

시간 절약:

• 문서 조회 시간 80% 감소
• 명확화 질문 (clarification questions) 50% 감소
• 더 빠른 코드 리뷰 및 아키텍처 결정

RAG-CLI를 사용하는 조직의 보고 내용:

지표 (Metric)	개선 사항 (Improvement)
개발 속도 (Development Speed)	완료 속도 30-40% 향상
...

RAG-CLI는 정교한 문서 검색 파이프라인 (document retrieval pipeline)을 구현합니다:

문서 인제스션 (Document Ingestion)- 지원 형식: Markdown, PDF, DOCX, HTML, TXT

• 자동 메타데이터 추출

• 지능형 청킹 (Intelligent chunking) (core.constants를 통해 설정 가능한 100토큰 오버랩을 포함한 500토큰 단위)

• 임베딩 생성 (Embedding Generation)

• 모델: sentence-transformers/all-MiniLM-L6-v2

• 빠름: 문서 100개당 200ms 미만

• 효율적: 384차원 벡터 (384-dimensional vectors)

• 반복 쿼리를 위한 캐싱 (Cached)

• 모델:

지능형 검색 (Intelligent Retrieval)

• 하이브리드 검색 (Hybrid search): 70% 의미론적 (semantic) + 30% 키워드 (keyword) (core.constants를 통해 설정 가능)

• 정확도를 위한 교차 인코더 재순위화 (Cross-encoder reranking)

• 신뢰도 점수와 함께 상위 K개 결과 반환 (기본값: 5, 최대: 100)

• 100ms 미만의 검색 시간

• 하이브리드 검색 (Hybrid search): 70% 의미론적 (semantic) + 30% 키워드 (keyword) (core.constants를 통해 설정 가능)

쿼리 강화 (Query Enhancement)

• 자동 문서 분류 (Automatic document classification)

• 지능형 컨텍스트 조립 (Intelligent context assembly)

• Claude Code를 위한 형식 적응 (Format adaptation)

• 인용 추적 (Citation tracking)

응답 생성 (Response Generation)

• Claude Haiku와의 통합 (빠르고 정확함)
• 더 나은 UX를 위한 스트리밍 응답 (Streaming responses)
• 자동 인용 삽입 (Automatic citation injection)
• 설정 가능한 출력 형식 (Configurable output formatting)

로컬 처리 (Local Processing):

• 모든 문서 처리는 로컬에서 수행됨
• 민감한 데이터가 외부 서비스로 전송되지 않음
• 완전한 개인정보 보호 및 보안
• 오프라인 사용 가능 (초기 인덱싱 이후)

성능 최적화 (Performance Optimized):

• HNSW 인덱싱을 사용하는 ChromaDB 벡터 저장소 (업계 표준)
• 처리량을 위한 배치 처리 (Batch processing)
• 응답성을 위한 비동기 작업 (Async operations)
• 메모리 효율적인 청킹 (Memory-efficient chunking)

프로덕션 준비 완료 (Production Ready):

• 포괄적인 에러 핸들링 (Error handling)
• 실패 시 우아한 성능 저하 (Graceful degradation)
• 상세한 로깅 및 모니터링
• 복잡한 쿼리를 위한 멀티 에이전트 오케스트레이션 (Multi-agent orchestration)

프론트엔드 (Frontend): Claude Code 플러그인
|
통합 계층 (Integration Layer): MCP 서버 + 훅 (Hooks) + 슬래시 명령어 (Slash Commands)
...

API 통합 (API Integration)

• 컨텍스트를 포함한 API 호출 자동 완성
• 문서를 바탕으로 파라미터 검증
• 코드에서 사용 예시 가져오기

버그 수정 (Bug Fixing)

• 문서에서 에러 메시지 검색
• 코드베이스에서 관련 이슈 찾기
• 베스트 프랙티스(Best practices)로부터 디버깅 힌트 얻기

코드 리뷰 (Code Review)

• 프로젝트 표준에 따라 자동으로 확인
• 관련 아키텍처 패턴 검색
• 베스트 프랙티스(Best practices)에 따라 검증

지식 베이스 (Knowledge Base)

• 팀 문서 동기화 유지
• 지식 베이스 (Knowledge Base) 즉시 질의
• "이거 어떻게 하나요..." 식의 질문 감소

온보딩 (Onboarding)

• 신입 개발자에게 문맥 인식 (Context-aware) 도움 제공
• 실제 문서를 바탕으로 질문에 답변
• 온보딩 시간 (Ramp-up time) 50% 단축

지속적 학습 (Continuous Learning)

• 학습 자료 즉시 검색
• 다양한 소스로부터 문맥 (Context) 확보
• 관련 개념 자동 연결

지식 합성 (Knowledge Synthesis)

• 여러 문서의 통찰력 (Insights) 결합
• 주제 간의 연결 고리 파악
• 포괄적인 이해를 더 빠르게 구축

RAG-CLI는 세 가지 운영 모드를 지원합니다:

API 키 불필요

• Claude Code 플러그인으로 실행 시 자동으로 감지됨
• Claude의 내부 처리를 위해 포맷팅된 문맥 (Context) 반환
• API 비용 발생 없이 최적의 성능 제공

Anthropic API 키 필요

• Claude로 직접 API 호출
• 모델 파라미터 (Model parameters)에 대한 완전한 제어
• 테스트 및 개발에 유용

하이브리드 (Hybrid)

• 환경 자동 감지
• 사용 가능한 경우 Claude Code 사용
• 필요 시 API로 전환 (Fallback)
• 최대의 유연성 제공

환경 변수를 통해 모드를 설정하세요:

export RAG_CLI_MODE="claude_code" # 또는 "standalone" 또는 "hybrid"

RAG-CLI/
src/
core/ # 핵심 RAG 파이프라인 (Core RAG pipeline)
...

문서 처리 (Document Processing): 문서 -> 청크 (Chunks, 400-500 토큰) -> 메타데이터 (Metadata) 추출
임베딩 생성 (Embedding Generation): 청크 -> sentence-transformers -> 384차원 벡터
벡터 저장 (Vector Storage): 임베딩 -> HNSW 인덱싱을 적용한 ChromaDB -> 영구 저장소
검색 (Retrieval): 질의 (Query) -> 하이브리드 검색 (Hybrid search) -> 재순위화 (Reranking) -> Top-K 결과
응답 생성 (Response Generation): 문맥 (Context) + 질의 (Query) -> Claude Haiku -> AI 응답

# 운영 모드
mode:
operation: hybrid # claude_code, standalone, 또는 hybrid
...

환경 변수 보호 (Environment Variable Protection):

절대로 .env 파일을 커밋하지 마세요: .env 파일은 민감한 API 키를 포함하고 있으므로 버전 관리 시스템에 절대로 커밋해서는 안 됩니다. - 이미 .gitignore에 포함되어 있습니다.

• config/templates/.env.template을 참조용으로 사용하세요

• 이미 포함되어 있습니다

파일 권한 (File Permissions): Unix 시스템에서는 .env가

제한된 권한을 가집니다: chmod 600 .env # 소유자만 읽기/쓰기 가능

API 키 저장 (API Key Storage):

• 모든 API 키는 .env 파일에만 저장하세요 - 소스 코드에 키를 하드코딩(hardcode)하지 마세요

• os.getenv()를 통해 환경 변수 (environment variables)를 사용하세요

• 모든 API 키를 저장하세요

서브프로세스 보안 (Subprocess Security): RAG-CLI는 서브프로세스 (subprocesses)를 생성할 때 환경 변수를 자동으로 정화 (sanitize)하여 다음과 같은 민감한 키를 제거합니다:
ANTHROPIC_API_KEY

TAVILY_API_KEY

OPENAI_API_KEY

설정 파일 (Configuration Files): config/ 내의 사용자별 설정은 gitignored 처리됩니다. config/defaults/ 및 config/templates/에 있는 기본 템플릿만 버전 관리 (version controlled)됩니다.

/search [query]

• 인덱싱된 문서 검색 /rag-enable

• 자동 RAG 강화 활성화 /rag-disable

• 자동 RAG 강화 비활성화 /rag-project

• 현재 프로젝트를 분석하고 관련 문서 인덱싱 /update-rag

• RAG-CLI 플러그인 파일 동기화

RAG 검색 기술 (retrieval skill)에 접속하세요:

/skill rag-retrieval "여기에 질문을 입력하세요"

RAG-CLI는 Claude Code 경험을 향상시키는 여러 후크 (hooks)를 포함하고 있습니다: