問題循環：
  Agent 收到任務
  → 不知道程式碼結構
  → 啟動 Explore Sub-Agent
  → grep/glob/Read 大量檔案
  → Context Window 被無關內容填滿
  → Token 爆炸
  → 回答品質下降
  → 需要更多輪對話修正
  → Token 再次爆炸

原始程式碼
  → Tree-sitter Parser（語言特定）
  → AST（抽象語法樹）
  → Language-specific Queries（語言特定查詢）
  → Node（符號節點）+ Edge（關係邊）

# 查看資料庫統計
codegraph status

# 輸出範例：
# Project: /path/to/your-project
# Database: .codegraph/codegraph.db
# Files: 1,234 indexed
# Symbols: 45,678
# Edges: 123,456
# Journal: wal
# Last sync: 2 seconds ago

# 手動啟動（除錯用）
codegraph serve --mcp

# 正常使用時由 Agent 自動啟動（透過 MCP 設定檔）

Step 1: Agent 啟動 Explore Sub-Agent
Step 2: grep "database" --include="*.java" -r src/          → 讀取 50+ 個檔案片段
Step 3: glob "src/**/*Controller.java"                       → 列出 30 個 Controller
Step 4: Read src/main/java/.../UserController.java           → 讀取 500 行
Step 5: grep "UserService" -r src/                           → 再次掃描
Step 6: Read src/main/java/.../UserService.java              → 讀取 300 行
Step 7: grep "UserRepository" -r src/                        → 再次掃描
Step 8: Read src/main/java/.../UserRepository.java           → 讀取 200 行
Step 9: grep "@Entity" -r src/                               → 再次掃描
Step 10: Read src/main/java/.../User.java                    → 讀取 150 行
... 重複 15-25 次 Tool Calls ...

Step 1: codegraph_trace("handleRequest", "executeQuery")     → 一次呼叫取得完整呼叫鏈
Step 2: codegraph_explore(相關符號 IDs)                       → 一次呼叫取得所有原始碼
... 完成，共 2-5 次 Tool Calls ...

Context 污染率 = 不相關內容 Token / 總 Context Token × 100%

傳統模式：
  不相關 Token: ~45,000 (grep + glob + 完整檔案)
  相關 Token: ~5,000
  污染率: 90%

CodeGraph 模式：
  不相關 Token: ~500
  相關 Token: ~2,000
  污染率: 20%

傳統模式累計成本 = N × (grep_cost + glob_cost + read_cost) × query_count
CodeGraph 累計成本 = index_cost(一次) + MCP_query_cost × query_count

其中：
  index_cost ≈ 0（本地運算，無 Token 消耗）
  MCP_query_cost << grep_cost + glob_cost + read_cost

# Agent 想找 UserService 的呼叫者
grep -r "UserService" src/
# 回傳：Import 語句、字串常數、註解、實際呼叫... 全部混在一起
# → 大量不相關結果

# Agent 使用 MCP 工具
codegraph_callers("UserService.findById")
# 回傳：精確的呼叫者列表
# → UserController.getUser() @ user.controller.ts:45
# → AdminService.lookupUser() @ admin.service.ts:78
# → 零雜訊

# 方法 1：PowerShell 一鍵安裝（推薦）
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

# 方法 2：npm 安裝（若已有 Node.js）
npx @colbymchenry/codegraph

# 方法 3：全域安裝
npm i -g @colbymchenry/codegraph

# 方法 1：Shell 一鍵安裝（推薦）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 方法 2：npm 安裝
npx @colbymchenry/codegraph

# 方法 3：全域安裝
npm i -g @colbymchenry/codegraph

# 零安裝執行（推薦初次體驗）
npx @colbymchenry/codegraph

# 全域安裝（推薦長期使用）
npm i -g @colbymchenry/codegraph

# 互動式安裝（推薦）
codegraph install

# 安裝程式會：
# 1. 自動偵測已安裝的 Agent（Claude Code, Cursor, Codex CLI, ...）
# 2. 詢問要設定哪些 Agent
# 3. 詢問是否全域安裝（所有專案）或本地安裝（僅目前專案）
# 4. 寫入各 Agent 的 MCP Server 設定
# 5. 設定 Claude Code 的 auto-allow 權限
# 6. 初始化目前專案（本地安裝時）

# 自動偵測 Agent，全域安裝
codegraph install --yes

# 指定 Agent，全域安裝
codegraph install --target=cursor,claude --yes

# 指定 Agent，本地安裝
codegraph install --target=auto --location=local

# 僅印出設定檔片段（不寫入檔案）
codegraph install --print-config codex

# 進入專案目錄
cd your-project

# 初始化並建立索引（推薦）
codegraph init -i

# 或分步執行：
codegraph init        # 建立 .codegraph/ 目錄
codegraph index       # 建立索引

# 強制重建索引（全量）
codegraph index --force

# 靜默模式（減少輸出）
codegraph index --quiet

# 增量同步（僅更新變更的檔案）
codegraph sync

# 查看索引狀態
codegraph status

# 輸出範例：
# Project: D:\projects\my-spring-boot-app
# Database: .codegraph/codegraph.db
# Files:    1,234 indexed
# Symbols:  45,678
# Edges:    123,456
# Journal:  wal
# Last sync: 3 seconds ago

# 搜尋符號（驗證索引是否正常）
codegraph query "UserService"

# 查看檔案結構
codegraph files

# 查看呼叫者
codegraph callers "UserService.findById"

# 查看影響範圍
codegraph impact "UserService" --depth 2

# 從所有 Agent 移除 CodeGraph 設定
codegraph uninstall

# 從特定 Agent 移除
codegraph uninstall --target=cursor

# 非互動式
codegraph uninstall --yes

# 移除專案索引
codegraph uninit

# 強制移除（跳過確認）
codegraph uninit --force

codegraph query "UserService" --kind class --limit 10 --json

# Agent 需要找 UserService
→ codegraph_search("UserService")
→ 結果：
  [{id: 42, name: "UserService", kind: "class", file: "src/services/user.service.ts", line: 15}]

# 對比傳統模式：
→ grep -r "UserService" src/
→ 回傳 50+ 行匹配（import、字串、註解...混雜）

codegraph context "fix login bug" --format markdown --max-nodes 20

# 追蹤「登入請求如何到達資料庫」
→ codegraph_trace("LoginController.login", "UserRepository.findByUsername")
→ 結果：
  LoginController.login()
    → AuthService.authenticate()
      → UserService.findByUsername()
        → UserRepository.findByUsername()
  每一跳附帶完整原始碼

codegraph callers "UserService.findById" --limit 20 --json

codegraph callees "AuthService.authenticate" --limit 20 --json

codegraph impact "UserService" --depth 3 --json

# 修改 UserService.findById 的影響範圍
→ codegraph_impact("UserService.findById", depth=2)
→ 結果：
  直接影響（depth=1）：
    - UserController.getUser()
    - AdminService.lookupUser()
    - UserBatchJob.processUsers()
  間接影響（depth=2）：
    - API: GET /api/users/:id
    - API: GET /admin/users/:id
    - Batch: UserBatchScheduler.run()

codegraph files --format tree --max-depth 3 --filter "*.java"

# 確認 MCP Server 正在運行
# 在 Claude Code 中輸入：
/mcp

# 應看到 codegraph 的 MCP server 列表

請分析這個專案的整體架構。

使用 codegraph_context 取得主要 entry points，
然後用 codegraph_trace 追蹤核心流程：
1. HTTP 請求 → Controller → Service → Repository → Database
2. 識別主要的設計模式
3. 列出模組間的依賴關係

請盤點所有 REST API 端點。

步驟：
1. 使用 codegraph_search 搜尋所有 route 類型的符號
2. 使用 codegraph_callees 查看每個端點呼叫的 Service
3. 整理成表格：HTTP Method | URL | Controller | Service | 說明

用戶反映 /api/users/:id 回傳 500 錯誤。

請：
1. 使用 codegraph_search 找到處理此 API 的 Controller 方法
2. 使用 codegraph_trace 追蹤從 Controller 到 Repository 的完整呼叫鏈
3. 使用 codegraph_explore 查看每個環節的原始碼
4. 分析可能的 NullPointerException 或例外未處理的位置

/api/reports 端點回應很慢。

請：
1. 使用 codegraph_trace 追蹤完整呼叫鏈
2. 使用 codegraph_callees 查看是否有 N+1 查詢問題
3. 標記可能的效能瓶頸（迴圈中的 DB 查詢、未快取的計算等）

我想將 UserService.findById 的回傳型別從 User 改為 Optional<User>。

請：
1. 使用 codegraph_impact 分析這個變更的影響範圍
2. 列出所有需要修改的檔案和方法
3. 按依賴順序規劃修改步驟
4. 確保不遺漏任何呼叫者

我想將 UserService 中的密碼相關邏輯提取為獨立的 PasswordService。

請：
1. 使用 codegraph_node 查看 UserService 的完整程式碼
2. 使用 codegraph_callers 分析密碼相關方法的呼叫者
3. 使用 codegraph_impact 評估提取後的影響
4. 規劃提取步驟並確保向後相容

請新增「使用者暱稱變更」功能。

步驟：
1. 使用 codegraph_search 找到現有的 User 相關類別
2. 使用 codegraph_explore 查看 UserController, UserService, UserRepository 的程式碼
3. 參考現有的類似功能（如 email 變更）的呼叫鏈
4. 按照相同的架構模式實作新功能

請實作「管理員可以停用使用者帳號」功能。

步驟：
1. 使用 codegraph_trace 理解現有的使用者狀態管理流程
2. 使用 codegraph_callers 分析 UserService 的所有呼叫者
3. 確認 Admin 相關的權限檢查機制
4. 在正確的層級加入 disable 功能

# CodeGraph 使用指引

## 開發規範
- 在探索程式碼結構時，優先使用 CodeGraph MCP 工具
- 禁止使用 grep/glob/Read 進行大範圍搜尋
- 修改程式碼前，必須先用 codegraph_impact 分析影響範圍

## 工具使用優先順序
1. codegraph_search — 找符號
2. codegraph_trace — 追蹤呼叫鏈
3. codegraph_impact — 影響分析
4. codegraph_explore — 查看相關程式碼
5. Read — 僅在需要查看 CodeGraph 未索引的檔案時使用

// .vscode/settings.json 或全域 settings.json
{
  "github.copilot.chat.mcp.servers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

@workspace 請使用 codegraph_search 找到所有 Controller 類別，
然後用 codegraph_callers 分析 UserController 的呼叫鏈。
不要使用 grep 或 glob 搜尋。

@workspace 我要修改 UserService.java 的 findById 方法簽名。
請用 codegraph_impact 分析影響範圍，
然後列出所有需要同步修改的檔案。

## AI 開發規範

### 搜尋策略
- ✅ 優先使用 CodeGraph MCP 工具進行符號搜尋和呼叫鏈追蹤
- ✅ 使用 codegraph_impact 進行變更影響分析
- ❌ 禁止使用 grep/find/rg 進行全 Repository 掃描
- ❌ 禁止遞迴讀取整個目錄

### 上下文建構
- ✅ 使用 codegraph_context 建構任務相關上下文
- ✅ 使用 codegraph_explore 查看多個相關符號
- ❌ 禁止一次讀取超過 3 個完整檔案

# Copilot + CodeGraph 開發指引

## 程式碼探索
當需要理解程式碼結構時：
1. 先用 codegraph_search 找到入口點
2. 用 codegraph_trace 追蹤呼叫鏈
3. 用 codegraph_explore 查看相關程式碼
4. 僅在必要時才使用 Read 讀取完整檔案

## 修改前必做
- 使用 codegraph_impact 分析影響範圍
- 確認所有受影響的呼叫者已被考慮
- 按依賴順序規劃修改步驟

## 效能意識
- 每次對話盡量控制在 5 次以內的 MCP 工具呼叫
- 避免重複查詢相同的符號
- 使用 codegraph_explore 一次取得多個符號，而非逐一 codegraph_node

# 搜尋所有 Controller / Servlet
codegraph query "Controller" --kind class
codegraph query "Servlet" --kind class

# 搜尋所有路由定義
codegraph query "@RequestMapping" --kind route
codegraph query "@GetMapping" --kind route

# 追蹤：登入請求 → 認證 → 資料庫驗證
→ codegraph_trace("LoginController.login", "UserDAO.findByUsername")

# 追蹤：訂單建立 → 庫存檢查 → 付款
→ codegraph_trace("OrderController.createOrder", "PaymentService.process")

# 使用 Claude Code Prompt：
請幫我建立這個遺留系統的架構概覽。

步驟：
1. 用 codegraph_files 查看專案結構
2. 用 codegraph_search 找到所有 Controller / Service / DAO 類別
3. 用 codegraph_trace 追蹤 3-5 個核心業務流程
4. 整理成架構圖（用 Mermaid）
5. 列出所有模組間的依賴關係

# 分析某個 Service 的完整依賴鏈
→ codegraph_callees("OrderService")
→ 列出：
  - ProductService（庫存查詢）
  - PricingService（價格計算）
  - PaymentGateway（支付閘道）
  - NotificationService（通知）
  - OrderRepository（資料持久化）

# 反向分析：誰依賴 OrderService
→ codegraph_callers("OrderService")
→ 列出：
  - OrderController（API 層）
  - BatchOrderProcessor（批次處理）
  - OrderMigrationJob（資料遷移）

# 盤點所有 Spring 路由
→ codegraph_search("@GetMapping")  + codegraph_search("@PostMapping") + ...

# 或直接搜尋 route 類型符號
→ codegraph_search("route", kind="route")

# 然後追蹤每個端點的完整處理鏈
→ codegraph_trace(route_handler, database_method)

# 1. 建立索引（約 2-5 分鐘，依專案大小）
cd /path/to/legacy-system
codegraph init -i

# 2. 確認索引
codegraph status
# Files: 3,456 indexed
# Symbols: 89,012
# Edges: 234,567

# 3. 盤點 API 端點
codegraph query "@RequestMapping" --kind route --json | wc -l
# 結果：287 個 API 端點

# 4. 找出核心 Service
codegraph query "Service" --kind class --limit 50

# 5. 分析核心流程（透過 Claude Code）
# Prompt: 請追蹤 OrderController.createOrder 到 Database 的完整流程

# Step 1: 盤點 javax 使用
codegraph query "javax" --json | jq '.[] | .file' | sort -u
# 結果：列出所有使用 javax 的檔案

# Step 2: 分析 SecurityConfig 影響
codegraph impact "SecurityConfig" --depth 3

# Step 3: 使用 Claude Code 進行升級
# Prompt：
請將此專案從 Spring Boot 2 升級到 Spring Boot 4。

步驟：
1. 用 codegraph_search 找到所有 javax.* import
2. 用 codegraph_impact 分析 SecurityConfig 的影響範圍
3. 用 codegraph_trace 追蹤 Security Filter Chain
4. 按依賴順序修改：Entity → Repository → Service → Controller → Config

# 找出使用已移除功能的程式碼
codegraph query "SecurityManager" --kind class
codegraph query "Finalize" --kind method

# 分析影響範圍
codegraph impact "SecurityManager" --depth 2

# Claude Code Prompt：
請分析從 Java 17 升級到 Java 25 需要修改的程式碼。
使用 codegraph_search 搜尋以下已移除/變更的 API：
- SecurityManager
- finalize()
- Deprecated for removal 的 API
列出所有影響並規劃修改順序。

# 找出 Vue 2 特定語法
codegraph query "Vue.filter" --kind function
codegraph query "Vue.mixin" --kind function
codegraph query "$listeners" --kind variable

# 分析 Options API → Composition API 的影響
codegraph impact "data()" --depth 2

# Claude Code Prompt：
請分析 Vue 2 → Vue 3 升級的影響範圍。
使用 codegraph_search 找到所有：
1. Vue.filter / Vue.directive / Vue.mixin
2. $listeners / $children / $on / $off
3. Vuex store 模式（需遷移到 Pinia）
4. Vue Router 3.x 語法

# 找出 AngularJS 特定模式
codegraph query "angular.module" --kind function
codegraph query "$scope" --kind variable
codegraph query "$http" --kind variable

# 追蹤 Controller → Service 關係
codegraph trace "MainController" "ApiService"

# Claude Code Prompt：
請分析 AngularJS → Angular 遷移的影響範圍。
使用 codegraph_search 找到所有：
1. angular.module 定義
2. $scope 使用
3. $http / $resource 呼叫
4. directive 定義
列出需要遷移的元件並建立遷移優先順序。

# 基本用法：指定變更檔案
codegraph affected src/utils.ts src/api.ts

# 從 git diff 取得變更檔案
git diff --name-only | codegraph affected --stdin

# 自訂測試檔案模式
codegraph affected src/auth.ts --filter "e2e/*"

# JSON 輸出
codegraph affected src/auth.ts --json

# 僅輸出檔案路徑（適合 CI/CD）
codegraph affected src/auth.ts --quiet

#!/usr/bin/env bash
# 在 CI 中僅執行受影響的測試
AFFECTED=$(git diff --name-only HEAD~1 | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  echo "Running affected tests: $AFFECTED"
  npx vitest run $AFFECTED
fi

# GitHub Actions 整合
- name: Run affected tests
  run: |
    AFFECTED=$(git diff --name-only ${{ github.event.before }} | codegraph affected --stdin --quiet)
    if [ -n "$AFFECTED" ]; then
      npm test -- $AFFECTED
    fi

# 追蹤密碼從前端到資料庫的完整路徑
→ codegraph_trace("LoginController.login", "UserRepository.save")

# 追蹤 PII 資料流
→ codegraph_trace("UserController.createUser", "UserDAO.insert")

# 找到所有處理密碼的函式
→ codegraph_search("password")
→ codegraph_search("encrypt")
→ codegraph_search("hash")

請協助進行 Threat Modeling。

步驟：
1. 用 codegraph_search 找到所有認證相關類別（Auth*, Login*, Security*）
2. 用 codegraph_trace 追蹤認證流程的完整呼叫鏈
3. 用 codegraph_callers 找到所有存取敏感資料的入口
4. 標記信任邊界：Controller（外部）→ Service（內部）→ Repository（資料）
5. 列出每個邊界的潛在威脅

# 審查某個 PR 修改的方法，檢查所有呼叫者是否有適當的權限檢查
→ codegraph_callers("UserService.deleteUser")
→ 驗證每個呼叫者都經過 @PreAuthorize 或權限檢查

# 檢查新增的 API 端點是否在安全範圍內
→ codegraph_search("@RequestMapping")
→ 比對 SecurityConfig 中的 antMatchers

請對 UserService.deleteUser 方法進行安全審查。

步驟：
1. 用 codegraph_node 查看方法實作
2. 用 codegraph_callers 找到所有呼叫者
3. 用 codegraph_trace 追蹤每個呼叫路徑
4. 檢查每條路徑是否有：
   - 認證檢查（Authentication）
   - 授權檢查（Authorization / @PreAuthorize）
   - 輸入驗證（@Valid / @Validated）
   - 審計日誌（Audit Log）
5. 標記缺少安全控制的路徑

# 場景：發現 SQL Injection 漏洞在 UserRepository.findByName
→ codegraph_callers("UserRepository.findByName")
→ 找到所有呼叫者

→ codegraph_impact("UserRepository.findByName", depth=3)
→ 找到所有可能受影響的 API 端點

# 快速修復範圍評估
→ codegraph_explore([affected_symbols])
→ 查看所有需要修改的程式碼

# 當某個第三方函式庫有 CVE 時，評估影響範圍
→ codegraph_search("VulnerableLibrary")
→ codegraph_impact("VulnerableLibrary.method", depth=3)
→ 列出所有直接和間接依賴此函式庫的程式碼

# 安裝
npm install -g @colbymchenry/codegraph

# 初始化（互動模式）
cd /your/project
codegraph init -i

# 驗證
codegraph status

## 搜尋策略
- 必須先嘗試 CodeGraph MCP 工具
- 僅在 CodeGraph 無法處理時才使用 grep/Read
- 禁止對已索引檔案使用 glob 搜尋

# 檢查 Agent 的 Tool Call 分布
# 在 Claude Code 中：
/cost   # 查看 Token 消耗
# 觀察 MCP tool calls vs grep/Read 的比例

[任務描述]

CodeGraph 策略：
1. 先用 codegraph_context 取得任務上下文
2. 用 codegraph_search 定位相關符號
3. 用 codegraph_trace 追蹤呼叫鏈
4. 用 codegraph_impact 分析影響範圍
5. 用 codegraph_explore 查看相關程式碼
6. 不要使用 grep 或讀取整個檔案

# .github/workflows/codegraph.yml
name: CodeGraph Affected Tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @colbymchenry/codegraph
      - run: codegraph init -i
      - name: Run affected tests only
        run: |
          AFFECTED=$(git diff --name-only origin/main | codegraph affected --stdin --quiet)
          if [ -n "$AFFECTED" ]; then
            npm test -- $AFFECTED
          fi

# .husky/pre-commit
#!/usr/bin/env bash
# 在 commit 前同步索引
codegraph sync

# PR 描述模板中加入 Impact Analysis
## 影響範圍分析（由 CodeGraph 產生）
[codegraph impact 結果]

## 受影響的測試
[codegraph affected 結果]

# 定期檢查團隊的 Token 使用趨勢
# Claude Code:
/cost  # 單次對話成本

# 建立基準線
# Week 1: 記錄無 CodeGraph 的平均 Token 使用
# Week 2: 記錄有 CodeGraph 的平均 Token 使用
# 計算改善比例

# 方法 1：根目錄索引（小型 Monorepo）
cd /monorepo
codegraph init -i

# 方法 2：分模組索引（大型 Monorepo）
cd /monorepo/packages/auth
codegraph init -i

cd /monorepo/packages/api
codegraph init -i

# 方法 3：透過 .gitignore 排除不需要的模組
# .gitignore（CodeGraph 自動尊重 .gitignore 規則）
node_modules/
dist/
build/
*.generated.ts
packages/deprecated-*

# 前後端分離專案
frontend/ (TypeScript/React)
backend/ (Java/Spring Boot)
shared/ (Protocol Buffers)

# CodeGraph 可在同一索引中處理多語言
codegraph init -i
# 自動偵測並索引所有支援的語言

# 追蹤前端 API 呼叫到後端 Controller
→ codegraph_search("fetchUsers")  # 前端 API 呼叫
→ codegraph_search("GET /api/users")  # 後端路由
→ codegraph_trace("UsersApi.fetchUsers", "UserRepository.findAll")

# 方案 1：將索引加入 .gitignore（推薦）
# .gitignore
.codegraph/

# 每個開發者本地執行 codegraph init -i
# 優點：索引與本地環境一致
# 缺點：每人需要初始化一次

# 方案 2：CI/CD 中建立索引
# 優點：一致的索引
# 缺點：需要 CI 支援

# 新成員 onboarding 腳本
#!/usr/bin/env bash

echo "=== CodeGraph 初始化 ==="
npm install -g @colbymchenry/codegraph
codegraph init -i
codegraph status

echo "=== 專案架構概覽 ==="
codegraph query "Controller" --kind class --limit 20
codegraph query "Service" --kind class --limit 20
codegraph query "Repository" --kind class --limit 20

echo "=== 核心流程追蹤 ==="
codegraph trace "OrderController.createOrder" "OrderRepository.save"

# 檢查索引大小
ls -lh .codegraph/codegraph.db

# 大型專案的效能建議
# 1. 排除不需要索引的檔案
# .gitignore（CodeGraph 自動尊重 .gitignore 規則）
*.min.js
*.bundle.js
vendor/
generated/

# 2. 重建索引（當索引損壞或過於碎片化）
codegraph index --force

import CodeGraph from '@colbymchenry/codegraph';

// 初始化並開啟專案索引
const cg = await CodeGraph.init('/path/to/project');
// 或開啟已建立的索引：
// const cg = await CodeGraph.open('/path/to/project');

// 建立全量索引（含進度回報）
await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

// 搜尋符號
const results = cg.searchNodes('UserService');

// 查詢呼叫者
const callers = cg.getCallers(results[0].node.id);

// 為 AI 任務建構上下文
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown'
});

// 影響範圍分析
const impact = cg.getImpactRadius(results[0].node.id, 2);

// 啟動檔案監視（自動同步）
cg.watch();

// 停止監視
cg.unwatch();

// 關閉連線
cg.close();

# [公司/團隊名稱] AI 輔助開發規範 v1.0

## 1. 適用範圍
本規範適用於使用 AI Agent（Claude Code, GitHub Copilot）進行開發的所有專案。

## 2. 工具使用規範

### 2.1 必須使用 CodeGraph
- 所有已索引的專案，Agent 必須優先使用 CodeGraph MCP 工具
- 禁止在已索引專案中使用 grep/glob 進行全域搜尋
- 修改程式碼前，必須使用 codegraph_impact 進行影響分析

### 2.2 Prompt 撰寫規範
- 任務 Prompt 必須包含明確的 CodeGraph 使用指示
- 使用標準 Prompt 模板（見附錄）
- 禁止使用 "幫我重構整個專案" 等模糊指令

### 2.3 Token 成本意識
- 每個開發者每日 Token 預算：[設定上限]
- 大型分析任務（> 50K Token）需事先申請
- 定期檢查 /cost 並回報異常消耗

## 3. 安全規範

### 3.1 程式碼審查
- AI 產生的程式碼必須經過人工 Code Review
- 安全相關程式碼（認證、授權、加密）禁止直接採用 AI 建議
- AI 產生的 SQL 查詢必須檢查注入風險

### 3.2 敏感資訊
- 禁止在 Prompt 中包含真實密碼、API Key、Token
- 禁止將生產環境的資料庫連線資訊傳給 Agent
- 使用環境變數和 Secret Manager 管理敏感設定

## 4. 品質規範

### 4.1 測試要求
- AI 產生的功能程式碼必須包含對應的單元測試
- 使用 codegraph affected 確認測試覆蓋率
- 重構後必須執行完整測試套件

### 4.2 文件要求
- 複雜的 AI 輔助修改必須在 PR 描述中說明使用的 Prompt
- 架構變更必須更新相關文件

.github/prompts/
├── architecture/
│   ├── analyze-system.md
│   ├── trace-flow.md
│   └── dependency-map.md
├── bugfix/
│   ├── locate-bug.md
│   ├── root-cause-analysis.md
│   └── regression-check.md
├── refactoring/
│   ├── extract-service.md
│   ├── impact-analysis.md
│   └── safe-rename.md
├── security/
│   ├── threat-model.md
│   ├── security-review.md
│   └── vulnerability-scan.md
└── onboarding/
    ├── system-overview.md
    ├── core-flow.md
    └── module-guide.md

# .github/prompts/bugfix/locate-bug.md
---
description: "使用 CodeGraph 定位 Bug"
---

## 任務
定位以下 Bug：{{BUG_DESCRIPTION}}

## CodeGraph 策略
1. 用 codegraph_search 找到相關類別/方法
2. 用 codegraph_trace 追蹤呼叫鏈
3. 用 codegraph_explore 查看相關程式碼
4. 分析可能的根因

## 注意事項
- 不要使用 grep 搜尋
- 不要讀取完整檔案
- 列出所有可能的根因，並標記可能性高低

❌ 錯誤做法：
cd /home/user
codegraph init -i  # 在 home 目錄執行

✅ 正確做法：
cd /path/to/your/project  # 先切換到專案根目錄
codegraph init -i

❌ 問題：索引包含大量無用檔案
   → 索引緩慢、搜尋結果雜亂

✅ 解決方案：
CodeGraph 自動排除 node_modules、vendor、dist、build、target 等目錄，
並尊重 .gitignore 規則。若仍有索引不需要的檔案，將其加入 .gitignore：
# .gitignore
coverage/
.next/
*.min.js
*.bundle.js

❌ 問題：修改了程式碼但 CodeGraph 索引仍是舊的
   → Agent 查詢結果與實際程式碼不一致

✅ 解決方案：
# CodeGraph v0.9.7 內建 Auto-Sync（檔案監視自動增量同步）
# 如果自動同步未生效：
codegraph sync  # 手動同步

# 嚴重不一致時重建索引：
codegraph init -i --force

❌ 問題：Agent 說「找不到 CodeGraph 工具」

✅ 解決方案：
# Claude Code:
/mcp  # 檢查 MCP Server 列表

# VS Code Copilot:
# 檢查 settings.json 中的 mcp.servers 配置

# 通用：
codegraph status  # 確認索引健康

❌ 問題：在純 Markdown / 純 Config 專案使用 CodeGraph
   → 索引為空或幾乎為空

✅ 解決方案：
# CodeGraph 僅對程式碼有效（20+ 支援語言）
# 文件專案、純配置專案不適用
codegraph status  # 檢查 Symbols 數量
# 如果 Symbols = 0，則專案可能不適合使用 CodeGraph

❌ 錯誤做法：
Prompt: "幫我用 grep 找到所有使用 UserService 的地方"

✅ 正確做法：
Prompt: "用 codegraph_search 找到 UserService，
然後用 codegraph_callers 查看所有呼叫者"

❌ 錯誤做法：
Prompt: "請讀取 src/services/user.service.ts 並分析"
→ 回傳整個檔案（可能數百行）

✅ 正確做法：
Prompt: "用 codegraph_node 查看 UserService.findById 的實作"
→ 僅回傳相關方法（數十行）

❌ 錯誤做法：
→ codegraph_node(id=1)
→ codegraph_node(id=2)
→ codegraph_node(id=3)
→ 3 次 Tool Calls

✅ 正確做法：
→ codegraph_explore([1, 2, 3])
→ 1 次 Tool Call，包含所有相關程式碼

❌ 錯誤做法：
Prompt: "修復登入 bug"
→ Agent 開始盲目搜尋

✅ 正確做法：
Prompt: "修復登入 bug。先用 codegraph_context 取得登入功能的上下文。"
→ Agent 直接獲得相關程式碼

❌ 錯誤做法：
Prompt: "將 findById 回傳型別改為 Optional<User>"
→ 直接修改，遺漏部分呼叫者

✅ 正確做法：
Prompt: "將 findById 回傳型別改為 Optional<User>。
先用 codegraph_impact 分析影響範圍，
確保所有呼叫者都被正確修改。"

❌ "幫我改善這個專案"
❌ "重構程式碼"
❌ "優化效能"

✅ "用 codegraph_search 找到 OrderService 中所有 public 方法，
   用 codegraph_callers 分析哪些方法的呼叫者最多，
   針對呼叫者最多的 3 個方法進行重構建議。"

❌ "分析 UserController 的呼叫鏈"
→ Agent 可能使用 grep + Read

✅ "使用 codegraph_trace 分析 UserController.getUser 到 UserRepository.findById 的呼叫鏈"
→ Agent 明確使用 CodeGraph

❌ "分析整個專案的所有 API、所有呼叫鏈、所有依賴關係"
→ Token 爆炸

✅ "分析 User 模組的 API 端點和呼叫鏈。
   僅關注 UserController 的 CRUD 操作。"
→ 聚焦範圍，控制 Token

❌ 每次都從零寫 Prompt

✅ 使用團隊 Prompt 庫（見 14.2 節），根據任務類型選擇模板：
   - 架構分析 → architecture/analyze-system.md
   - Bug 定位 → bugfix/locate-bug.md
   - 重構分析 → refactoring/impact-analysis.md

❌ 一次性的巨大 Prompt，試圖讓 Agent 一次完成所有事

✅ 分階段迭代：
   第 1 輪："用 codegraph_context 了解系統架構"
   第 2 輪："用 codegraph_trace 追蹤訂單流程"
   第 3 輪："基於以上分析，提出重構方案"

❌ 每次 CI 都跑完整測試套件（30 分鐘）

✅ 使用 codegraph affected 僅跑受影響的測試（3-5 分鐘）：
git diff --name-only | codegraph affected --stdin --quiet | xargs npm test

❌ 問題：每次修改程式碼後都需要手動 codegraph sync

✅ 解決方案：CodeGraph 採零設定架構，不需要設定檔。
MCP Server 啟動後會自動監視檔案變更（使用原生 OS 事件）。
# 若自動同步未生效，手動執行：
codegraph sync

❌ 同一個問題使用 codegraph_search + grep + file_search
   → 重複結果、浪費 Token

✅ 建立優先順序：
   1. codegraph_search（符號搜尋）
   2. codegraph_files（檔案結構）
   3. grep（僅用於 CodeGraph 不支援的搜尋，如正則表達式）

❌ 忽略 "N files need re-indexing" 警告

✅ 定期檢查：
codegraph status

# 如果有警告，立即同步：
codegraph sync

# 將 status 檢查加入開發工具腳本

❌ 問題：部分成員使用 CodeGraph、部分不使用
   → Token 使用差異大、PR Review 品質不一致

✅ 解決方案：
   1. 將 CodeGraph 安裝納入專案 onboarding 流程
   2. 在 copilot-instructions.md / CLAUDE.md 中寫入使用規範
   3. 定期檢查團隊 Token 使用報告
   4. 分享 CodeGraph 使用案例和最佳實踐

[任務描述]

請先用 codegraph_context 取得相關上下文，
確認影響範圍後再開始實作。
實作完成後用 codegraph_impact 驗證沒有遺漏。

# Phase 1: Architecture Agent
→ codegraph_context("理解訂單系統架構")
→ 產出架構分析報告

# Phase 2: Implementation Agent
→ codegraph_explore([需要修改的符號])
→ 基於架構報告實作程式碼

# Phase 3: Review Agent
→ codegraph_impact("修改的符號")
→ 檢查是否有遺漏的影響

# Phase 4: Test Agent
→ codegraph_callers("修改的符號")
→ 為所有呼叫路徑撰寫測試

Human: 請分析 OrderService 的完整業務邏輯

Claude Code (無 CodeGraph):
→ grep -r "OrderService" src/        # 搜尋符號 → ~200 行匹配
→ Read src/services/OrderService.java # 讀取完整檔案 → ~500 行
→ grep -r "createOrder" src/         # 搜尋方法 → ~80 行匹配
→ Read src/controllers/OrderController.java  # ~300 行
→ grep -r "OrderRepository" src/     # ~60 行匹配
→ Read src/repositories/OrderRepository.java # ~150 行
→ Read src/models/Order.java          # ~200 行
→ Read src/models/OrderItem.java      # ~100 行
→ Read src/services/PaymentService.java # ~400 行
→ Read src/services/InventoryService.java # ~350 行
...（繼續讀取更多檔案）

統計：
- Tool Calls: 18 次
- Input Tokens: ~85,000
- Output Tokens: ~12,000
- 總成本: ~$0.52

Human: 請分析 OrderService 的完整業務邏輯

Claude Code (有 CodeGraph):
→ codegraph_context("OrderService 業務邏輯分析")
  # 一次呼叫取得相關上下文 → 精準的符號列表 + 關係
→ codegraph_explore([OrderService 相關符號 IDs])
  # 一次呼叫取得所有相關程式碼 → 自適應大小
→ codegraph_trace("OrderController.createOrder", "OrderRepository.save")
  # 追蹤完整呼叫鏈

統計：
- Tool Calls: 3 次
- Input Tokens: ~35,000
- Output Tokens: ~10,000
- 總成本: ~$0.22

@workspace 請重構 UserProfile 元件，將表單驗證邏輯提取為共用 Hook

Copilot (無 CodeGraph):
→ 搜尋 UserProfile → 多個檔案匹配
→ Read UserProfile.tsx → ~400 行
→ Read UserProfileForm.tsx → ~300 行
→ 搜尋其他使用相同驗證的元件
→ Read RegistrationForm.tsx → ~350 行
→ Read SettingsForm.tsx → ~280 行
→ Read types/user.ts → ~100 行
→ Read hooks/useForm.ts → ~200 行
→ Read utils/validation.ts → ~150 行
...

統計：
- Tool Calls: 14 次
- 讀取的程式碼行數: ~2,300 行
- Token 消耗: ~72,000

@workspace 請重構 UserProfile 元件，將表單驗證邏輯提取為共用 Hook。
使用 codegraph_search 找到相關元件，用 codegraph_explore 查看程式碼。

Copilot (有 CodeGraph):
→ codegraph_search("UserProfile")
  # 精確找到元件定義
→ codegraph_callers("validateForm")
  # 找到所有使用驗證邏輯的元件
→ codegraph_explore([UserProfile, validateForm, 相關元件])
  # 一次取得所有相關程式碼，自適應大小

統計：
- Tool Calls: 3 次
- 讀取的程式碼行數: ~800 行（精準片段）
- Token 消耗: ~28,000

每月 Token = 20 人 × 22 天 × 150K = 66M tokens
Input: 52.8M × $15/1M = $792
Output: 13.2M × $75/1M = $990
月度總成本 = $1,782

每月 Token = 20 人 × 22 天 × 65K = 28.6M tokens
Input: 22.88M × $15/1M = $343.20
Output: 5.72M × $75/1M = $429
月度總成本 = $772.20

# Enterprise AI Coding Standard v1.0

## 1. 總則

### 1.1 目的
本標準規範企業內使用 AI 輔助開發的流程、工具和最佳實踐，
確保開發效率、程式碼品質和資訊安全的平衡。

### 1.2 適用範圍
適用於所有使用 AI Agent（Claude Code, GitHub Copilot, 其他 MCP 相容 Agent）
進行軟體開發的團隊和專案。

## 2. 工具標準

### 2.1 核准工具清單
| 類別 | 工具 | 版本 | 狀態 |
|------|------|------|------|
| 知識圖譜 | CodeGraph | ≥ 0.9.7 | 必裝 |
| AI Agent | Claude Code | Latest | 核准 |
| AI Agent | GitHub Copilot | Latest | 核准 |
| MCP Server | CodeGraph MCP | 內建 | 必裝 |

### 2.2 禁止工具
- 未經安全審查的第三方 MCP Server
- 非公司核准的 AI Agent
- 任何將程式碼傳送到公司外部的工具（除核准工具外）

## 3. 使用規範

### 3.1 CodeGraph 使用
- 所有程式碼專案必須建立 CodeGraph 索引
- Agent 必須優先使用 CodeGraph MCP 工具
- 修改程式碼前必須執行 codegraph_impact 分析

### 3.2 Prompt 規範
- 使用團隊 Prompt Library 中的模板
- 禁止在 Prompt 中包含敏感資訊
- 大型分析任務需事先評估 Token 消耗

### 3.3 Token 預算
| 等級 | 每日上限 | 審批 |
|------|---------|------|
| 開發者 | 500K tokens | 免審批 |
| 大型任務 | 2M tokens | Tech Lead 審批 |
| 專案級分析 | 10M tokens | Manager 審批 |

## 4. 安全規範

### 4.1 資料分類
| 分類 | 說明 | AI 使用限制 |
|------|------|-----------|
| Public | 開源程式碼 | 無限制 |
| Internal | 一般業務程式碼 | 核准 Agent 可用 |
| Confidential | 含商業邏輯的核心程式碼 | 需加密或脫敏 |
| Restricted | 含密碼/金鑰的配置 | 禁止傳給 AI |

### 4.2 Code Review 要求
- AI 產生的程式碼必須經過至少 1 位人工 Reviewer
- 安全相關程式碼需 2 位 Reviewer（含 Security Champion）
- AI 產生的 SQL 必須通過 SQL Injection 審查

## 5. 品質標準

### 5.1 測試覆蓋
- AI 產生的功能程式碼必須有對應的單元測試
- 使用 codegraph affected 確認測試完整性
- 重構後執行完整回歸測試

### 5.2 文件要求
- 使用 CodeGraph 進行的重大分析需在 PR 中記錄
- 架構變更需更新相關文件
- Prompt 範例需回饋至 Prompt Library