記錄一些使用 Claude Code 過程中踩到的坑，希望幫後來者少走彎路。

# allowed-tools 多指令

要讓 skill 完整跑完而不跳 permission prompt，需要在 allowed-tools 中把用到的指令都列入允許。但若指令包含 &&，例如：

cd frontend && npx playwright test e2e/specs/appointment-pet-grooming.spec.ts

不能用一條 allowed-tools 規則涵蓋整個指令：

# 這樣會失敗
allowed-tools:
  - Bash(cd frontend && npx playwright test *)

必須拆成兩條分別允許：

# 正確做法
allowed-tools:
  - Bash(cd frontend)
  - Bash(npx playwright test *)

Claude Code 的 glob 比對是針對單一指令段，無法跨越 && 做匹配。

官方文件：Claude Code Permissions

---

# rtk permission

安裝 rtk（Rust Token Killer）之後，Claude Code 執行指令時會頻繁跳出 permission prompt。需要在 settings.json 加上允許規則：

{
  "permissions": {
    "allow": ["Bash(rtk *)"]
  }
}

沒加這條，rtk 每次被 hook 觸發就會被攔下來。

另外，rtk hook 執行時會把指令歷史寫入 ~/.local/share/rtk/，需要在 settings.json 加上寫入白名單，否則 hook 會因寫入被 sandbox 阻擋而失敗：

{
  "permissions": {
    "allow": ["Bash(rtk *)"],
    "allowWrite": ["/home/your-username/.local/share/rtk"]
  }
}

JSON 不支援 shell 變數，~ 也不會被展開，需要填完整絕對路徑。

官方資源：rtk-ai.app | GitHub

---

# GitNexus post-commit hook

GitNexus 會對 codebase 建立知識圖譜供 Claude 查詢。為了讓圖譜保持最新，可以設定 post-commit hook，讓每次 commit 後自動觸發重新分析，不需要手動執行。hook 範例如下：

#!/bin/bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" --no-use
GITNEXUS=$(command -v gitnexus 2>/dev/null)
[ -z "$GITNEXUS" ] && exit 0
"$GITNEXUS" analyze --no-stats --skip-agents-md > /dev/null 2>&1 &

這裡有幾個重點：

• 手動載入 nvm 環境，確保 gitnexus 指令找得到
• 用 command -v 確認指令存在再執行，避免 hook 報錯
• 加上 & 讓分析在背景執行，不阻塞 commit 流程

commit 相關的 skill 還需要在 SKILL.md 中用自然語言指示 Claude 呼叫 git commit 時帶上 dangerouslyDisableSandbox: true，否則 hook 會被 sandbox 殺掉。

原因是 Claude Code 使用 bwrap（bubblewrap）做 Linux namespace-based sandbox，teardown 時會對整個 process group 發送 SIGKILL，包含 hook 裡用 & fork 出去的背景子 process。光是修好 NVM 路徑讓 gitnexus 找得到還不夠——commit 本身若還跑在 sandbox 裡，背景 process 就會一起被殺。

NVM 修正和 dangerouslyDisableSandbox 兩個條件缺一不可。兩個都設好後，可以用 gitnexus status 確認 hook 有沒有正確觸發，看 indexed 時間是否更新到剛才的 commit 時間。

官方資源：GitHub - GitNexus

---

本文使用 Codex 輔助撰寫。