From 7beed8f69e36f352440c0735a3ff7dfa062e05a8 Mon Sep 17 00:00:00 2001
From: artbiit <artbiit@naver.com>
Date: Thu, 9 Apr 2026 17:38:58 +0900
Subject: [PATCH] docs: update project configuration and add Graphify setup
 documentation

---
 .cursorrules                          |  3 +-
 .windsurfrules                        |  5 +++
 CLAUDE.md                             |  2 +
 Docs/Features/Graphify_Setup_Guide.md | 62 +++++++++++++++++++++++++++
 Docs/index.md                         |  1 +
 graphify-out/needs_update             |  1 +
 6 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 Docs/Features/Graphify_Setup_Guide.md
 create mode 100644 graphify-out/needs_update

diff --git a/.cursorrules b/.cursorrules
index 8179af2..45569b0 100644
--- a/.cursorrules
+++ b/.cursorrules
@@ -17,6 +17,7 @@
 - 봇이 성공적으로 온라인 상태(`Ready`)에 진입한 것을 확인한 뒤에만 사용자에게 작업 완료를 보고합니다.
 
 ## Graphify Rules
-- 사용자가 `/graphify` 혹은 지식 그래프 관련 질의를 할 경우, 프로젝트 루트의 `SKILL.md` 지침을 준수하여 실행합니다.
+- 사용자가 `/graphify` 혹은 지식 그래프 관련 질의를 할 경우, 프로젝트 루트의 `SKILL.md` 및 `Docs/Features/Graphify_Setup_Guide.md` 지침을 준수하여 실행합니다.
 - 대규모 리팩토링이나 구조 파악이 필요할 때는 `graphify-out/GRAPH_REPORT.md`를 우선적으로 참조하여 의존 관계를 파악합니다.
 - 로컬 Ollama 환경이 감지되면 (`http://localhost:11434`), 대량의 데이터 처리에 대해 `--ollama` 옵션 사용을 우선적으로 검토합니다.
+- 개발 및 잦은 코드 수정 시 항상 `python3 -m graphify.watch .` 를 백그라운드에 구동시켜 지식 그래프의 최신화를 자동화하는 것을 검토하십시오.
diff --git a/.windsurfrules b/.windsurfrules
index a1ade21..0db4f8a 100644
--- a/.windsurfrules
+++ b/.windsurfrules
@@ -16,3 +16,8 @@
 - 유저에게 노출되는 모든 기능(메시지, 임베드, 상태 메시지 등)을 구성할 때는 별도의 요청이 없더라도 **반드시 다국어 지원(i18n) 적용을 검토하고 구현**해야 합니다. (자세한 내용은 `Docs/Rules/i18n_guidelines.md` 참조)
 - 단순 문법 검증에 그치지 말고, `yarn dev` 등의 명령어로 봇을 백그라운드에서 직접 구동(Boot)시켜 DB/캐시 커넥트 및 이벤트 리스너 초기화 중 런타임 에러(예: Intents 권한 거부 등)가 발생하지 않는지 스스로 눈으로 확인하고 완벽히 디버깅해야 합니다.
 - 봇이 성공적으로 온라인 상태(`Ready`)에 진입한 것을 확인한 뒤에만 사용자에게 작업 완료를 보고합니다.
+
+## Graphify Rules
+- 사용자가 `/graphify` 혹은 지식 그래프 관련 질의를 할 경우, `SKILL.md`와 `Docs/Features/Graphify_Setup_Guide.md`의 워크플로우를 참조합니다.
+- 대규모 리팩토링이나 구조 파악이 필요할 때는 `graphify-out/GRAPH_REPORT.md`를 우선적으로 참조하여 의존 관계를 파악합니다.
+- 로컬 모델을 위한 시맨틱 추출이 필요한 경우 `--ollama` 옵션의 활용을 검토하며, 코드 기반 갱신은 `python3 -m graphify.watch .` 를 이용합니다.
diff --git a/CLAUDE.md b/CLAUDE.md
index 104a6a8..aa7c811 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,3 +1,5 @@
 # graphify
 - **graphify** (`SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`
 When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"` before doing anything else.
+- 프로젝트의 구조 변경이나 문서 갱신시 실시간 업데이트를 원한다면 `python3 -m graphify.watch .` 실행을 추천하세요.
+- Ollama 연동 및 트러블슈팅 설정 등은 `Docs/Features/Graphify_Setup_Guide.md` 문서를 참고하세요.
diff --git a/Docs/Features/Graphify_Setup_Guide.md b/Docs/Features/Graphify_Setup_Guide.md
new file mode 100644
index 0000000..e440dc7
--- /dev/null
+++ b/Docs/Features/Graphify_Setup_Guide.md
@@ -0,0 +1,62 @@
+# Graphify Setup & Guide
+
+이 문서는 프로젝트 내 코드 및 문서의 지식 그래프(Knowledge Graph)를 생성하고 유지관리하기 위한 `graphify` 도구의 설치부터 Ollama 모델 연동, 그리고 실시간 자동 갱신(Watch Mode)을 적용하는 과정을 다른 환경에서도 쉽게 따라 할 수 있도록 정리한 가이드입니다.
+
+## 1. Graphify 설치 및 기본 환경 설정
+
+`graphify`는 코드베이스, 문서 등을 분석하여 구조적/시맨틱(의미론적) 연결망을 만들어주는 지식 그래프 도구입니다.
+
+### Python 인터프리터 구성
+- 시스템 전역 파이썬 대신 `venv` 등의 가상 환경에 구성된 파이썬을 이용하는 것을 권장합니다.
+- `graphify` 설치 명령어:
+  ```bash
+  python3 -m pip install graphifyy -q --break-system-packages
+  ```
+- 에이전트(Claude 등)가 일관된 파이썬을 사용할 수 있게 프로젝트 루트에 `.graphify_python` 파일을 생성해 파이썬 경로를 저장합니다.
+  ```bash
+  python3 -c "import sys; open('.graphify_python', 'w').write(sys.executable)"
+  ```
+
+## 2. 로컬 LLM (Ollama) 연동 및 시맨틱 분석
+
+`graphify`는 문서나 코드의 주석 등을 기반으로 추론된 엣지(INFERRED)를 찾을 때 LLM을 사용합니다. 외부 API 대신 로컬 Ollama 모델을 활용하면 토큰 비용을 아낄 수 있습니다.
+
+### Ollama 연결 확인 및 모델 설정
+- 로컬의 `11434` 포트에서 Ollama 데몬이 실행 중인지 확인합니다.
+  ```bash
+  curl -s http://localhost:11434/api/tags > .ollama_tags.json
+  ```
+- 로드된 언어 모델(예: `gemma4:e4b-it-q4_K_M`, `llama3` 등)을 `.ollama_models.json` 캐시로 저장합니다.
+- 이후 그래프 생성 명령 시 `--ollama` 플래그를 붙여 로컬 연동을 지시합니다.
+  ```bash
+  /graphify . --ollama --model gemma4:e4b-it-q4_K_M
+  ```
+
+### 트러블슈팅: f-string 및 패키지 오류 (semantic_llm.py)
+파이썬 버전 또는 패키지 업데이트 상태에 따라 Ollama API를 호출하는 `semantic_llm.py` 내부 로직에서 몇 가지 오류가 발생할 수 있습니다. (에이전트가 실행 시 자동 수정하거나, 수동으로 수정해야 합니다.)
+1. **f-string `{}` 파싱 오류**: `extract_semantic` 프롬프트 내 JSON 예시의 괄호(`{`, `}`)가 f-string의 변수로 인식되어 `ValueError`가 발생할 수 있습니다. JSON 중괄호를 모두 `{{`, `}}`로 더블 이스케이프해야 합니다.
+2. **urllib Request 오류**: `urllib.request.Request` 호출 시 `content_type="application/json"` 인자가 거부될 경우, `headers={"Content-Type": "application/json"}` 형태로 교체해야 합니다.
+
+## 3. 지식 그래프 자동 갱신 설정 (Watch Mode)
+
+개발 과정 중 코드나 문서가 빈번하게수정될 때, 그래프를 백그라운드에서 실시간으로 최신화하는 `watch` 모드를 설정할 수 있습니다. (문서 수정은 수동 업데이트 필요, 코드는 자동 재구성)
+
+### 의존성 설치
+watch 모드는 `watchdog` 라이브러리를 요구합니다.
+```bash
+python3 -m pip install watchdog
+```
+
+### 상태 감시 실행
+터미널을 열어 아래 명령어를 유지합니다:
+```bash
+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`에 의한 자동 갱신 확인" 등을 수행합니다.
diff --git a/Docs/index.md b/Docs/index.md
index e21659b..435b415 100644
--- a/Docs/index.md
+++ b/Docs/index.md
@@ -10,6 +10,7 @@
 ## 기능 명세 (Features)
 
 - [임시 음성 채널 자동화 (Temp Voice Channels)](Features/temp_voice_channels.md)
+- [Graphify 설정 및 연동 가이드 (Graphify Setup Guide)](Features/Graphify_Setup_Guide.md)
 
 ## 기획서 (Plans)
 
diff --git a/graphify-out/needs_update b/graphify-out/needs_update
new file mode 100644
index 0000000..56a6051
--- /dev/null
+++ b/graphify-out/needs_update
@@ -0,0 +1 @@
+1
\ No newline at end of file