4.0 KiB

Raw Permalink Blame History

Graphify Setup & Guide

이 문서는 프로젝트 내 코드 및 문서의 지식 그래프(Knowledge Graph)를 생성하고 유지관리하기 위한 graphify 도구의 설치부터 Ollama 모델 연동, 그리고 실시간 자동 갱신(Watch Mode)을 적용하는 과정을 다른 환경에서도 쉽게 따라 할 수 있도록 정리한 가이드입니다.

1. Graphify 설치 및 기본 환경 설정

graphify는 코드베이스, 문서 등을 분석하여 구조적/시맨틱(의미론적) 연결망을 만들어주는 지식 그래프 도구입니다.

Python 인터프리터 구성

시스템 전역 파이썬 대신 venv 등의 가상 환경에 구성된 파이썬을 이용하는 것을 권장합니다.

graphify 설치 명령어:

python3 -m pip install graphifyy -q --break-system-packages

에이전트(Claude 등)가 일관된 파이썬을 사용할 수 있게 프로젝트 루트에 .graphify_python 파일을 생성해 파이썬 경로를 저장합니다.
```
python3 -c "import sys; open('.graphify_python', 'w').write(sys.executable)"
```

2. 로컬 LLM (Ollama) 연동 및 시맨틱 분석

graphify는 문서나 코드의 주석 등을 기반으로 추론된 엣지(INFERRED)를 찾을 때 LLM을 사용합니다. 외부 API 대신 로컬 Ollama 모델을 활용하면 토큰 비용을 아낄 수 있습니다.

Ollama 연결 확인 및 모델 설정

로컬의 11434 포트에서 Ollama 데몬이 실행 중인지 확인합니다.
```
curl -s http://localhost:11434/api/tags > .ollama_tags.json
```
로드된 언어 모델(예: gemma4:e4b-it-q4_K_M, llama3 등)을 .ollama_models.json 캐시로 저장합니다.
이후 그래프 생성 명령 시 --ollama 플래그를 붙여 로컬 연동을 지시합니다.
```
/graphify . --ollama --model gemma4:e4b-it-q4_K_M
```

트러블슈팅: f-string 및 패키지 오류 (semantic_llm.py)

파이썬 버전 또는 패키지 업데이트 상태에 따라 Ollama API를 호출하는 semantic_llm.py 내부 로직에서 몇 가지 오류가 발생할 수 있습니다. (에이전트가 실행 시 자동 수정하거나, 수동으로 수정해야 합니다.)

f-string {} 파싱 오류: extract_semantic 프롬프트 내 JSON 예시의 괄호({, })가 f-string의 변수로 인식되어 ValueError가 발생할 수 있습니다. JSON 중괄호를 모두 {{, }}로 더블 이스케이프해야 합니다.
urllib Request 오류: urllib.request.Request 호출 시 content_type="application/json" 인자가 거부될 경우, headers={"Content-Type": "application/json"} 형태로 교체해야 합니다.

3. 지식 그래프 자동 갱신 설정 (Watch Mode)

개발 과정 중 코드나 문서가 빈번하게수정될 때, 그래프를 백그라운드에서 실시간으로 최신화하는 watch 모드를 설정할 수 있습니다. (문서 수정은 수동 업데이트 필요, 코드는 자동 재구성)

의존성 설치

watch 모드는 watchdog 라이브러리를 요구합니다.

python3 -m pip install watchdog

상태 감시 실행

터미널을 열어 아래 명령어를 유지합니다:

python3 -m graphify.watch .

코드 파일이 변경된 경우: 백그라운드에서 즉각적으로 AST 추출이 다시 실행되고 graph.json과 리포트가 갱신됩니다.
문서 파일이 변경된 경우: LLM 추론이 필요하므로 need_update 플래그만 기록합니다. 이후 에이전트나 사용자가 명시적으로 /graphify . --update 를 실행하여 최신화합니다.

4. 에이전트 설정(IDE Rules) 연계

CLAUDE.md 및 .cursorrules: AI 에이전트가 graphify 관련 요청을 받을 경우 SKILL.md를 우선 확인하도록 규칙이 지정되어 있습니다.
백그라운드에서 감지될 수 있도록 에이전트는 "대규모 리팩토링이나 구조 파악 전 GRAPH_REPORT.md 검토", "코드 작성 중 watchdog에 의한 자동 갱신 확인" 등을 수행합니다.

4.0 KiB Raw Permalink Blame History