Claude Code와 LightRAG로 구축하는 1인 개발자용 실무 지식 엔진

코드 한 줄 고치려고 문서를 뒤지는 시간은 아깝습니다. 혼자 북치고 장구치는 풀스택 개발자라면 더 그렇습니다. Claude Code가 프로젝트 구조를 제멋대로 해석해서 엉뚱한 코드를 짜준다면, 그건 AI의 지능 문제가 아니라 당신의 지식 보관함이 엉망이기 때문입니다. LightRAG를 단순 설치하는 수준을 넘어, 실제로 쓸모 있는 지능형 지식 창고로 굴리는 법을 정리했습니다.

엔티티 중심으로 프로젝트 문서 재구조화

LightRAG는 텍스트를 무작정 자르는 방식이 아닙니다. 단어와 단어 사이의 관계를 잇는 지식 그래프를 그립니다. AI가 내 코드의 맥락을 오해하지 않게 하려면 README.md부터 다시 써야 합니다. 평면적인 기능 나열은 무의미합니다.

문서 상단에 의존성을 명시하는 주석을 넣으세요. 예를 들어 (OrderProcessor, uses, PaymentService) 같은 이진 관계를 텍스트로 박아넣는 식입니다. 복잡한 관계일수록 잘게 쪼개서 설명할 때 LightRAG는 정확한 노드를 생성합니다. 서비스, 컨트롤러, DTO 간의 연결 고리를 명시적으로 적어두면 Claude Code가 내부 라이브러리 구조를 파악하지 못해 헛소리하는 현상을 잡을 수 있습니다. 실제로 관계가 명시된 문서를 인덱싱하면 아키텍처 관련 질문의 답변 신뢰도가 90% 이상으로 올라갑니다.

불필요한 인덱싱을 막는 데이터 필터링

로컬의 모든 파일을 다 먹이는 건 미련한 짓입니다. 토큰만 축내고 지식 그래프는 지저분해집니다. 특히 node_modules 같은 외부 의존성은 이미 AI가 세상 모든 데이터를 통해 학습한 내용입니다. 내 로컬 엔진까지 오염시킬 필요가 없습니다.

프로젝트 루트에 .ragignore 파일을 만드세요. 빌드 결과물이나 로그, 임시 파일은 가차 없이 제외해야 합니다.

• node_modules/, dist/, target/ 같은 빌드 폴더 제외
• *.log, tmp/ 등 실행 시 발생하는 휘발성 데이터 차단
• 중복된 인터페이스 정의가 있다면 @primary_definition 메타데이터를 핵심 파일에 추가해 우선순위 부여

불필요한 데이터를 걷어내는 것만으로도 검색 정확도는 90%를 상회하게 됩니다. 인덱스가 가벼워지니 검색 속도가 빨라지는 건 덤입니다.

Claude Code 연동을 위한 MCP 서버 최적화

Claude Code는 MCP를 통해 외부와 소통합니다. 이때 모든 텍스트를 통째로 넘기면 응답은 느려지고 지갑은 가벼워집니다. 핵심은 유사도 점수 $S$가 높은 상위 $k$개의 노드만 골라내는 선별 작업입니다.

$$D = \frac{\sum_{i=1}^{k} S(N_i)}{k}$$

MCP 설정에서 only_need_context 옵션을 켜고 딱 필요한 서브 그래프만 추출하도록 제한하세요. 질문의 성격에 따라 모드를 다르게 호출하는 지능이 필요합니다. 아키텍처를 물을 때는 global 모드를, 구체적인 함수 수정을 요청할 때는 local 모드를 쓰도록 매개변수를 짜두면 응답 속도가 2배 이상 빨라집니다. AI가 질문의 의도를 정확히 파악하고 가장 적절한 지식 노드를 참조하게 만드는 기술입니다.

로컬 리소스 배분과 안정성 확보

Docker로 LightRAG를 돌리면서 Claude Code까지 실행하면 내 컴퓨터 비명소리가 들릴 겁니다. 1인 개발 환경에서 시스템이 멈추면 작업 흐름도 끊깁니다. 리소스 제한 설정은 선택이 아닌 필수입니다.

16GB RAM 기준이라면 LightRAG 컨테이너에 4GB 정도만 떼어주세요. 나머지는 IDE와 로컬 LLM이 쓰도록 자리를 비워줘야 합니다. docker-compose.yaml에서 cpus: '2.0', memory: 4G 정도로 상한선을 그어두면 됩니다. 속도가 중요하다면 임베딩 모델로 레이턴시가 56ms 수준인 nomic-embed-text를 쓰는 게 속 편합니다. 정밀도가 절실하다면 90ms가 걸리더라도 text-embedding-3-small을 선택하는 저울질이 필요합니다.

Git Hook을 이용한 실시간 지식 업데이트

코드를 고칠 때마다 수동으로 인덱싱 명령을 치는 건 고역입니다. 인간은 결국 귀찮아서 업데이트를 안 하게 되고, AI는 어제의 코드를 바탕으로 오늘의 버그를 잡으려 들 겁니다.

Git의 post-commit 훅을 쓰면 해결됩니다. 코드를 커밋할 때마다 변경된 파일만 골라내서 LightRAG 서버에 던져주는 스크립트를 짜두세요. git diff-tree로 바뀐 파일 목록을 뽑고, .ragignore에 걸리지 않는 녀석들만 /insert 엔드포인트로 쏴주면 끝입니다. 이렇게 증분 인덱싱 체계를 갖춰두면 별다른 노력 없이도 Claude Code는 항상 '지금 이 순간'의 내 코드를 이해합니다. 수동 관리에 쓰던 시간을 줄여 하루에 최소 1시간은 더 확보할 수 있습니다.