Merge pull request 'chore(graphify): hook 改放本機設定並移除不適用的 graph.json 規則' (#81) from chore/graphify-claude-integration into master

Reviewed-on: #81

.gitignore

@@ -28,3 +28,6 @@ yarn-error.log
 /frontend/.env
 
 
+
+# graphify 知識圖譜輸出（可由 graphify 重建，graph.json 每次整份重寫）
+/graphify-out

CLAUDE.md

@@ -213,3 +213,13 @@
 - 發現問題直接說，不要繞彎
 - 有不確定的地方，明確標注「我不確定，需要你確認」
 - 不要重複確認已經決定的技術選擇
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- When graphify-out/graph.json exists, run `graphify query "<question>"` before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

docs/GRAPHIFY.md

@@ -0,0 +1,58 @@
+# graphify 知識圖譜操作筆記
+
+graphify 把專案的程式碼、OpenSpec 文件、設定檔轉成可查詢的知識圖譜，輸出在 `graphify-out/`。
+該目錄被 `.gitignore` 忽略（`graph.json` 每次重建都整份重寫，進版控只會產生無意義 diff），換機器或清掉後需自行重建。
+
+規則（先 query 再 grep、改完程式碼跑 `graphify update .`）見根目錄 `CLAUDE.md`，此處不重複。
+
+## 建置紀錄（2026-10-29）
+
+- 規模：2429 節點、4369 邊、約 117 個社群
+- 來源：253 個程式碼檔以 AST 抽取；218 份文件與 5 張圖片以子代理做語意抽取
+- 語意抽取沒有設 `GEMINI_API_KEY`，由 Claude Code 的子代理擔任 LLM
+
+## 安裝與重建
+
+```bash
+uv tool install --upgrade graphifyy   # 安裝（Windows，graphify 位於 uv tool 目錄）
+/graphify .                           # 在 Claude Code 內完整建置
+graphify update .                     # 只重新處理變更的檔案（AST 免費，語意抽取才耗 token）
+graphify query "<問題>"               # 查詢既有圖譜
+```
+
+完整建置的語意抽取需派約 15 個子代理，**同時最多 4 個**（超過會被拒絕），要分批派。
+
+## 已知限制與踩過的坑
+
+| 項目 | 說明 | 處理 |
+|------|------|------|
+| enum case 引用 | AST 只看得到類別被引用，看不到 `BookingStatus::Pending` 這類 case 的使用處，所以 `Pending`／`Confirmed`／`Completed` 在圖上看起來孤立 | 查 enum case 的使用處改用 grep |
+| 腳本檔名 | 輔助腳本不可命名為 `ast.py`，會遮蔽標準函式庫造成循環匯入 | 換名稱，並用 `python -I` 執行 |
+| 二進位檔覆蓋率 | PNG 沒有「行數」，覆蓋率檢查會誤報 partial（`hero.png`） | 可忽略 |
+| 子代理只讀檔頭 | `.pi/agents/` 三個檔案只讀了檔頭，未寫入 manifest | 與 `.claude/agents/` 僅工具名稱寫法不同，已決定不補 |
+| 同端點邊合併 | YAML 中重複的鍵（如 `steps` 底下多個 `name`）會被合併成一條邊 | 正常現象，不是圖損壞 |
+
+## 社群命名
+
+graphify 預設以「連線最多的節點名稱 + cluster」命名社群。前 16 大社群已手動改名（依成員與所在資料夾判斷）：
+
+| 編號 | 名稱 |
+|------|------|
+| 0 | 預約狀態機與生命週期測試 |
+| 1 | 預約通知（Notification 類別） |
+| 2 | 早期 OpenSpec 設計文件（預約／評價／會員入口） |
+| 3 | 教練端前端（排程／評價／個人檔案） |
+| 4 | 預約即時訊息（Reverb 事件） |
+| 5 | 認證強化 spec（鎖定／OAuth state／稽核補強） |
+| 6 | 課程排程與預約 API |
+| 7 | 會員端前端（我的預約／課程列表） |
+| 8 | AuthController 認證 |
+| 9 | 前端與根目錄 package.json |
+| 10 | 課程詳情頁前端（評價／預約） |
+| 11 | 前端 Pinia 狀態與通知 |
+| 12 | 評價功能測試 |
+| 13 | Docker Compose 服務 |
+| 14 | Feature 測試基底與授權測試 |
+| 15 | 管理後台前端 |
+
+社群編號可能隨重建而改變，此表只對 2026-10-29 這次建置有效；重建後需重新核對。