外部工具設定指南

本文件說明如何在各平台配置搭配本 kit 使用的外部工具：推薦的 Serena、GitNexus，以及選用的 Superpowers。

本 kit 自身的安裝方式不在這裡，各資料夾的 README 已載明對應平台的複製路徑： rules/README.md · skills/README.md

前置需求

工具	需求	安裝
Serena	uv / uvx（Python 工具執行器）；Python 3.13 由 `uvx -p 3.13` 自動下載	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
GitNexus	Node.js ≥ 18（建議用 nvm 管理）	`npm install -g gitnexus`
Superpowers	依平台而異，見下方對應章節	—

MCP 設定檔位置

Serena 與 GitNexus 都以 MCP server 形式整合，各平台的設定檔與結構如下：

平台	設定檔	頂層鍵
Codex	透過 `codex mcp add` 指令登錄，寫入 `~/.codex/config.toml`（TOML）	`mcp_servers`
Claude Code	透過 `claude mcp add` 指令登錄	—
OpenCode	`~/.config/opencode/config.json`	`mcp`
Antigravity	`~/.gemini/config/mcp_config.json`	`mcpServers`
Cursor	`~/.cursor/mcp.json`	`mcpServers`

Antigravity 與 Cursor 的 JSON 格式完全相同，可直接互相沿用。

Antigravity 的路徑遷移：~/.gemini/antigravity/ 底下的 mcp_config.json 與 skills/ 是 2026-05-20 遷移前的舊路徑，現行設定統一在 ~/.gemini/config/，由 Antigravity、Antigravity IDE 與 Antigravity CLI（agy）共用。從舊版升級時記得比對兩處內容，避免遺漏遷移後才加入的 server。

設定 Serena（MCP）

Serena 是 LSP 層級的程式碼分析 MCP 伺服器，支援符號搜尋、重構、診斷。

首次啟動時 uvx 會下載並編譯 Serena 與相依套件，耗時數分鐘屬正常。

Claude Code（user scope，全部專案可用）：

claude mcp add serena -s user -- \
  uvx -p 3.13 --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide --project-from-cwd

Codex（使用 Serena 專為 Codex 準備的 codex context，排除與 Codex 內建檔案／shell 工具重複的工具）：

codex mcp add serena -- \
  uvx -p 3.13 --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context codex --project-from-cwd

首次啟動因 uvx 下載而超過 Codex 的 MCP 啟動逾時時，在 ~/.codex/config.toml 的 [mcp_servers.serena] 加上 startup_timeout_sec = 120。

OpenCode（config.json 的 mcp 區塊）：

{
  "mcp": {
    "serena": {
      "type": "local",
      "timeout": 60000,
      "command": [
        "uvx", "-p", "3.13",
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide",
        "--project-from-cwd"
      ]
    }
  }
}

Antigravity / Cursor（mcpServers 區塊）：

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide",
        "--open-web-dashboard", "False"
      ],
      "disabled": false
    }
  }
}

使用注意事項：

首次進入新專案時，Serena 規定要先呼叫 initial_instructions 工具讀取「Serena Instructions Manual」，再開始任何 coding 任務
進入大型專案後可執行 onboarding 建立索引，可大幅加速後續符號查詢
已索引的 memory 存放於專案內 .serena/，建議加入 .gitignore

設定 GitNexus（MCP + Hook）

GitNexus 是程式碼知識圖譜分析工具，支援影響分析、路由對應、API 形狀檢查。

1. 安裝 CLI 並建立索引

npm install -g gitnexus
gitnexus --version
gitnexus analyze .        # 於專案根目錄執行，產生 .gitnexus/（建議加入 .gitignore）

2. 登錄 MCP server

Codex：

codex mcp add gitnexus -- gitnexus mcp

Claude Code：

claude mcp add gitnexus -s user -- gitnexus mcp

OpenCode（config.json 的 mcp 區塊）：

{
  "mcp": {
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

Antigravity / Cursor（mcpServers 區塊）：

{
  "mcpServers": {
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

3. 安裝 Hook（僅 Claude Code）

GitNexus 的 hook 會在 Grep / Glob / Bash 之前自動把對應的圖譜上下文塞給 agent，並在 Bash 之後偵測索引是否過期。請將官方 hook 腳本（取自 GitNexus 專案）放到 ~/.claude/hooks/gitnexus/gitnexus-hook.cjs，並在 ~/.claude/settings.json 加上：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Grep|Glob|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$HOME/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Enriching with GitNexus graph context..."
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$HOME/.claude/hooks/gitnexus/gitnexus-hook.cjs\"",
            "timeout": 10,
            "statusMessage": "Checking GitNexus index freshness..."
          }
        ]
      }
    ]
  }
}

⚠️ 其他平台無 hook 等價機制：OpenCode / Antigravity / Cursor 都沒有與 Claude Code PreToolUse / PostToolUse 對應的 hook 系統，因此「自動補圖譜上下文」僅在 Claude Code 中可用。其他平台需透過 gitnexus-* skills 主動呼叫。

Codex 有同名事件的 hook（~/.codex/hooks.json），但上述腳本以 Claude Code 的 Grep / Glob / Bash 工具為對象，尚未驗證能在 Codex 運作；在驗證前同樣改用 skills 主動呼叫。

使用注意事項：

配套 skills：安裝後可用 gitnexus-exploring、gitnexus-debugging、gitnexus-impact-analysis、gitnexus-pr-review、gitnexus-refactoring、gitnexus-cli、gitnexus-guide
索引重建：commit 大量檔案或重構後，Claude Code 的 hook 會自動提醒；其他平台需手動執行 gitnexus analyze .

設定 Superpowers

Superpowers 是強化 AI 開發流程的能力包，提供 brainstorming、TDD、debugging、subagent-driven development、verification 等流程型 skills。本 kit 預設不使用，各節點走內建流程；已安裝時，只有使用者在對話中明確指定（例如「用 brainstorming 釐清」）才會改用對應 skill，核准、產物位置與完成 gate 仍依本 kit：

Superpowers skill	對應節點	預設的內建流程
`brainstorming`	`new-issue`	依 `agents/acceptance.md` 核對來源並處理必要缺項
`writing-plans`	`decompose`	內建 Phase / Task 與覆蓋規則；指定 writing-plans 時，產物仍寫入 issue 的唯一任務來源
`test-driven-development`	`execute-task`	內建雙迴圈狀態機
`requesting-code-review`	`review`	宿主原生 subagent / task；沒有獨立 reviewer 能力時阻塞
`verification-before-completion`	`create-pr`	依 `agents/review-evidence.md` 核對範圍與有效證據

改為預設不使用的依據與驗證狀態見規則驗證狀態。以下安裝步驟供已決定使用的人參考。

Claude Code（官方 plugin marketplace）：

/plugin marketplace add anthropics/claude-plugins-official
/plugin install superpowers@claude-plugins-official

確認 ~/.claude/settings.json 含：

{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true
  }
}

安裝內容位於 ~/.claude/plugins/cache/claude-plugins-official/superpowers/<version>/。

OpenCode（直接從 git URL 安裝，編輯 ~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "superpowers@git+https://github.com/obra/superpowers.git"
  ]
}

啟動 OpenCode 後會自動透過 bun / npm 安裝。

Antigravity / Cursor（無 plugin marketplace，需手動安裝）：

# 1. 取得 Superpowers 原始碼到任一位置
git clone https://github.com/obra/superpowers.git ~/Tools/superpowers

# 2. 將 skills 連結（或複製）到平台的 skills 目錄
ln -s ~/Tools/superpowers/skills/* ~/.gemini/config/skills/        # Antigravity
ln -s ~/Tools/superpowers/skills/* ~/.cursor/skills/               # Cursor

建議使用 symlink 而非複製，更新時只需拉取來源：

# 更新 Superpowers（symlink 安裝時）
cd ~/Tools/superpowers && git pull

# 上游若「新增」技能才需要補連結；既有連結不受影響
ln -sfn ~/Tools/superpowers/skills/* ~/.gemini/config/skills/

symlink 指向來源目錄，git pull 後既有技能的內容即刻生效，不必重新連結；只有上游新增技能時原本的 skills/* 展開清單才會漏掉它。補連結指令是冪等的——-f 覆蓋既有連結、-n 避免連進目錄內部，重複執行不會產生巢狀，也不會動到同目錄下非 Superpowers 的技能。

Claude Code 與 OpenCode 走各自的 plugin 機制自動更新，不需要這份 clone。

使用注意事項：

核心原則：「若有 1% 機率某個 skill 適用，就必須先呼叫它」— 詳見 using-superpowers。這會讓 Superpowers 在沒被要求時也自行接手流程，與本 kit「明確要求才使用」的預設衝突；只想在指定時使用的話，平常保持停用（例如 Claude Code 的 enabledPlugins 設為 false），需要時再啟用
多數 skills 為流程型（rigid），會強制依步驟執行，例如 TDD 必定先寫測試
Skill 優先順序：先用 process skill（brainstorming、debugging），再用 implementation skill

完整設定檔範例

把 Serena 與 GitNexus 一起放進去的最小可運作設定。

Codex — ~/.codex/config.toml：

[mcp_servers.serena]
command = "uvx"
args = ["-p", "3.13", "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex", "--project-from-cwd"]
startup_timeout_sec = 120

[mcp_servers.gitnexus]
command = "gitnexus"
args = ["mcp"]

OpenCode — ~/.config/opencode/config.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "serena": {
      "type": "local",
      "timeout": 60000,
      "command": [
        "uvx", "-p", "3.13",
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide",
        "--project-from-cwd"
      ]
    },
    "gitnexus": {
      "type": "local",
      "command": ["gitnexus", "mcp"]
    }
  }
}

Antigravity / Cursor — mcp_config.json 或 mcp.json：

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide",
        "--open-web-dashboard", "False"
      ],
      "disabled": false
    },
    "gitnexus": {
      "command": "gitnexus",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

驗證

平台	驗證方式
Codex	`codex mcp list`，預期 `serena` 與 `gitnexus` 皆為 `enabled`；session 內輸入 `/mcp` 查看已連線的工具
Claude Code	`claude mcp list`，預期 `serena` 與 `gitnexus` 皆顯示 `✓ Connected`；輸入 `/` 應看到 `superpowers:*` 系列指令
OpenCode	輸入 `@` 應列出 MCP 工具；plugin 載入訊息會出現在啟動 log
Antigravity	檢查 chat 面板下方的 MCP server 狀態列
Cursor	Settings → MCP 應看到 `serena` 與 `gitnexus` 顯示為綠燈

常見問題

設定改了沒生效：MCP 設定在啟動時載入。Codex 需開新 session；Antigravity 需執行 Developer: Reload Window；Cursor 可按 Cmd/Ctrl + Shift + P → Cursor: Reload MCP Servers
~/.cursor/ vs ~/.config/Cursor/：前者是 Cursor CLI agent 設定（含 MCP、commands、skills），後者是 VS Code 風格的 IDE 偏好設定（settings.json、keybindings.json）

移除

Claude Code：

claude mcp remove serena -s user
claude mcp remove gitnexus -s user
npm uninstall -g gitnexus
rm -rf ~/.claude/hooks/gitnexus/          # 並從 settings.json 移除 hook 區段
/plugin uninstall superpowers@claude-plugins-official

Codex：

codex mcp remove serena
codex mcp remove gitnexus

其他平台：從對應的 MCP 設定檔移除 serena / gitnexus 區塊，並刪除 Superpowers 的 symlink 與 clone 目錄。

參考連結

Serena GitHub · uv 官方文件
GitNexus GitHub · Claude Code Hooks 文件
Superpowers GitHub · Claude Plugins marketplace
平台官方文件：Codex · Claude Code · OpenCode · Antigravity · Cursor

Navigation Menu

Repository navigation

外部工具設定指南

前置需求

MCP 設定檔位置

設定 Serena（MCP）

設定 GitNexus（MCP + Hook）

設定 Superpowers

完整設定檔範例

驗證

常見問題

移除

參考連結

FilesExpand file tree

tools.md

Latest commit

History

tools.md

File metadata and controls

外部工具設定指南

前置需求

MCP 設定檔位置

設定 Serena（MCP）

設定 GitNexus（MCP + Hook）

設定 Superpowers

完整設定檔範例

驗證

常見問題

移除

參考連結